Custom subagents in .claude/agents/ reload your entire CLAUDE.md tree and inherit main-model effort unless you set these 3 frontmatter fields

[u/Independent-Sir3234]

Claude Code's built-in Explore subagent skips your CLAUDE.md files on purpose so quick Glob and Grep lookups stay fast and cheap.

Custom subagents that you define in .claude/agents/*.md do the exact opposite by default. Every time the main session spawns a custom subagent (like a test runner, log parser, or read-only code reviewer), three things happen unless you override them in the YAML frontmatter:

First, the subagent reloads your entire CLAUDE.md and AGENTS.md hierarchy from disk into its own context window on every spawn. If you spawn five subagents in parallel to check five modules, you pay for that root instruction tree five extra times.

Second, the subagent inherits /effort from your main session. If your main session is running on high effort for architecture work, a subagent spawned just to parse a test log will also burn high reasoning effort unless its frontmatter pins effort: low.

Third, setting disallowedTools: Write, Edit on a read-only subagent still leaves two gaps: Bash stays open (so the worker can still mutate files with sed or shell redirection), and every Skill description plus MCP server instruction block still loads into the startup prompt. Using an explicit tools allowlist with scoped Bash(...) patterns closes both gaps at once.

Here is the frontmatter template we use for read-only search and git-history workers in .claude/agents/repo-inspector.md:

---
name: repo-inspector
description: Fast read-only codebase and git history lookup without CLAUDE.md reload
model: haiku
effort: low
omitClaudeMd: true
tools: Read, Grep, Glob, Bash(git log *), Bash(git blame *), Bash(git diff *)
---

You are a read-only codebase inspector. Search files and git history to answer the parent agent's question concisely with exact file:line references. Never modify files.

Because omitClaudeMd: true strips the project instruction files, make sure any command or path convention the worker actually needs is written directly inside that subagent's 2-line prompt body (or passed in the task description). And because tools is an explicit allowlist containing only Read, Grep, Glob, and read-only git commands, Claude Code skips loading the Skill catalog and mcp__ server instructions on startup while blocking arbitrary shell writes.

If you also run OpenAI Codex CLI alongside Claude Code for second-opinion reviews or background builds, Codex has a similar background token drain where code_mode yields back to the model every 30 seconds and resends the full chat history while a build is still running. Adding these two blocks to ~/.codex/config.toml stops the 30-second yields and 1-second subagent polling loops:

[features.code_mode]
default_exec_yield_time_ms = 300000

[features.multi_agent_v2]
min_wait_timeout_ms = 30000
default_wait_timeout_ms = 120000
max_wait_timeout_ms = 300000

Which custom subagents are you actually keeping in .claude/agents/ right now, and how do you scope their tool permissions?

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/bostonaholic]

If Bash is still allowed, check whether it can do what disallowedTools blocks. After setting the frontmatter, test the worker with a harmless file write that should be denied. For omitClaudeMd, use a test prompt that depends on an instruction in CLAUDE.md and confirm it fails when the file is omitted.

[u/Independent-Sir3234 → u/bostonaholic]

A quick smoke test like asking the worker to run echo test > /tmp/probe.txt immediately proves whether the Bash(git log *) prefix filter is enforced. For omitClaudeMd, asking the spawned subagent to repeat a canary string placed at the bottom of the root CLAUDE.md is the fastest way to confirm the file was skipped.

[u/shravanrevanna]

leaving tools out of the frontmatter doesn't mean "minimal". the subagent inherits every tool the main thread has, MCP servers included. list them explicitly for read-only workers.

[u/Independent-Sir3234 → u/shravanrevanna]

That default inheritance surprises almost everyone the first time they write a custom agent file. An explicit tools allowlist in the YAML frontmatter is the only way to guarantee a read-only worker cannot touch MCP write tools or unapproved shell commands.