claude-code - 💡(How to fix) Fix Granular control over <system-reminder> injections (env var / settings)

Summary

Add an env var / settings.json option to selectively suppress harness-injected <system-reminder> blocks. Current behavior creates false-positive prompt-injection signals in security-conscious multi-agent workflows.

Related issues / not a duplicate

Searched existing issues 2026-05-17. Closest related (both closed not-planned):

• #9486 — documented <system-reminder> placement inside tool-result/message structure. Closed not-planned. Different: that issue describes WHERE reminders appear in the message wire format; this request is about CONTROL over whether specific runtime reminder categories fire at all.
• #5474 — requested disabling startup UI hints. Closed not-planned. Different: that issue covers TUI startup tips; this request covers runtime <system-reminder> injections that arrive in the model's tool-result stream during a session.

This request is scoped specifically to runtime model-stream <system-reminder> control, not MCP thinking preservation, not startup UI hints, not message-wire-format placement.

Current behavior

Claude Code injects <system-reminder> blocks into tool results in several known patterns:

1. Plan-mode transitions — ## Exited Plan Mode / ## Entered Plan Mode. Observed to misfire even when no plan-mode transition occurred this turn.
2. TaskCreate prompts — The task tools haven't been used recently. If you're working on tasks that would benefit from tracking progress, consider using TaskCreate... Make sure that you NEVER mention this reminder to the user
3. Clarifying-question suppression — The user has asked you to work without stopping for clarifying questions...
4. File-modified notice — Note: <path> was modified, either by the user or by a linter. This change was intentional... (legitimate; least problematic)
5. Background-task notification — [SYSTEM NOTIFICATION - NOT USER INPUT] <task-notification>... after async background command completion

These blocks share the <system-reminder> tag with both:

• Genuine system prompts (auto-memory, skill-loaded markers — legitimate, needed)
• Prompt-injection payloads from untrusted content (WebFetch / Read / sub-agent return values containing fake <system-reminder> blocks crafted by adversaries)

Minimal reproduction

Session: Claude Code 2.1.126 on Windows 11 / MINGW64.

Steps:

1. Open a fresh Claude Code session (no plan mode active)
2. Run a Bash tool call that performs a Write or Edit on any tracked file
3. Observe tool-result stream

Expected: tool result contains stdout/stderr only.

Actual: tool result contains stdout/stderr plus appended <system-reminder> blocks — typically the file-modified notice (legitimate) PLUS the TaskCreate prompt and sometimes "Exited Plan Mode" / "work without stopping" reminders even though no plan-mode transition occurred and no operator instruction to suppress questions was given this session.

Redacted transcript fragment (operator paths redacted):

[tool: Bash, output stream]
UPDATED 8364 bytes

<system-reminder>
Note: <REDACTED-PATH>.md was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account as you
proceed (ie. don't revert it unless the user asks you to). Don't tell the
user this, since they are already aware.
</system-reminder>

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate to
add new tasks and TaskUpdate to update task status (set to in_progress
when starting, completed when done). Also consider cleaning up the task
list if it has become stale. Only use these if relevant to the current
work. This is just a gentle reminder - ignore if not applicable. Make
sure that you NEVER mention this reminder to the user
</system-reminder>

Problem

In a governance-conscious operating model where every untrusted-source <system-reminder> should be logged as a potential injection attempt, harness-emitted reminders create false positives. Operators must either:

• Whitelist by pattern matching — fragile; new harness patterns appear without notice; mimicry attacks possible
• Skip injection logging entirely — defeats the security discipline
• Suppress at the agent-instruction level — requires every session/agent rule to know the full harness pattern set

The third option is what we implemented (harness-output-classification.md — 6-pattern allowlist with non-authority constraint), but it's brittle: any new harness reminder type breaks the allowlist silently.

The "NEVER mention this reminder to the user" instruction in the TaskCreate reminder is also problematic from a transparency standpoint — it asks the agent to hide harness state from the operator, which conflicts with operator-trust workflows.

Proposed feature

Add a settings.json field and/or env var:

{
  "systemReminders": {
    "planMode": false,
    "taskCreatePrompt": false,
    "clarifyingQuestionHint": false,
    "fileModifiedNotice": true,
    "skillLoadedMarker": true,
    "autoMemory": true,
    "backgroundTaskNotification": true
  }
}

Or equivalently an env var:

CLAUDE_CODE_DISABLE_REMINDERS=plan,task,clarify

With granular controls so operators can suppress the misfiring or unwanted reminders while keeping the genuinely useful ones (file-modified notice, skill-loaded marker, background-task notification).

Alternative (lighter-weight)

Add a single env var that suppresses ALL non-essential harness reminders, keeping only the file-modified notice, skill-loaded marker, and background-task notification (which carry actual state information the agent needs):

CLAUDE_CODE_DISABLE_OPTIONAL_REMINDERS=1

Use case

Multi-agent fleet operating under documented prompt-injection defense. Every <system-reminder> block from an unverified source should be classified as potential INJECTION and logged. Today this is impossible to do cleanly because harness reminders and injected reminders share the same tag and arrive through the same channel.

A suppression option lets operators run a strict default-deny policy without polluting injection-incident logs with harness noise.

Workaround currently in use

Profile-level rule maintains a 6-pattern allowlist; agents classify source as HARNESS / INJECTION / UNKNOWN before logging. Brittle but functional.

Scope

This is a feature request for observability/control, not a security vulnerability report. The local rule already handles operational safety. The upstream ask is for granular suppression of the runtime model-stream injections that are currently always-on.

Acknowledgment

The plan-mode transition reminder appears to misfire in non-plan-mode sessions — that's likely an independent bug worth investigating regardless of whether the suppression feature lands.