anthropics / anthropics/claude-code
Editing an existing agent's `tools:` frontmatter is not picked up by dispatched subagents, even after a full app restart
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
## Summary
Adding a tool to an existing subagent's `tools:` frontmatter (`~/.claude/agents/.md`) is not applied to
subagents dispatched via the `Agent`/`Task` tool — not in the same session, not in a brand-new session, and not
even after a full kill-and-relaunch of the Claude Code process. The only thing that *is* fresh is the "Available
agent types" listing shown to the top-level session, which already reflects the edited file.
Version: Claude Code 2.1.276, Windows 11.
## Repro
1. Edit an existing agent definition, e.g. `~/.claude/agents/cpp-developer.md`, changing
`tools: Read, Glob, Grep, Edit, Write, Bash` to `tools: Read, Glob, Grep, Edit, Write, Bash, LSP`. Commit/save it.
2. Fully quit and relaunch the Claude Code app/process (not `/clear`, not `claude --continue`, not just a new
top-level conversation) and start a new session.
3. Confirm the top-level session's own "Available agent types" system listing already shows the updated line,
e.g. `cpp-developer: ... (Tools: Read, Glob, Grep, Edit, Write, Bash, LSP)` — it does, so the file is being
re-parsed fine at this layer.
4. From that fresh session, dispatch a subagent: `Agent({ subagent_type: "cpp-developer", prompt: "" })`.
5. After it completes, grep its own transcript (`~/.claude/projects///subagents/agent-a-
.jsonl`) for its actually-defined tools:
```
grep -o '"name":"[A-Za-z_]*","description"' .jsonl | sort -u
```
**Expected:** the list includes `LSP` (matches the on-disk, and now also registry-listed, definition).
**Observed:** the list is exactly the *pre-edit* six (`Bash, Edit, Glob, Grep, Read, Write`, plus `SendMessage`
which every teammate gets), with `LSP` completely absent — even though this is a brand-new session created well
after both the file edit/commit and the full process restart.
This was reproduced twice: once in a new session only (no restart) and once after a genuine full process restart,
with identical results both times.
## Why this looks distinct from existing reports
- #5738 and #28685 describe agents (new files, or edited files generally) not being picked up **without a
restart**, with the fix being "restart the app." Here, a full restart of the app itself does not fix it — that
is new information beyond what those two report.
- #92426 describes a related but different failure shape: a dispatched subagent silently inheriting the
**dispatcher's own full toolset and system prompt**, ignoring its own definition's ceiling entirely, while the
"Available agent types" listing is nonetheless parsed correctly. Our repro's symptom is narrower and more
specific: the child gets *exactly* its own agent type's declared tool list, just apparently frozen at an older
parse of that same file (missing only the newly-added tool) rather than inheriting the parent's tools wholesale.
That suggests either a second, independent caching layer specifically for the tool-ceiling applied at
instantiation time, or a subtly different variant of whatever #92426 is tracking.
## Impact
Anyone iterating on an existing subagent's tool list (adding/removing a tool) currently has no reliable way to get
dispatched subagents to pick up the change short of possibly reinstalling — a full app restart, which should be
the last resort per #28685/#5738, was insufficient in this case.
## Question
Is there a separate cache (a compiled agent registry, an index file, something in a local app-data directory)
that holds a stale per-agent tool list independent of the "Available agent types" listing shown at session start?
If so, where does it live and how can it be invalidated short of a reinstall?
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the agent definition at ~/.claude/agents/.md and reproduce the issue through the Agent/Task entry point after a full restart. Compare the Available agent types listing with the dispatched subagent's JSONL transcript under ~/.claude/projects///subagents/; the work is complete when the child reflects the edited tools list, including LSP.
Written by the indexing model from the issue text.
Assessment
- Domain
- devtools
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100