Per-agent frontmatter to skip CLAUDE.md / memory inheritance (the engine already does this for Explore/Plan)

Summary

Add an opt-in frontmatter field on custom subagent definitions (.claude/agents/*.md) that excludes the inherited CLAUDE.md hierarchy and/or auto-memory from that agent's startup context. For example:

inheritProjectMemory: false   # skip the CLAUDE.md hierarchy (default: true)
inheritMemory: false          # skip MEMORY.md auto-memory   (default: true)

Defaults preserve today's behavior. This is purely opt-in, for agents whose task doesn't need project conventions or branch state.

Why this is a small ask

The capability already exists in the engine. Per the sub-agents docs ("What loads at startup"): "Explore and Plan are the only subagents that omit CLAUDE.md and git status. There is no frontmatter field or per-agent setting to change which agents skip them." The request is to expose that existing skip path to custom agents, not to build new loading semantics.

Motivation (measured)

On multi-agent review fan-outs, every custom subagent inherits the full project CLAUDE.md plus the auto-memory index — in my setup ~7.4K + ~4.7K ≈ 12K tokens it never uses. Confirmed by spawning an introspection probe: a general-purpose and a custom review subagent both quoted project CLAUDE.md and MEMORY.md content verbatim from their boot context, with no prior file read.

A focused code/test reviewer uses none of it. It reviews a diff; it doesn't need the build commands, IDE-control routing rules, monitor docs, or the branch-status memory index.

Cost: a subagent averages ~20 turns, and context is front-loaded (~70% of peak is present by the halfway point), so each inherited token is re-read ~19 times via prompt cache. That ~12K therefore costs roughly $0.20–0.30 per spawn in cache traffic. Across ~2,350 logged subagent spawns that is a few hundred dollars of inherited-but-unused context, and it scales linearly with fan-out width.

Today there is no per-agent lever for this: tools, disallowedTools, and model are configurable, but CLAUDE.md and memory inheritance are not. The only workarounds are shrinking the shared files (which also strips guidance the orchestrator needs) or routing work through the built-in Explore agent (read-only, fixed model, so it can't carry a custom reviewer prompt).

Scope / safety

• Opt-in, default true → zero behavior change for existing setups.
• Mirrors the existing Explore/Plan skip path, so no new loading semantics.
• Pairs naturally with tools/disallowedTools for building lean, single-purpose subagents.

Environment

Claude Code v2.1.169.

Alternatives / variants

Two designs solve the same problem; either works, and they compose:

A. Binary skip (above). inheritProjectMemory: false drops the inherited hierarchy wholesale. Simple, but blunt — a reviewer that skips everything also loses the code-style and test conventions it does want.

B. Per-subagent project memory (preferred). Let an agent point at its own scoped context file that replaces the inherited hierarchy, for example:

projectMemory: .claude/agents/review-code-quality.context.md   # replaces the inherited CLAUDE.md for this agent

The agent then boots with a curated slice — just the conventions that role needs — instead of the full shared CLAUDE.md. This is strictly more capable than A: the binary skip is the degenerate case of B with an empty file. It avoids the all-or-nothing tradeoff and composes with the existing per-agent memory field and the agent's own system-prompt body.

Today the agent .md body is appended to the inherited CLAUDE.md, so it can't be used to substitute a leaner context. Variant B would make that substitution explicit. Field name is illustrative — the ask is the capability, not the spelling.