[FEATURE] Minimize the smallest subagent: per-agent opt-outs for every startup context block

Related: #78974 (skip CLAUDE.md and git status per agent; CLAUDE.md half shipped as omitClaudeMd), #68981, #77261 (per-subagent memory injection), #8245 (git snapshot cost; fixed only session-wide), #40459 (why opt-outs must be opt-in).

Background

Dispatching subagents is our main way to save context. Our cheapest agent, min, has one tool (Bash), no skills, no MCP, omitClaudeMd: true, and a ~2.9k-char body. Its first request is still large.

Measured. 1,279 subagent transcripts, agent type from *.meta.json. First request = input + cache_read + cache_creation on the first assistant message. Claude Code 2.1.280.

| Agent type | n | median first request (tokens) |
|---|---|---|
| min (Bash only, omitClaudeMd) | 48 | 7,538 |
| lookup | 69 | 8,005 |
| Explore (built-in) | 10 | 21,860 |
| general-purpose | 795 | 44,422 |

What's in min's first request. Estimated at ~3.8 chars/token. The last row is inferred as total minus what the transcript shows.

| Block | est. tokens | Needed by a Bash-only worker? |
|---|---|---|
| Sandbox instructions (full filesystem allow/deny JSON) | ~1,400 | Partly. It's enforced anyway, and the long deny list is noise. |
| Agent body | ~750 | Yes |
| The brief | ~620 | Yes |
| gitStatus snapshot + user email | ~340 | Rarely |
| Environment block | ~125 | cwd only |
| Model identity + attribution text + date | ~100 | Mostly no |
| Not in the transcript: base system prompt + Bash tool description | ~4,200 | Mostly no |

More than half of the smallest agent's first request is harness text we can't see or turn off. Also:

• The sandbox block is re-injected mid-run when the allowlist changes: median 2 copies, max 8, up to ~11k tokens of repeats in one short run (117 min/lookup transcripts).
• The three most recent min runs had cache_read_input_tokens = 0 on the first request, so the cheapest agent pays full cache creation every time.

Goals

• An agent definition can bring its first request down to roughly its own body, the tool schemas it lists, and the brief.
• Every intervention is opt-in per agent in frontmatter, and defaults stay as they are (#40459).
• Authors can see an agent type's startup cost, e.g. through /context for a subagent type.

Non-goals

• Changing defaults for general-purpose or built-in agents.
• Removing managed-policy or safety text.
• Tool Search / deferred loading, which has already shipped.

Solution

Per-agent frontmatter flags, with the estimated saving for min:

| Flag (proposed) | Removes | Saving |
|---|---|---|
| omitClaudeMd: true | CLAUDE.md | already shipped (2.1.271) |
| omitGitStatus: true | git status + recent commits | ~300 (more than 10k in busy repos, #8245) |
| omitEnvironment: true / environment: [cwd] | platform/OS/scratchpad lines | ~100 |
| omitSessionContext: true | user email, model identity, attribution text | ~150 |
| sandboxInstructions: brief | the full path JSON, replaced by one paragraph | ~1,200 per copy, and stops the mid-run re-injections |
| systemPrompt: replace | the harness base prompt (managed policy still appended) | ~2,000 to 3,000 (est.) |
| toolDescriptions: terse | long usage prose, keeping the schema | ~1,000 to 2,000 (est.) |
| tools: strictly honoured | deferred-tool lists and MCP instructions beyond those listed | large in MCP-heavy sessions |
| stable cacheable prefix per agent type | per-dispatch cache creation | ~7k cache-creation becomes cache-read |

Combined, min could go from ~7.5k to ~1.5-2.5k tokens, a 3 to 5 times cut on the agent type dispatched most for small jobs. A convenience preset (profile: minimal) could sit on top.

Why per-flag and not one switch: each block matters to some agent (git status to a commit agent, environment to a cross-platform agent), and #40459 shows the cost of context disappearing unexpectedly.

Alternatives considered:

• Session-wide includeGitInstructions:false also removes git context from the main session.
• Forked skills on Explore still carry Explore's ~21.9k start.
• claude -p --system-prompt through Bash loses worktree isolation, hand-back and permission inheritance.

Claude Code 2.1.280, Linux.