Claude Code subagents and hooks: a working developer’s guide

Published May 5, 2026 by Pondero Editorial

In short

Claude Code’s subagent and hook systems are the two features that turn it from a chat-with-files coding assistant into a controllable, auditable engineering tool. We built four reusable subagents (Explorer, Planner, Reviewer, Tester) and three pre-tool-use hooks (lint-on-write, branch-protect, cost-cap) over 30 days of production use. This guide covers what each pattern does, when to use it, and what broke when we shipped them. The recipes are vendor-feature-true to what Claude Code documents (anthropic.com/en/docs/claude-code/sub-agents and anthropic.com/en/docs/claude-code/hooks); your mileage will vary based on your repo’s specifics. Treat the patterns as a starting playbook, not a benchmarked best-practice.

What subagents are (vs main agent, vs Skills)

A Claude Code subagent is a separate agent context that the main agent can spawn for a focused task. Each subagent has its own system prompt, its own tool allowlist, and its own conversation history. When the subagent finishes, it returns a summary to the main agent and exits.

Subagents differ from the main agent in three ways:

• Scope: subagents are configured for a single job. The main agent is your generalist.
• Tool access: you can give a subagent fewer tools than the main agent has. An Explorer subagent might only have Read and Grep; a Tester might only have Bash.
• Context isolation: subagent transcripts do not pollute the main agent’s context. This is the biggest practical win for long sessions.

Subagents differ from Skills in that Skills are user-invokable bundles of instructions and tools that the main agent executes inline. Subagents run in their own process boundary; Skills do not. The two compose: a subagent can use a Skill, and a Skill can recommend spawning a subagent.

What hooks are (PreToolUse, PostToolUse, Stop, etc.)

Hooks are shell commands that Claude Code runs at specified points in the agent loop. The documented hook events include PreToolUse (before any tool call), PostToolUse (after), Stop (when the agent finishes), Notification (when the agent prompts the user), and several others. See anthropic.com/en/docs/claude-code/hooks for the current list.

A hook can read structured input from stdin, run any logic, and emit either a pass signal or a block signal. A blocking PreToolUse hook prevents the tool call from happening. A blocking PostToolUse hook can flag a violation for the agent to react to.

Hooks run as your user. They can read your filesystem, hit your network, and write to disk. Treat them as production code, not glue scripts.

Four subagent recipes

Explorer (read-only deep search)

Use when: you need to understand an unfamiliar part of the codebase before making changes.

Configuration: Read, Grep, Glob tools only. No Edit, Write, or Bash. System prompt instructs the subagent to produce a structured map of the relevant code: files, functions, call paths, and data flow.

Why a subagent: Explorer runs through 30 to 50 tool calls on a real codebase. Keeping that history out of the main agent’s context preserves the budget for actual editing work. We saved roughly 40% of main-agent tokens per task by routing exploration to a dedicated Explorer.

What broke: Explorer occasionally over-reported on tangentially-related files. We added a “include only files you would edit or read to make the change” line to the system prompt and the false-positive rate dropped sharply.

Planner (writes plan files, no edits)

Use when: a task spans multiple files or has architectural choices that should be reviewed before any code is written.

Configuration: Read, Grep, Write (scoped to plans/ directory only via a PreToolUse hook). No source-file editing. System prompt instructs the subagent to write a markdown plan with goals, files to touch, and a step-by-step implementation order.

Why a subagent: keeping planning separate from implementation creates a reviewable artifact (plans/<feature>.md) that the team can comment on before code lands. Even when no human reviews the plan, having it in git history is useful for audits.

What broke: Planner sometimes ran the same exploration as a previous Explorer run because it could not see the Explorer transcript. We started passing the Explorer summary explicitly as the first user message to Planner. Lost a token-budget win, gained reliability.

Reviewer (diffs against main)

Use when: a feature branch is ready for self-review before opening a PR.

Configuration: Bash (scoped to git read-only commands via PreToolUse hook), Read. System prompt instructs the subagent to run git diff main, identify each change, and rate it against a checklist (correctness, test coverage, style, security).

Why a subagent: review output is a structured artifact (markdown table of findings) that gets attached to the PR description. Keeping the review pass in its own context avoids the main agent rationalizing its own code.

What broke: Reviewer was too lenient initially. We added a calibration prompt: “rate three sample diffs from this repo’s history and explain why each one passed or failed review.” That brought the false-positive rate to roughly 15%, acceptable for a self-review pass.

Tester (runs targeted tests)

Use when: you have a focused change and want to run only the relevant tests, not the full suite.

Configuration: Bash (scoped to test runner commands), Read. System prompt instructs the subagent to identify the test files relevant to the change, run them, and report pass/fail with a one-line root-cause guess for each failure.

Why a subagent: test runs produce verbose output. Subagent isolation keeps the main agent context clean while still surfacing the pass/fail summary.

What broke: Tester’s root-cause guesses were wrong about 30% of the time on flaky tests. We added a “if the test is flaky, say flaky and stop guessing” line to the prompt. Still wrong sometimes; humans have to verify on real failures.

Three hook recipes

Lint-on-write hook (PostToolUse on Edit/Write)

What it does: after every Edit or Write tool call, run the project’s linter against the changed file. If the linter fails, return the error to the agent so it can fix the violation in the next turn.

Why: catches style and obvious-correctness issues at the point of edit instead of letting them accumulate.

Implementation note: scope the hook to specific file extensions you actually lint. Running prettier on every JSON file in node_modules/ is not what you want.

Branch-protect hook (PreToolUse on Bash)

What it does: parses the Bash command and blocks any call that would push to main, force-push, or delete a branch. Allows everything else.

Why: an agent that can run Bash can theoretically push to main. The blast radius of that mistake is enough to justify a hard block.

Implementation note: parse with care. git push origin main is obvious; git push --force is obvious. git push -f and git push --force-with-lease are subtler. Test the parser against the GitHub-flavored push variations before trusting it.

Cost-cap hook (Stop event)

What it does: when the agent finishes a session, read the session’s token usage from Claude Code’s logs, calculate the dollar cost at current Anthropic pricing (anthropic.com/pricing), and write it to a daily ledger. If the daily ledger exceeds a configured cap, post a warning to a Slack channel.

Why: agent-driven coding can quietly burn budget. Visibility is the cheapest control.

Implementation note: the ledger is per-developer, not per-machine. Centralize it (a small SQLite file on a shared volume or a tiny API) if you want team-wide caps.

How they compose with Skills

Skills are inline; subagents are out-of-process. The composition rule we settled on after 30 days: use Skills for repeatable instructions you want the main agent to follow (style guides, deployment recipes, repo-specific conventions). Use subagents for repeatable tasks you want to run in isolation (exploration, planning, review, testing).

A real example from our work: the “ship a feature” Skill asks the main agent to spawn Planner first, then implement, then spawn Reviewer, then spawn Tester. Each subagent emits a structured summary that the Skill incorporates into the final PR description. The Skill is the conductor; the subagents are the orchestra.

For more on the wider Claude Code workflow, see our Claude Code recap on prompt caching, the Claude Code vs Cursor comparison, and the Claude Code ultrareview.

What we cannot tell you

This guide covers patterns we use. We have not benchmarked subagent overhead vs. inline execution on a controlled task set. The “40% token savings on exploration” number above is a single-team observation across roughly 30 days of work, not a published benchmark. Your token economy will vary by model, by task, and by how aggressively your subagents prune their own context.

Verify Claude Code feature behavior at the release notes (anthropic.com/en/release-notes/claude-code) since the subagent and hook APIs have changed shape multiple times in 2025 and 2026.

FAQ

Can a subagent spawn a subagent? Yes. Use sparingly. The token math compounds.

What language are hooks in? Any executable. Shell, Python, Node, Go. Hooks read JSON from stdin and write JSON or text to stdout. Pick whatever your team will maintain.

Can hooks read environment variables? Yes. They run in your shell environment.

Are subagents free? Subagent token usage rolls into your Anthropic bill the same as the main agent. There is no per-subagent overhead beyond the system prompt.

Verdict

Subagents and hooks are the two Claude Code features that move the product from “useful chat assistant” to “controllable engineering tool.” Start with one Explorer subagent and a branch-protect hook. Add the Tester subagent and the lint-on-write hook in week two. Add Planner and Reviewer when your tasks consistently span multiple files. The cost-cap hook is the cheapest insurance you can put in place.

For more on Claude Code’s broader role in our workflow, see our Claude Code vs Cursor head-to-head.

Related: Claude Code recap on prompt caching · Claude Code vs Cursor · Claude Code ultrareview