Claude Code / delegated agent field notes
Claude Code Subagents: scope, files, tools, and limits
.claude/agents/ and personal definitions under ~/.claude/agents/. Write a precise description because it is the delegation signal, and restrict tools to what the subagent needs. A valid definition still does not prove that delegation occurred.Our local test on Claude Code 2.1.283 separated those two claims. A JSON agent definition passed CLI parsing and reached the authentication boundary. The session then returned Not logged in · Please run /login, with zero input tokens, zero output tokens, zero cost, and zero spawned subagents.
A minimal project subagent
Save a project-specific definition as .claude/agents/evidence-auditor.md. The filename helps humans; the name field is the agent identity.
---
name: evidence-auditor
description: Audits a technical claim against saved local output and reports unsupported claims.
tools: Read, Glob, Grep
model: inherit
---
Read the supplied evidence files. Separate observed output
from documentation and inference. Do not edit files.| Field | Why it matters | Failure mode |
|---|---|---|
name | Stable identity used for invocation | Duplicate names in one tree can resolve by filesystem order rather than an intended hierarchy. |
description | Tells Claude when delegation is appropriate | A vague description causes missed or inappropriate delegation. |
tools | Creates a positive capability boundary | Omitting a boundary can give the delegated task more tools than needed. |
model | Chooses a model or inherits the parent | Changing the model can change cost, speed, and behavior. |
| Body prompt | Defines the specialist's job and output discipline | A broad role can duplicate the parent instead of reducing context. |
Discovery and precedence are part of the design
| Source | Scope | Documented precedence |
|---|---|---|
| Managed definitions | Organization | Highest |
--agents JSON | Current session | Above project definitions |
.claude/agents/ | Current project | Above user definitions |
~/.claude/agents/ | All local projects | Above plugin definitions |
Plugin agents/ | Where the plugin is enabled | Lowest of these sources |
The official guide says project definitions are discovered while walking from the current directory toward the repository root; when nested project directories define the same name, the closest definition wins. Agent directories are scanned recursively. Keep names unique within one directory tree because duplicate selection there is not a useful precedence mechanism.
The local test: accepted configuration is not delegation
We ran two deliberately different --agents inputs. Passing the Markdown file itself failed immediately because the flag expects JSON or a file containing JSON:
Error: Invalid --agents configuration:
invalid JSON: JSON Parse error: Invalid number
(read from ...\.claude\agents\evidence-auditor.md)The second fixture used a JSON object with description, prompt, tools, and model. The CLI accepted it, started a print-mode turn, and stopped at authentication:
"result":"Not logged in · Please run /login"
"total_cost_usd":0
"input_tokens":0
"output_tokens":0
"subagent_stats":{"spawned":0,...}Download the subagent test observations (CSV)
What was tested, and what remains untested
| Claim | Verdict | Evidence |
|---|---|---|
| The installed CLI can parse the session agent JSON | Tested | The JSON invocation passed configuration parsing and reached authentication. |
A Markdown agent file can be passed directly to --agents | Rejected | The CLI returned an invalid JSON error. |
| The custom subagent was spawned | Untested | The raw result reported spawned: 0. |
| The tool boundary prevented writes | Untested | No delegated tool call occurred. |
| The subagent improved task quality | Untested | No model response was produced. |
Use a subagent when the context boundary is real
- Delegate a bounded search, test, review, or evidence audit that can return a compact result.
- Give read-only tools to a read-only task. Add write or shell tools only when the delegated work requires them.
- Put shared project specialists in version control; keep personal preferences at user scope.
- Use hooks for deterministic lifecycle actions and subagents for model-guided work. They solve different problems.
- Record whether a run actually spawned the named agent. A definition on disk is inventory, not execution evidence.
FAQ
Do I need Claude Pro or Max to test delegation?
You need an authenticated Claude Code path, which can be a supported Claude subscription or an Anthropic API setup. This test used neither, so delegation was not run.
Does claude plugin validate prove a subagent can run?
No. It can catch some directory or frontmatter problems, but execution still depends on discovery, trust, authentication, model access, and the actual task.
Did this local attempt incur a charge?
No. The result reported total_cost_usd: 0 and zero input and output tokens.