# How Maka Executes Subagents with Worktree-Backed Child Sessions

> Learn how Maka executes subagents using worktree-backed child sessions for robust filesystem isolation. Discover the process of provisioning Git worktrees and binding them to child sessions.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-31

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/subagent-tools.ts)), the runtime constructs a header object that distinguishes the child as a subagent:

```typescript
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`](https://github.com/apache/maka/blob/main/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:

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.