System prompt line 'Do not call the AgentTool unless the user requested it' overrides explicit user configuration and is not configurable

Summary

The system prompt contains the line:

Do not call the AgentTool unless the user requested it

This line is injected on every turn, cannot be disabled or overridden through any configuration surface, and in practice overrides an explicit, documented user instruction to the contrary. The result is degraded output quality and higher token consumption — the opposite of what the guardrail presumably intends.

Why this is a problem

1. It overrides explicit user configuration.

I had instructed Claude to use subagents for investigations. This was documented in three places:

• global CLAUDE.md, section on roles ("subagents in parallel for independent research")
• global CLAUDE.md, section on parallelisation
• a persistent memory file stating explicitly that the harness line is permanently satisfied by the project rule

Claude still avoided subagents throughout a long session, and — when asked why — cited the system prompt line as the reason, describing it as a conflict it resolved "in favour of the more restrictive reading".

2. It is structurally privileged over user configuration.

CLAUDE.md and memory files are loaded once, at session start, and lose salience as the context grows. The system prompt line is re-injected every turn. This is not a fair contest between instructions — it is a frequency asymmetry. In our case the user instruction only started taking effect after we built a UserPromptSubmit hook that re-injects a counter-instruction at the same frequency.

3. Everything else in that system prompt is configurable — this is not.

Permissions, model, language, hooks, attribution, MCP servers, plugins: all steerable through settings.json. This particular behavioural rule has no corresponding switch. There is no obvious reason why it could not live next to permissions.

Concrete impact (measured, one working day)

With subagent use suppressed, at least four multi-step investigations ran inline in the main context. Each carried its failed attempts with it — wrong regex, invalid CLI format strings, a discarded shell implementation later rewritten in Python. Roughly a dozen throwaway intermediate states ended up permanently in the main context, when only the final numbers mattered. Conservatively that is several thousand tokens of pure noise, and every subsequent decision in that session was made against a more cluttered context.

The workaround now costs ~65 tokens per turn, indefinitely, purely to neutralise a default the user had already opted out of twice in writing.

Proposed fix

Make it configurable, e.g.:

{
  "agentToolPolicy": "on-request" | "allowed" | "encouraged"
}

with on-request remaining the default, so nothing changes for users who never touch it.

Alternatively — and cheaper to implement — soften the line so that a documented CLAUDE.md instruction demonstrably takes precedence, e.g. "Prefer not to call the AgentTool unless the user requested it or project instructions direct otherwise." The current phrasing gives no room for user configuration to win, which is why it kept being cited as a blocker.

Environment

• Claude Code CLI, long-running session (several hours, context compacted once)
• Configuration via global CLAUDE.md, project CLAUDE.md, memory files, and settings.json hooks