Repository navigation
feat(sub-agents): one kind of sub-agent, with an optional workspace that copies the whole project - #281
Draft
daniel-kurzynski wants to merge 9 commits into
Draft
feat(sub-agents): one kind of sub-agent, with an optional workspace that copies the whole project#281daniel-kurzynski wants to merge 9 commits into
daniel-kurzynski wants to merge 9 commits into
Conversation
daniel-kurzynski
marked this pull request as draft
October 27, 2026 13:39
daniel-kurzynski
force-pushed
the
feat/sub-agent-workspaces
branch
from
October 28, 2026 10:20
a575fa4 to
2d13b3c
Compare
MCP tools were tagged only for the main agent's scopes, so sub-agents never saw them. Tag them for the sub-agent default scopes too; sub-agents share the parent's registry and session config, so the session's MCP on/off switches and :mcp: resources carry over.
Several agents can work in one tree at once, each with its own Explorer. Their read-modify-write sequences could interleave and silently drop an edit, and std::fs::write let readers see a truncated file. Writers now hold a process-wide per-path lock across read, apply, format and read-back, and files are replaced via a sibling temp file and rename (written through symlinks, keeping permissions).
In a git project a writing sub-agent now starts in a worktree created from a snapshot of the parent's tree (uncommitted and untracked work included, index and HEAD untouched). When it finishes, its changes are three-way merged into the parent's working tree, all or nothing, under the per-path write locks. On a conflict nothing is applied; the changes stay on a branch and the parent is told how to resolve them. A cancelled or failed sub-agent applies nothing and keeps partial changes on a branch. Writing sub-agents can therefore run in parallel and in the background. Outside git they still take turns in the shared tree.
With every sub-agent working in its own worktree (git projects) or under the per-file write locks (elsewhere), the read-only/default split is no longer needed for safety. spawn_agent loses its mode parameter (an old `mode` in saved sessions is ignored), SubAgentMode and the SubAgentReadOnly scope go, every sub-agent gets the full tool scope and may run in the background, and MCP tools are offered to sub-agents.
The merge compared content only, so a sub-agent's chmod alone was dropped, and a content merge took the sub-agent's mode even when only the parent had changed it. Compare content and executable bit, and let the side that changed the bit win. A path deleted here but changed by the sub-agent is now reported as such instead of as overlapping edits.
Every sub-agent in a git project got its own worktree, including ones that only research: a full checkout per sub-agent, and builds there start without any build outputs. spawn_agent now takes worktree: true for sub-agents that change files alongside others; by default a sub-agent shares the parent's tree, guarded by the per-file write locks. Whether a sub-agent writes cannot be told from its tools (MCP tools), so the main agent decides per call. The runner gets SubAgentOptions instead of a bare require_file_references flag.
…'s tree A sub-agent given a worktree only registered it as an extra project; its session config still named the parent's project, so the system prompt offered the parent's tree as the initial project and writing sub-agents changed the user's checkout while their worktree stayed empty. The sub-agent's directory is now its worktree path, so it becomes the initial project; init_path stays the parent's for per-project tool choices.
A sub-agent's worktree was a fresh checkout of a snapshot: build outputs, installed dependencies and local configuration were missing, so it had to set them up before it could build or test. The worktree is now created without a checkout and filled with a copy-on-write clone of everything in the parent's tree, ignored files included (clonefile on macOS, reflinks on Linux). .git is not copied: the worktree shares the repository, so its branch and the merge back work as before. Worktrees nested in the project are left out. The commit the changes are measured against is a snapshot of the copy itself, so edits made to the parent's tree while copying are not taken for the sub-agent's. Where the file system cannot clone files, the worktree is a checkout of the snapshot as before.
daniel-kurzynski
force-pushed
the
feat/sub-agent-workspaces
branch
from
November 4, 2026 17:25
2d13b3c to
78eaec9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #280. Every sub-agent can now write. Sub-agents that change files alongside others can work in a full copy of the project of their own.
One kind of sub-agent
read_only/defaultmode split is gone. Every sub-agent has the editing tools and the session's MCP tools; an oldmodefield in stored input is ignored.spawn_agentcall of a turn runs in parallel. By default sub-agents share the parent's tree;fs_explorernow locks each path and replaces files atomically, so concurrent edits are not lost.Workspaces
worktree: true(the main agent decides per call), a sub-agent in a git project works in a workspace of its own. It's a git worktree on a branch of its own, filled with a copy-on-write clone of everything in the parent's tree: uncommitted work, build outputs, installed dependencies and local configuration. So the sub-agent can build and test right away, without a setup step..gitis not copied: the worktree shares the parent's repository, so its branch is visible there and the merge back needs no fetch. Worktrees nested in the project are left out.clonefileon macOS (APFS) and reflinks on Linux (btrfs, XFS). Where the file system can't clone files, the workspace is a checkout of the snapshot without ignored files, as before.Limits
Tests
git status, nested worktrees are skipped, two workspaces editing one file both land, a conflict keeps a branch, abandoning keeps partial changes..gitand skipped paths is copied, links stay links, and the copy is independent of the original.Docs:
docs/sub-agents-feature.md.