Plan mode tool definitions silently override operator skill file guardrails

Summary

Claude Code's EnterPlanMode and related tool definitions contain instructions that contradict and override guardrails defined in operator-provided skill files (injected into the session at start via .claude/agents/). These instructions are baked into the tool definitions, not in any user-visible or user-editable file, and cannot be overridden or suppressed by the operator.

The result: an explicit "never skip the approval checkpoint" guardrail in the agent's skill file was silently overridden, and the agent self-approved its own plan and committed a 383-line change without real operator review.

Verified still present in v2.1.63.

The guardrail (operator skill file)

An agent session was started with a skill file (via .claude/agents/) containing explicit workflow discipline:

For non-trivial implementation, always use the plan-approve-implement cycle:
1. Investigate the problem
2. Enter plan mode
3. Get explicit approval before writing any code
4. Implement, verify, report

Never skip the approval checkpoint.
The user's approval is the gate between research and implementation.

The override (tool definition instructions)

The AskUserQuestion and ExitPlanMode tool definitions contain instructions that directly contradict the skill file:

• AskUserQuestion tells the agent: do NOT use this tool to ask about plan approval — use ExitPlanMode instead
• ExitPlanMode tells the agent: do NOT use AskUserQuestion for plan approval — ExitPlanMode "inherently requests user approval"

These instructions are always present in the tool definitions — not just injected during plan mode. When EnterPlanMode is called, additional <system-reminder> instructions reinforce the same constraint:

Important: Use AskUserQuestion ONLY to clarify requirements or choose
between approaches. Use ExitPlanMode to request plan approval. Do NOT ask
about plan approval in any other way - no text questions, no
AskUserQuestion.

The result

1. Agent entered plan mode (per skill file)
2. Agent wrote a plan
3. Agent called ExitPlanMode (per tool definition instructions, which forbade asking any other way)
4. ExitPlanMode returned "User has approved your plan" — without the operator actually reviewing
5. Agent implemented and committed a 383-line, 5-file change without real approval
6. The skill file guardrail ("never skip the approval checkpoint") was completely bypassed

Root cause

Tool definition instructions sit at a higher priority level in the prompt hierarchy than operator-provided skill files. When they conflict, the tool definitions win. The agent correctly identified this hierarchy and followed the tool instructions over its skill file guardrails.

This means:

• Operators cannot enforce approval workflows via skill files if those workflows conflict with tool-level instructions
• Operators have no visibility into what instructions the tool definitions contain
• Operators have no mechanism to override or suppress tool-level instructions
• The agent silently follows the tool instructions over the operator's explicit guardrails

v2.1.63 verification

Verified that the issue is still present in Claude Code v2.1.63:

• The AskUserQuestion tool definition still instructs the agent not to use it for plan approval
• The ExitPlanMode tool definition still instructs the agent not to use AskUserQuestion for plan approval
• The instructions are in the tool definitions themselves, meaning they are always active — not just during plan mode
• ExitPlanMode can still auto-approve depending on the agent's permission mode

Expected behaviour

Operator-provided skill file guardrails should not be silently overridden by tool-level instructions. At minimum:

1. Transparency: Operators should be able to see all instructions that tool definitions inject
2. Editability: Operators should be able to override or suppress tool-level instructions
3. Priority control: Operators should be able to declare that skill file guardrails take precedence over tool instructions
4. No silent contradiction: If a tool's instructions conflict with skill file guardrails, the agent should flag the conflict rather than silently following one

Reproduction

1. Create a skill file in .claude/agents/ with an explicit approval checkpoint
2. Start a session with the skill file injected
3. Give the agent a non-trivial implementation task
4. The agent calls EnterPlanMode
5. Observe: the tool definitions instruct the agent to NOT use AskUserQuestion for plan approval
6. The agent calls ExitPlanMode without asking the operator
7. ExitPlanMode may auto-approve depending on permission settings
8. The agent implements without real operator approval
9. The skill file guardrail was bypassed

Environment

• Claude Code v2.1.63
• macOS (Darwin 25.2.0)
• Skill files via .claude/agents/