Claude Code subagents: the rule boundary nobody warns you about

Claude Code subagents are one of the most useful features in the tool and one of the easiest to get quietly wrong. They fan work out. They also fan out a hole: every rule you wrote to keep your agent in line stops at the subagent door. This post explains what subagents are, when to reach for them, and the boundary problem that no getting-started guide mentions.

What are Claude Code subagents?

A subagent is a fresh agent your main agent spawns with the Task tool to handle a self-contained job on its own. It runs in its own context window, does the work, and returns only its final answer. That isolation is the whole point: a broad search or a big audit can burn thousands of tokens, and a subagent keeps all of that noise out of your main conversation.

The isolation is real in both directions. The subagent does not see your running conversation, and, as we are about to see, it does not see the rules you set up at the start of it either.

When to use a subagent

Reach for a subagent when a job is independent and noisy: a codebase-wide search when you do not know where something lives, a multi-file review where you only want the conclusion, or several unrelated tasks you want to run in parallel. Keep tightly coupled, step-by-step work in the main session, where each move depends on the last.

The rule of thumb: delegate the reading, keep the deciding. A subagent is great at going and finding out. It is a poor place for work where you need to stay in the loop turn by turn, because you cannot coach it mid-flight. You get one prompt in and one answer back.

Why your rules die at the Task boundary

Here is the part nobody warns you about. When your main agent spawns a subagent, the subagent inherits your model but not your rules. Claude Code loads your CLAUDE.md and runs your SessionStart hooks at the start of the main session, and that context never crosses the Task boundary. The subagent starts clean, with its own system prompt and none of your carefully written behavior rules.

Think about what that means at scale. You spend an afternoon tuning a CLAUDE.md so your agent asks before it builds, stays lean, and does not ship AI-slop UI. Then your agent spawns five subagents to parallelize a refactor. Those five run with zero of your rules. The one place you most want restraint, several agents editing files at once, is the one place your rules are absent. This is not a bug in your config. It is how the boundary works, and it is invisible until you go looking.

It has been documented publicly. The ponytail rules repo filed issue #252 on exactly this: SessionStart guidance does not reach subagents, so the rules silently stop applying the moment work is delegated. If you rely on a SessionStart-only setup, every delegated task is a gap.

The fix: re-inject rules with a SubagentStart hook

The fix is a hook that fires on SubagentStart and prints your working rules straight into the new subagent's context. Claude Code exposes that event for exactly this reason. kitstarter wires it with a 16-line script, subagent-rules.mjs, that runs every time a subagent spawns and re-states the rules that matter. It fails open, so a bad run never blocks the subagent.

These are the literal three rules it injects into every subagent:

That single hook is not the whole story, though. It is one of eight events kitstarter wires so the rules hold at every point in a session, not just at the start.

Rules that hold at every boundary

A rule that only fires once is a rule with holes. kitstarter wires eight Claude Code events to eight scripts so the same behavior applies when a session starts, when you prompt, when a tool runs, when a subagent spawns, and when the agent tries to stop. The full wiring table looks like this:

Does the enforcement actually work?

In our clean-room benchmark, yes, and we publish the losses too. On the same model and the same scripted tasks, the kit asked before building on 5 of 5 tasks versus 2 of 5 for vanilla Claude Code, shipped about 40 percent less code for the same outcome, and cut slop tells from 5 to 0 on the debug-spiral task. Enforced behavior beat mood-dependent behavior on every task that had room to move.

The honest side. On an already-clear, already-minimal job, the kit is pure overhead: the todo-app task ran about twice as slow and roughly 75 percent pricier for near-identical output. Across the suite the hook context tokens add about a 25 percent average cost premium. That cost is real, it is disclosed, and it is paid out of your existing subscription. We never hide the losses, because a benchmark that only shows wins is marketing, not measurement.

The takeaway

Claude Code subagents are worth using. Just know the boundary: they inherit your model, not your CLAUDE.md, so a SessionStart-only setup leaves every delegated task unguarded. Close it with a SubagentStart hook that re-injects your rules, and every subagent your agent spawns is held to the same standard as the main session. You can write that hook yourself from the shape above, or start from one that is already wired.