Build1 publisher3 min readPublished
Claude Code's subagent transcripts record which model and effort level each launch used
Dev.to authors ran seven claude -p probes on Claude Code 2.1.278 to test whether the model and effort lines in three subagent files do anything. Each subagent's transcript logs model and effort per request, so a pinned setting can be checked against the run.
The Engineer · Build desk
What happened
- The post's authors keep three Claude Code subagents whose frontmatter pins sonnet at xhigh, opus at xhigh, and inherit at high effort.
- Until the week of the test, the authors had never checked whether those model and effort lines change anything at runtime.
- They ran seven claude -p invocations on Claude Code 2.1.278 on macOS on 2026-09-22, inside a throwaway directory.
- The longest system prompt a subagent received was 1,702 characters, and 422 of them came from the authors' agent file.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- decision Any cost or quality claim that depends on which model a subagent used can be checked against message.model and effort in its JSONL before anyone trusts the frontmatter.
- exposure Reviewers whose rules say never write to anything public still inherit the full tool pool, so that rule rests on prompt text until a tools line narrows what they can call.
- cost Editing an agent file changes at most about a quarter of its launch system prompt; the rest is harness text the agent file does not contain.
"Waved through" is the post's own phrase for one frontmatter field [10]. The documentation's table of supported fields opens with a single rule: "The following fields can be used in the YAML frontmatter. Only name and description are required." [16] The authors' workflow runs `claude plugin validate .claude/agents` before any launch [4]. Their introduction lists what Claude Code does with a key it has never heard of among the things they measured [15]. A passing validate run shows the file parses; whether the model and effort lines changed the run is a separate question, and the transcript is where it gets answered. The excerpt of the post ends at the documentation table, before the per-agent costs and before the validator's printed output, so whether it warned about the unknown key is not in the record.
The probe itself is careful work. It runs in a directory made with `mktemp -d`, so the repo's own instruction files stay out of the count [4]. The parent session is told to launch the subagent exactly once with this prompt: "This is a measurement probe. Do not read anything, do not call tools. Return 'ok'." [4] Few model replies cost less to produce than "ok". With no tool calls, the first API request comes close to the bare cost of launching the agent, and that first request is what the authors set out to price [15].
Two readouts come back. The JSON on stdout has a `modelUsage` object keyed by model, so a subagent running on a different model from its parent shows up as its own bucket [6]. The subagent's own JSONL, under `~/.claude/projects/<cwd>/<session_id>/subagents/`, carries `message.model`, `message.usage` and a top-level `effort` key on every assistant record [5]. The authors wrote that the effort key was new to them [5]. A second run with `--effort low` on the `claude -p` line then shows whether the file's effort beats the session's [7].
According to the documentation, the file should win. The effort row reads: "Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session." [8] The model row says that when the field is omitted, "Claude Code picks the model in the subagent model order." [9] The bulk-reader pairs `sonnet` with `xhigh` [2]. The effort row ends with "available levels depend on the model" [8]. That pairing is the likeliest place for a file and a run to disagree, and the recorded `effort` value is where a disagreement would appear [5].
Most of what a subagent hears at launch comes from the harness. Of the longest system prompt, 1,280 characters, about 75 percent, were Claude Code's own notes for subagents [12]. The authors singled out that share when asking where launch tokens go [11]. Each of their agent bodies is 5 to 8 bullet rules [13].
What to watch
- The post's reported validator output for the unknown key: a printed warning, a silent pass, or a runtime that read the field anyway.
- The effort value recorded in the bulk-reader transcript, showing whether sonnet actually ran at the xhigh level its file requests.
- The --effort low run: if each subagent's recorded effort stays at its file value, the documented override holds on 2.1.278.