Subagents and worktree isolation

Why this matters

The parent session is one context window. If you stuff research, a refactor, and a review into it, you pay for all of that on every later turn, and the model starts “remembering” files it has not opened this hour. A subagent is a child session. It gets its own window. It reports a summary back. The parent keeps the job, not the raw grep.

Specialist rung. If you do not write software or run agents, you can stop after C4 and still have reached repo level.

That only helps if the child’s edits cannot collide with yours. Default isolation is none — same working tree as the parent. Two writers, one disk. Worktree isolation gives the child its own checkout. You apply the result, or you throw it away. Until you have seen git status stay clean in the main tree while a child writes next door, you have not used isolation. You have used hope.

Teach

A subagent is not a persona and not a tab

Subagents are on by default. The parent calls spawn_subagent. The child runs with:

• Its own context window — the parent’s transcript is not copied in
• A toolset from its agent type and optional capability_mode
• Optional persona instructions (tone, output contract) layered at resolution — you do not pass a persona name as a spawn argument

When it finishes, the parent gets a summary, not a second copy of every file the child read. That is the point. If the child must continue later, spawn again with resume_from set to that child’s id (same agent type, child already completed, same parent session).

Agent (session definition: model, tools, prompt) is not persona (behavioral overlay on a subagent). Manage both in /config-agents (alias /agents). Personas live in /personas. Bundled personas are read-only.

Turn the feature off only if you mean it: GROK_SUBAGENTS=0 or [subagents] enabled = false.

Types, tools, depth

Project or user agents can add types or shadow these by name (.grok/agents/, ~/.grok/agents/).

capability_mode is an optional coarse filter: read-only, read-write, execute, all. If you omit it, the type’s own toolset wins. explore and plan already refuse edits.

Spawn parameters you will actually use:

Depth is one. Only the top-level session spawns. If a child calls spawn_subagent, the call fails. That is not a bug. It keeps the tree flat.

MCP: children inherit the parent’s already-connected servers (mcpInheritance: all / none / named / except). An empty catalog means the parent never connected the server, or the filter dropped it. Review C7 if that sentence is new.

When to spawn — and when not to

Use a child when the work is separable: map this package, run the test suite, review the diff the parent just wrote. Independent tasks can run in parallel.

Do not spawn for a one-file typo. Do not spawn for a question that needs you in the loop — a child is not a conversation with you. Do not spawn when briefing the child would take longer than doing the read yourself.

The parent still owns the user. You talk to the parent. You open a child to observe.

Isolation: worktrees

isolation: worktree makes a git worktree for the child. The child edits that copy. The main tree does not move. The child’s result includes the worktree path.

Grok manages this through x.ai/git/worktree/*: create, list, apply (merge back into the main working directory), remove, gc.

You can also start your session in a worktree, which is the right move when you are the one about to edit:

# Use = so the prompt is not eaten as the worktree name
grok --worktree=c8-demo "Add notes/c8-isolated.txt with one line. Do not touch files outside this worktree."

# Base the worktree on main, not whatever you have checked out
grok -w --ref main "implement the feature from main"

/fork --worktree (or --no-worktree) branches the session and, if you ask, the tree. /new can prompt for a worktree depending on [ui] new_session_worktree_mode (ask / always / never).

Resume a session in a fresh worktree: grok -w -r <session-id>.

Worktrees pile up under ~/.grok/worktrees/. grok du shows size and age. grok worktree gc --max-age 7d --dry-run, then without --dry-run. Gc does not inspect uncommitted work. Read the dry-run. Untracked worktrees are not in the registry; grok worktree rm --dry-run <path> then rm.

Each worktree keeps its own permission grants. Always-allow in the main tree is not always-allow in the child tree.

Personas can set default_isolation. Isolation resolution does not inherit the parent’s mode; it defaults to none unless spawn, role, or persona says worktree.

Watching in the TUI

• Parent scrollback: a lifecycle block (Subagent running: "map the auth package"). Enter opens the child’s transcript.
• Ctrl+G — tasks pane, group Subagents. Kill or inspect from there.
• The child view is mostly observational. You do not drive it like a second prompt. q or Esc returns to the parent.

Ctrl+T is the todo pane, not the task pane. Different window.

Good parent prompts name the type and the isolation. Bad parent prompts say “go do everything” and then act surprised when two children edit package.json.

Worked example

Practice repo. Clean git status on the branch you care about.

Part A — own context. In the TUI:

Spawn one explore subagent. Description: map practice repo.
Prompt it: List top-level files and the first heading of README.md.
Do not edit. When it finishes, quote only its summary. Then answer
from the parent: did you open README.md yourself this turn? Yes or no.

You should see a spawn block, then a short summary. The parent’s honest answer is no — it did not need those file reads in its own window. If the parent also dumped a full file listing, it failed the brief. Ask it to stop restating the child.

Part B — isolation. Quit. From the same repo:

grok --worktree=c8-demo "Create notes/c8-isolated.txt containing exactly: c8 worktree demo. Do not commit. Do not modify any other path. Stop and print this worktree's absolute path and git status."

Approve the write in the worktree. In a second terminal, cd to the main repo (not the worktree path) and run git status. The main tree should not show notes/c8-isolated.txt as an untracked file in the main checkout. If it does, you were not in a worktree — you launched without --worktree= or you applied already.

In the worktree session, ask Grok for the path. cd there in the second terminal. git status should show the new file. That pair of statuses is the lesson.

Apply only if you want the file in the main tree. Otherwise discard and grok worktree rm after a dry-run. Do not leave mystery checkouts on disk.

Your turn

Do c8-l01-e1 in Grok Build. You will spawn an explore child, then make a one-line file in a worktree, and paste both git status outputs. If the file appears in the main tree before you apply, you failed isolation.

Common failure

Treating the child as a second you. You keep pasting the same long brief into the parent and the child. The parent’s window fills up anyway. Brief the child once, with files and a stop. Let the summary come back.

Shared-tree edits. You spawn general-purpose with default isolation: none to “try a refactor.” It writes next to your unfinished work. git diff is now two authors. Use explore for reads. Use isolation: worktree or grok --worktree= for writes you might throw away.

Nested spawn. You tell the child to “delegate further.” Depth-limit error. Split work from the parent, in parallel, not as a pyramid.

Worktree as a trash can. Six old --worktree sessions, 20 GB, none applied. grok du. Dry-run gc. Decide apply or delete.

What’s next

C9 leaves the TUI: grok -p for one-shot scripts, ACP as JSON-RPC for editors, and Grok Bot as a different product with a cloud computer. Do not mix those three names.

I am on Grok Mastery Pathway C, module C8, part A.

Spawn exactly one subagent:
- subagent_type: explore
- isolation: none
- background: false
- description: map this repo

Child prompt: Name the top-level files. Quote the first heading or first line
of README.md (or say README.md is missing). Do not edit. Do not spawn anyone.

When the child finishes:
1) Paste its summary, labeled CHILD SUMMARY.
2) Answer as the parent, labeled PARENT: Did you read README.md with your
   own tools this turn? Yes or no. One sentence on what you kept out of
   your context.
Do not repeat the child's file dump in the parent voice.