Plan-mode injected workflow overrides project CLAUDE.md conventions (agent fan-out, chat plan file) despite CLAUDE.md being marked as overriding defaults

Summary

The plan-mode feature's injected workflow instructions direct the model to override project CLAUDE.md conventions that Claude Code itself loads with the wrapper "IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written." The two instruction sources give contradictory precedence signals, and in practice the model followed the more proximate, more imperative plan-mode injection — at real token cost and with workflow effects the project's process then had to unwind.

Environment

• Claude Code CLI 2.1.217, macOS (darwin), model claude-fable-5

Setup

Our repository's checked-in CLAUDE.md defines:

1. A planning gate: implementation plans are drafted as a reviewed document in docs/plans/active/ from a template, on the feature branch, and the maintainer reviews the document before any code ("an in-chat summary answered 'proceed' is a task go-ahead, not a plan review — the document is the review artifact").
2. A code-search convention: a local semantic-search MCP server is to be used first for conceptual lookups — explicitly: "Don't Read a whole file — or fan out reader sub-agents — to locate something [the search tool] finds."

What happened

Asked to pick up a tracked bug, the model:

1. Followed the EnterPlanMode tool guidance ("Prefer using EnterPlanMode for implementation tasks unless they're simple") and entered plan mode instead of the repo's plan-doc process.
2. Once in plan mode, the injected phase workflow instructed it: "Critical: In this phase you should only use the Explore subagent type", "Launch up to 3 Explore agents IN PARALLEL (single message, multiple tool calls)", to build the plan in a chat-side plan file, and "your turn should only end with either using the AskUserQuestion tool OR calling ExitPlanMode."
3. It complied: launched an unrequested Explore subagent (~90k tokens) duplicating what the project's mandated search tool provides at a fraction of the cost, and produced a chat-file plan that the project's review process rejects by design.

The user had to intervene twice ("you should not have been using plan mode and doing a plan in chat"; "you also used agents without first asking for permission"), and the planning work was redone through the repo's own process.

Why this is a product issue, not just a model miss

Claude Code injects CLAUDE.md under an instruction that it OVERRIDES default behavior — but then injects feature workflows (plan-mode phases) that are more recent, more specific, and more imperative, with no subordination clause. When both prescribe a workflow for the same activity (planning, code exploration), the model is set up to resolve the contradiction wrongly. The failure mode is systematic, not incidental.

Requests

1. Subordination clause: plan-mode phase instructions (and similar injected feature workflows) should explicitly defer to project conventions, e.g. "If the project's CLAUDE.md defines its own planning or code-search process, follow that process instead of the phases below."
2. Per-project opt-out: a supported setting to disable plan mode / the injected phase workflow for a repository. We currently hand-roll this with a PreToolUse hook that hard-denies EnterPlanMode (workaround below).
3. Agent-launch guidance should respect approval posture: "Launch up to 3 Explore agents IN PARALLEL" should not be an unconditional directive; token-expensive fan-outs should be gated on user approval or at minimum acknowledge project/user rules requiring approval.

Workaround (for others hitting this)

Project .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "EnterPlanMode",
        "hooks": [{ "type": "command", "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Plan mode disabled: use the repo plan-doc convention.\"}}'" }]
      },
      {
        "matcher": "Agent|Workflow",
        "hooks": [{ "type": "command", "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"Agent/workflow launches require explicit approval.\"}}'" }]
      }
    ]
  }
}