Allow concurrent writable Subagent calls with a worktree contract
@JAORMX is already working on this.
Since Sep 3, 2026.
- Dominant language
- Go
- Stars
- 152
- Forks
- 16
- Avg merge
- 14h 48m
- Merged PRs (30d)
- 536
Description
Problem
Subagent calls with mode: "read-write" currently participate in the parent-mutation serialization seam. That blocks an orchestrator from running independent implementation workers concurrently.
The current restriction is safe, but it is too rigid for the normal agent-workflow case: the orchestrator can create one Git worktree per task, assign each worker a branch and worktree path, and instruct the worker to modify only that worktree. This is how other agent harnesses commonly coordinate parallel implementation work.
Decision
Allow writable Subagent calls to overlap. Make worktree separation a soft, model-visible orchestration contract, rather than a runtime-managed isolation system.
For concurrent implementation workers:
- The parent/orchestrator creates one Git worktree and task branch per worker, normally below
.scratch/worktrees/. - The parent includes the assigned worktree path and branch in each worker brief.
- Each worker performs file edits, commands, tests, and commits only in its assigned worktree.
- The orchestrator collects worker branches and integrates them serially into the accumulator branch.
This is not a security sandbox and must not be described as one. mecatl does not need to provision, validate, bind, or attest a worktree on behalf of a Subagent. If the model violates the contract, concurrent workers can still conflict or overwrite work; normal Git review, branches, and serial integration are the recovery mechanisms.
mode: "read-write" remains the direct-write mechanism. A single focused child may write directly to the parent workspace. Concurrent children are responsible for respecting the worktree discipline supplied in their prompts.
Scope
- Remove the blanket dispatch serialization applied to writable Subagent calls.
- Preserve dispatch serialization for tools that actually perform an automatic merge into the parent workspace.
- Update the filesystem-capable Subagent tool description to explain the worktree coordination contract, its limits, and the direct-write vs. concurrent-worker distinction.
- Keep the no-filesystem description free of worktree and writable-execution claims.
- Update
/plan-orchestrateand thetdd-workercontract so parallel implementation waves create and assign a worktree per task, include the path in the worker brief, and require workers to stay inside it. - Add a new ADR superseding only ADR 0077's blanket writable-Subagent serialization decision, and update architecture/user documentation.
Non-goals
- No new Subagent mode, schema field, environment handle, mutation-domain identity, or caller-provided filesystem capability.
- No runtime validation, binding, provisioning, or attestation of worker worktrees.
- No force-copy fork, clone backend, or new
EnvironmentForkerbehavior. - No automatic multi-worker merge or apply registry.
- No change to Parallel or Team.
- No claim that Git worktrees protect against arbitrary Bash, shared Git administration state, or hostile code.
Acceptance criteria
- Two
mode: "read-write"Subagent calls can overlap in one dispatch batch. - Existing read-only dispatch behavior remains concurrent.
- Operations that automatically merge into the parent workspace remain dispatch-serial.
- The normal Subagent tool description tells the model to create and assign separate worktrees before concurrent writable work, says the contract is not runtime-enforced, and distinguishes it from a single direct-write child.
- The no-fs Subagent description contains no worktree or writable-execution guidance.
- The plan-orchestration and TDD-worker contracts require one assigned worktree per concurrent task and prohibit touching another task's or the orchestrator's checkout.
- Tests cover writable overlap, merge serialization, and both filesystem/no-fs descriptions.
- ADR, architecture, and user-facing documentation describe the soft contract and its limits consistently.
Delivery
Implement in a dedicated Git worktree on a feature branch, open one PR, and merge only after review and green CI.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.