Undocumented system-prompt directive "Do not call the AgentTool unless the user requested it" contradicts documented description-based subagent delegation

Summary

Claude Code ships an undocumented system-prompt directive that instructs the model not to use the Agent tool unless the user explicitly asks:

Do not call the AgentTool unless the user requested it
Do not use workflows or deep-research unless the user requested it

This directly contradicts the documented subagent model, which states that Claude decides when to delegate based on each subagent's description. The result is that custom subagents with well-written, explicitly matching descriptions are never auto-selected — the user must name the agent or ask for delegation in words.

I am not arguing the directive is wrong. I am reporting that it is undocumented and contradicts published behaviour, which makes the documented description field misleading for anyone building custom subagents.

---

Evidence

1. The directive is hardcoded in the CLI binary

strings "$(readlink -f "$(command -v claude)")" | grep "unless the user requested"

Output on macOS arm64, Claude Code 2.1.220:

Do not call the AgentTool unless the user requested it
Do not use workflows or deep-research unless the user requested it

The surrounding minified source shows it assembled as a system-prompt block:

ttp = ["Do not call the AgentTool unless the user requested it",
       "Do not use workflows or deep-research unless the user requested it"].join("\n");

It is not user configuration. I searched and ruled out: ~/.claude/settings.json, project .claude/settings.json and settings.local.json, ~/.claude.json, all CLAUDE.md files (user and project scope, plus every parent directory), output styles, enterprise managed settings (/Library/Application Support/ClaudeCode/managed-settings*), and the cached remote feature-flag payloads in ~/.claude.json.

2. Introduced in 2.1.219

Three versions were present locally:

| Version | contains the directive |
|---|---|
| 2.1.218 | no |
| 2.1.219 | yes |
| 2.1.220 | yes |

for v in ~/.local/share/claude/versions/*; do
  printf '%s %s\n' "$(basename "$v")" "$(grep -ac 'Do not call the AgentTool' "$v")"
done

3. The model cites it as the reason for not delegating

Running headless in an empty directory with a prompt that squarely matches a custom subagent's description, and asking the model to explain its own decision, it quoted the directive verbatim as the blocking rule.

4. Confirmed behaviour

With Claude Code 2.1.220 and 14 custom subagents installed under ~/.claude/agents/, natural-language prompts matching each agent's description produced zero subagent_type dispatches. Adding an explicit request such as "please hand this to a dedicated subagent" to the same prompts produced correct dispatch in 12 of 14 cases — including three deliberately confusable pairs. Agent selection works; the decision to delegate at all is what is suppressed.

---

Why this is a documentation/behaviour conflict

The subagents documentation defines description as the delegation trigger:

Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it.

and lists it as a required frontmatter field whose meaning is:

description — When Claude should delegate to this subagent

— https://code.claude.com/docs/en/sub-agents

If the shipped system prompt says delegation requires an explicit user request, then description cannot function as documented for automatic delegation. One of the two should change: either document the directive and its interaction with description, or make the directive conditional.

---

Workarounds evaluated and ruled out

| Attempt | Result |
|---|---|
| UserPromptSubmit hook emitting a standing-authorization line | No effect. The hook fired and produced output (verified by logging), but the model still did not dispatch. This matches the documented behaviour: hook stdout is added as context, and UserPromptSubmit "only supports blocking or adding context, not rewriting the user's message" — https://code.claude.com/docs/en/hooks |
| CLAUDE_CODE_AGENT_RULE_DISABLED=1 | No effect (name found via strings; semantics undocumented). |
| Standing authorization written into CLAUDE.md | No effect. |
| description phrasing per community advice ("use PROACTIVELY", description-as-trigger-condition) | Already in use across all agents; no effect on this version. |

---

Honest caveat — the directive is probably not the whole story

I want to be precise rather than overstate the report.

I re-ran the same natural-language prompt against 2.1.218, which does not contain the directive. It also did not dispatch — it answered inline instead. So removing the directive alone does not restore automatic delegation, and downgrading is not a fix.

The most defensible reading is that automatic delegation was already unreliable, and 2.1.219 made a previously implicit bias explicit and unconditional. Community reports describe the same unreliability independently.

That caveat does not dissolve the issue: an undocumented, unconditional directive that contradicts the documented delegation mechanism is worth either documenting or reconsidering, regardless of what the behaviour was before it landed.

---

Reproduction

1. Create ~/.claude/agents/demo-reviewer.md:

---
name: demo-reviewer
description: Reviews source files for defects and security issues. Use PROACTIVELY whenever the user asks to look over code they just wrote.
tools: ["Read", "Grep", "Glob", "Bash"]
---
Review the provided code and report defects.

1. In an empty directory:

claude -p "I just finished a PHP order-processing service, can you look over the code for problems?" \
  --dangerously-skip-permissions --max-turns 3 --output-format stream-json --verbose \
  | grep -o '"subagent_type":"[^"]*"'

1. Observed: no output (no dispatch). The model performs the review inline.
2. Re-run with ... for problems? Please hand this to a dedicated subagent. → "subagent_type":"demo-reviewer".

---

What I'd like

Any one of these would resolve it:

1. Document the directive in the subagents page, and state plainly that automatic description-based delegation is best-effort and may be suppressed.
2. Make it configurable — an opt-out for users who have deliberately built a subagent library and want description-based routing.
3. Scope it — e.g. apply it to built-in agents/workflows but not to user-defined agents in ~/.claude/agents/, which exist precisely because the user already asked for them.

Option 3 seems closest to the intent: a user who authored a subagent and wrote its trigger condition has, in a meaningful sense, already requested it.

---

Environment

• Claude Code 2.1.220 (also verified 2.1.219, 2.1.218)
• macOS, arm64
• Subagents: 28 user-scope agents in ~/.claude/agents/
• No enterprise managed settings; no MCP-provided agents involved