How Maka Executes Subagents with Worktree-Backed Child Sessions

Maka executes subagents by provisioning a Git worktree lease, binding it to a child Session header via SubagentWorkspaceBinding, and running the child with its working directory set to the isolated worktree path for filesystem isolation.

Apache Maka’s subagent architecture allows a parent Session to spawn lightweight, isolated child agents without duplicating the entire repository. By leveraging Git worktrees, each subagent receives an independent filesystem view while sharing the object database with the host project. This article explains how Maka executes subagents using worktree-backed child Sessions, referencing the actual implementation in the apache/maka repository.

The Three-Stage Execution Flow

Maka’s subagent execution follows a strict three-stage lifecycle that keeps Git implementation details hidden from the graph scheduler while providing POSIX-level isolation for the child process.

Stage 1: Provisioning the Worktree Lease

Before spawning a subagent, the host validates that the current project can support isolated worktrees. The SubagentWorktreeExecutor interface—implemented in packages/storage/src/git-worktree-child-executor.ts—handles this validation through the isAvailable() method.

When available, the host creates a unique lease identifier that follows the strict pattern /^subagent_worktree_[a-f0-9]{32}$/. The executor then provisions the worktree under the host’s common directory, checks out the base commit specified in the input, and creates a host-owned branch named maka/subagent/<hash> that the child may manipulate.

The result is a SubagentWorkspaceBinding object (defined in packages/core/src/subagent-workspace.ts lines 35-45) that immutably records the worktree path, lease ID, and base commit reference.

Stage 2: Binding the Workspace to the Session Header

The lease information is wrapped into a SubagentWorkspaceBinding and attached to the child Session’s header as the subagentWorkspace field. This binding is constructed alongside two other subagent-specific metadata fields:

• subagentParent – Identifies the spawning Session with kind: 'subagent' and references the parent graph
• subagentRuntime – Contains runtime metadata such as the preset ID and tool list
• subagentWorkspace – The binding from Stage 1 containing the worktree path and lease details

The child Session’s cwd (current working directory) is explicitly set to binding.worktreePath, ensuring that all file operations automatically target the isolated checkout. This header assembly logic is demonstrated in the test suite at packages/runtime/src/__tests__/session-manager.test.ts (lines 898-1001).

Stage 3: Executing in the Isolated Worktree

Once the header is persisted to the session-store (SQLite), the child Session boots using the standard runtime engine. Because the runtime initializes process.cwd() to the worktree path, tools like read_file or write_file operate entirely within the isolated directory.

The scheduler remains unaware of Git specifics; it simply sees a normal Session with a distinct working directory. After the subagent completes its task, the host may optionally capture the delta between the modified worktree and the original base commit.

Implementation Details in SubagentWorktreeExecutor

The concrete implementation in packages/storage/src/git-worktree-child-executor.ts provides four critical operations that manage the worktree lifecycle.

First, the provision() method validates the lease ID format, creates the physical worktree directory, and checks out the base commit while establishing the maka/subagent/<hash> branch. Second, the isAvailable() check ensures the host filesystem supports worktree creation before attempting allocation.

Third, after the child Session terminates, capturePatch() generates a patch representing the filesystem delta between the current worktree state and the original base commit. This allows the parent Session to review or merge changes without direct filesystem access to the child’s working directory.

Finally, retire() performs cleanup by removing the Git worktree and releasing the lease ID, preventing orphaned directories from accumulating on the host system.

Session Header Construction

When a parent Session invokes the internal agent_spawn API (or related utilities in packages/runtime/src/subagent-tools.ts), the runtime constructs a header object that distinguishes the child as a subagent:

const childHeader = {
  // Standard Session fields...
  cwd: binding.worktreePath,
  subagentParent: { kind: 'subagent', graph: parent.graph },
  subagentRuntime: {
    presetId: 'fast-reader',
    agentName: 'Fast reader',
    // Additional runtime metadata
  },
  subagentWorkspace: binding,
};

This header is saved to the session-store via sessionStore.saveHeader() and subsequently loaded by the child Session’s runtime in packages/runtime/src/session-manager.ts. The presence of subagentWorkspace signals to the execution environment that filesystem operations should remain confined to the leased worktree.

Capturing Deltas and Lifecycle Management

The worktree pattern enables safe experimentation and cleanup. After the child Session finishes execution, the host can capture any modifications:

// Capture the delta after the child finishes
const patch = await executor.capturePatch(binding);

// Application-specific logic to merge or review the patch

// Clean up the worktree and release the lease
await executor.retire(binding);

The capturePatch method (implemented in git-worktree-child-executor.ts lines 60-82) computes the diff between the worktree’s current state and the binding.baseCommit, returning a standard Git patch that the parent can apply to its own working directory if desired.

This design provides isolation (each subagent sees only its own files), performance (worktrees share the parent repository’s object database), and safety (the host controls lease lifecycle and cleanup).

Summary

• Maka uses SubagentWorktreeExecutor (in git-worktree-child-executor.ts) to provision Git worktree leases with validated IDs and isolated branch names.
• The SubagentWorkspaceBinding (defined in core/subagent-workspace.ts) attaches worktree metadata to child Session headers via the subagentWorkspace field.
• Child Sessions execute with cwd set to the worktree path, providing automatic filesystem isolation without cloning the repository.
• The host captures deltas using capturePatch() and cleans up resources via retire() to prevent orphaned worktrees.
• Key header fields (subagentParent, subagentRuntime, subagentWorkspace) distinguish subagent Sessions from standard Sessions in the runtime.

Frequently Asked Questions

How does Maka ensure subagents do not corrupt the parent repository?

Maka ensures isolation by binding each subagent to a dedicated Git worktree with a unique lease ID and branch name (maka/subagent/<hash>). The child Session’s working directory is locked to this worktree path, so all file operations occur in the isolated checkout. The parent repository’s working directory remains untouched, and changes are only propagated back if the host explicitly applies a patch captured via capturePatch().

What is the format of the lease ID for subagent worktrees?

The lease ID must match the regular expression /^subagent_worktree_[a-f0-9]{32}$/, producing strings like subagent_worktree_a1b2c3d4e5f6.... This format is strictly validated in git-worktree-child-executor.ts during the provision() call to ensure unique, predictable identifiers for lease management and cleanup tracking.

Can multiple subagents run simultaneously on the same host?

Yes. Because each subagent receives its own worktree lease and distinct branch name under the maka/subagent/ namespace, multiple child Sessions can execute concurrently within the same parent project. Each maintains an independent filesystem view while sharing the underlying Git object database for efficiency.

Where is the subagent header logic tested in the codebase?

The construction and validation of subagent headers—including the assembly of subagentParent, subagentRuntime, and subagentWorkspace fields—is tested in packages/runtime/src/__tests__/session-manager.test.ts, specifically around lines 898-1001. These tests verify that child Sessions correctly inherit worktree bindings and execute within the expected directory context.

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