[rdimitrov]

Summary

Subagents were a large share of wall-clock time. Two causes:

• Children inherit the full project instructions, including repository-wide test and lint gates, so every child ran the full package suite on its own.
• The delegation guidance presented delegation as free and advertised test runs and implementation as delegation targets. Nothing told the parent to keep short or context-dependent work inline. Children start with only a brief, so many of them re-read the same files to rebuild the same context.

The guidance now follows a cost-first framing, closer to how other harnesses steer delegation: delegation has a real cost, read-only investigation is the advertised use, and the default is to do the work yourself.

Changes:

• Subagent tool description (engine/agent/subagent.go):
  • Opens with the cost: the subagent starts empty, re-reads what the parent already has, and returns only its final message.
  • The parent does work itself when it's a handful of tool calls or depends on context it holds.
  • Delegation is reserved for read-only investigations whose intermediate output isn't needed.
  • The parent runs full suites and repository-wide checks itself.
  • Ends with "When in doubt, don't spawn".
  • Removed: the "run the tests and report failures" example, and the "implement this fix" and "edits LAND" examples. mode:"read-write" is still documented factually but no longer promoted.
• Tool-discipline hint (engine/prompt/builder.go): one sentence carries the same cost and default into the system prompt.
• Child verification scope (internal/app/build.go): every Subagent-family child (task, task:*) gets a Role note. It says the delegating session owns repository-wide verification, so the child runs only focused checks. The exception is a delegating brief that explicitly asks for a full gate. Team members, Parallel branches, and internal reviewer and router children are unchanged.
• panel-review skill: the orchestrator captures the diff once and passes it to every reviewer as <Step 1 diff>. A diff over about 1000 lines is saved once and passed by path. Reviewers don't run git diff themselves.

The agency text (agencyDelta) and the panel-review reviewer count were reviewed and left unchanged.

Tests

• TestSubagentChildPromptScopesVerification drives a real Subagent call through buildIsolated with a scripted mock provider. It asserts the child's stable system prefix carries the note and the parent's does not. Mutation-checked: disabling the wiring makes it fail.
• TestDelegationGuidanceLandsInBuiltEnginePrompt and the new test share one helper, captureBuiltPrefixes. Both assert through constants, not prose.
• go test ./engine/agent ./engine/prompt pass.
• task docs passes.
• task lint is clean except for one darwin-only gosec finding in environment/microvm/launch_ownership_darwin.go, which this PR doesn't touch.
• go test ./internal/app: the delegation tests pass. Several tests fail locally on macOS (TestCanonicalConfiguredDir_AllowsMissingDefaultParents, TestYoloRelativeEscape*, and git-in-worktree end-to-end tests). They fail the same way on an unmodified checkout of the base commit.

The effect on real sessions is not measured yet. This changes model-facing guidance, so the wall-clock win depends on model behaviour and needs a before/after run on a representative task.

API compatibility

• Assessment: compatible, no major bump.
• Rationale: the only remote-observable change is model-facing prompt text: the Subagent tool description, the system-prompt hint, and the child Role. Tool names, schemas, events, RPCs, and authorization are unchanged. Clients that render tool descriptions get different text, but no contract depends on it.
• Major/feature changes: none.
• Approval for a break: not needed.
• Upgrade implications: none. Models should delegate less, keep implementation in the parent, and run fewer full suites inside subagents.

🤖 Generated with Claude Code