How Agent Graph Git Worktree Isolation Enables Sub‑Agent Execution in Apache Maka

Maka runs each sub-agent inside an isolated Git worktree managed by GitWorktreeChildExecutor, eliminating the need for full repository clones while guaranteeing that filesystem changes never leak between parent and child sessions.

Apache Maka leverages agent graph Git worktree isolation to enable secure, parallel sub-agent execution within the same repository. When a parent session spawns a child, the system creates a managed worktree rather than cloning the entire repository, providing filesystem isolation through Git's native worktree mechanism. This architecture ensures that sub-agents operate in deterministic, sandboxed environments without corrupting the parent's workspace or Git index.

The GitWorktreeChildExecutor Lifecycle

Allocation of the Sub-Agent Root

The isolation process begins when GitWorktreeChildExecutor is instantiated with a dedicated root directory for sub-agent worktrees, conventionally located at subagent-worktrees beneath the storage root. This directory serves as the parent for all dynamically created worktrees during the agent graph execution.

Provisioning the Isolated Worktree

When a parent session requests a child session, the executor receives a unique lease identifier (subagent_worktree_<hash>) and provisions a new worktree using Git's native commands. In packages/storage/src/git-worktree-child-executor.ts, the executor invokes runGit with the ['worktree', 'add', …] command to create a new worktree for the required branch under the designated root. This operation is significantly faster than cloning because Git hard-links the object database rather than copying it.

Filesystem Isolation Mechanics

Each provisioned worktree maintains its own .git directory that points to the same gitCommonDir (shared object database) while keeping the working tree in a separate filesystem directory. This structure guarantees that file changes made by the sub-agent remain confined to its isolated directory. The parent's working directory and Git index remain untouched, preventing any cross-contamination between agent sessions.

Lease Binding and Verification

After creation, the executor stores a lease configuration in the worktree's git config using the branchLeaseConfigKey. This lease binds the worktree to the specific sub-agent session. When a sub-agent starts, the executor calls inspectOwnedWorktree to verify the lease and branch match the expected values. If the worktree is missing, points to the wrong branch, or has an altered lease, the system throws an error to prevent unauthorized access or stale data usage.

Cleanup and Resource Reclamation

Upon child session termination, the executor removes the worktree entry from both the filesystem and Git's worktree registry. This cleanup, implemented in the executor's disposal logic, ensures no stray files or orphaned worktrees remain on the system after sub-agent execution completes.

Safety and Performance Benefits

Agent graph Git worktree isolation provides four critical advantages for distributed agent execution:

• Deterministic Environment: Each sub-agent runs against a clean copy of the repository at the exact commit required, eliminating "works on my machine" variables.
• Filesystem Safety: Changes made within a sub-agent's worktree cannot corrupt the parent's files or its Git index, maintaining the integrity of the primary session.
• Parallel Execution: Multiple sub-agents can spawn simultaneously, each operating within its own isolated worktree without filesystem conflicts.
• Rapid Provisioning: Adding a worktree requires only hard-linking the object database, making sub-agent startup orders of magnitude faster than full repository clones.

Implementation in the Maka Codebase

Core Executor Logic

The primary implementation resides in packages/storage/src/git-worktree-child-executor.ts, which handles allocation, provisioning, and validation of isolated worktrees. The executor integrates with packages/storage/src/project-catalog.ts to resolve project locations and distinguish between normal paths and Git worktree roots, while packages/storage/src/managed-workspace-owner.ts defines the "managed_worktree" mode that enables this isolation pattern.

UI Integration

The user interface reflects worktree sessions through the SessionListPanel component in packages/ui/src/session-list-panel.tsx. This component receives a worktreeSessionIds set to identify which sessions belong to worktrees, displaying a special "Git worktree" ARIA label defined by worktreeAriaLabel in packages/ui/src/conversation-copy.ts for accessibility compliance.

Practical Code Examples

The following TypeScript demonstrates provisioning a sub-agent worktree and verifying ownership:

// Allocate a sub-agent executor (the root is a directory under the storage root)
const executor = new GitWorktreeChildExecutor(
  join(storageRoot, 'subagent-worktrees')
);

// Provision a new worktree for a child session
await executor.provisionResolved(
  leaseId,
  source.git!.worktreeRoot,          // parent worktree root
  {
    sourceSessionId: parentSession.id,
    branch: 'feature/xyz',
    gitCommonDir: source.git!.gitCommonDir,
  }
);

// Inside the sub-agent, verify the worktree lease before using it
const inspected = await this.inspectOwnedWorktree(binding.worktreePath);
const lease = await gitConfigGet(
  inspected.worktreePath,
  branchLeaseConfigKey(binding.branch)
);
if (!lease) throw new Error('Subagent worktree lease is unavailable');

To mark a session as belonging to a worktree in the UI:

// UI – mark a session as belonging to a worktree
<SessionListPanel
  worktreeSessionIds={new Set(['proj-worktree'])}
  /* …other props */
>
  {/* items … */}
</SessionListPanel>

Summary

• Apache Maka uses GitWorktreeChildExecutor to create isolated Git worktrees for sub-agent execution instead of cloning repositories.
• Each worktree has its own working directory while sharing the object database via gitCommonDir, ensuring filesystem isolation.
• Lease verification through inspectOwnedWorktree and branchLeaseConfigKey prevents unauthorized access and detects configuration drift.
• Automatic cleanup removes worktrees when sessions end, preventing resource leakage.
• The UI exposes worktree sessions through SessionListPanel with appropriate ARIA labeling for accessibility.

Frequently Asked Questions

How does Git worktree isolation compare to repository cloning for sub-agents?

Git worktree isolation is substantially faster and more storage-efficient than cloning. While cloning duplicates the entire object database, worktrees use hard-links to share the parent's gitCommonDir, requiring only minimal additional disk space for the new working tree. This allows sub-agents to start almost instantly compared to the network and disk I/O overhead of a full clone.

What prevents a sub-agent from modifying the parent's working directory?

The isolation is enforced at the filesystem level through Git's worktree mechanism. Each worktree has its own separate working directory, and the GitWorktreeChildExecutor ensures the sub-agent's processes are bound to that specific path. While the sub-agent can read from the shared object database, any writes to the working tree affect only its isolated directory, leaving the parent's workspace untouched.

How does Maka verify that a sub-agent owns its assigned worktree?

The executor stores a unique lease identifier in the worktree's git configuration using branchLeaseConfigKey. When the sub-agent starts, inspectOwnedWorktree checks this lease against the expected value and validates that the branch matches the requested configuration. If verification fails—indicating tampering, corruption, or stale data—the system throws an error before the sub-agent executes any operations.

Can multiple sub-agents run simultaneously using this isolation method?

Yes. Agent graph Git worktree isolation explicitly supports parallelism by design. Each sub-agent receives its own independent worktree with a unique lease, allowing multiple agents to execute concurrently against different branches or commits within the same repository. The shared object database remains read-only during normal operations, while each agent writes to its distinct working directory without filesystem conflicts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}