claude-code - 💡(How to fix) Fix [FEATURE] `OnSystemReminder` hook event with `reminder_text` payload

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

When the harness injects a <system-reminder> block into the model's context (e.g., file-modification notifications, hook-injected reminders, harness-side notices, mode-switch announcements), no hook fires. The reminder is visible only inside the model's context window — there is no observation point for integrations.

The current event list covers user input (UserPromptSubmit), tool calls (PreToolUse/PostToolUse), per-session lifecycle (SessionStart/SessionEnd), and post-turn (Stop/StopFailure), but provides no hook for harness-injected context. This leaves an asymmetry: every other channel by which content reaches the model is hookable; system-reminders are not.

Proposed Solution

Add an OnSystemReminder hook event that fires when a <system-reminder> is injected into the model's context. Payload follows existing conventions:

{
  "hook_event_name": "OnSystemReminder",
  "session_id": "...",
  "cwd": "...",
  "transcript_path": "...",
  "permission_mode": "default",
  "reminder_text": "<the system-reminder text being injected>",
  "reminder_kind": "<categorisation if available — e.g., 'file_modified', 'hook_injected', 'harness_notice', 'mode_switch'>"
}

Two output modes:

• Observational (default) — hook reads, may log / mirror / trigger external actions; cannot suppress or modify the reminder.
• Optional additionalContext injection — if the hook chooses to append context (per the existing UserPromptSubmit convention), the appended text is added alongside the reminder before the model sees the combined block.

The event should fire on every system-reminder injection regardless of source (harness-emitted, hook-injected, mode-change announcements, etc.) so integrations have a single observation point for the full reminder stream.

Alternative Solutions

Each of the following has been considered and falls short:

• Polling the conversation transcript file for system-reminder detection — works but races against the model's first observation of the reminder; cannot gate or block. By the time polling detects the reminder, the model has already responded.
• Reading the transcript via PreToolUse hook on every subsequent tool call — same race; also fires too late and conflates reminder observation with tool gating.
• Existing UserPromptSubmit hook — fires only on user input, not on harness-injected reminders. Reminders can arrive cross-turn (between user prompts) and are missed entirely.
• Existing PostToolUse hook — receives tool_output only, not any reminder text the harness may inject in response to the tool result.

None approximate the proposed event. The capability gap is genuine.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

Cross-turn marker mechanism for file-edit safety:

1. The user edits a project file directly in their editor while Claude is mid-task on the same project.
2. The harness emits a <system-reminder> to the model: "file X was modified externally; this change was intentional".
3. With this hook, an OnSystemReminder integration receives reminder_text and reminder_kind="file_modified". It writes a marker file ~/.claude/.pending_external_edit_<hash>.
4. On the next PreToolUse for any tool targeting file X, the integration's PreToolUse hook checks the marker, returns permissionDecision: "deny" with reason "external edit detected; confirm with user before proceeding".
5. The user resolves the conflict explicitly (re-read the file, acknowledge the change, etc.). The integration clears the marker.
6. Tool calls on file X resume.

Why this needs the hook: today, the model sees the <system-reminder> and may or may not internalise it. Without an observation point, an integration cannot reliably gate downstream behaviour on the reminder content. Polling the transcript is too late (by the time polling detects the reminder, the model has already responded). The proposed event closes the gap with a single observation point at injection time.

Additional Context

A repo search 2026-05-09 confirmed no existing feature request for this hook event. There is, however, substantial discussion of the system-reminder mechanism's behaviour and bugs — these are symptoms of integrations needing to observe / react to reminder content but having no observation point:

• #56867 — "System reminders inserted after every tool call disrupt long-running multi-step work"
• #50331 — "Auto mode injects undocumented behavioral system-reminder that steers beyond its documented permission-gate contract"
• #46465 / #52018 — "Harness-emitted <system-reminder> uses 'NEVER mention this reminder to the user' phrasing indistinguishable from prompt injection"

Compatibility: the proposed event is purely additive — existing hooks and configurations continue to work unchanged. Adoption is opt-in: users who don't configure OnSystemReminder see no behaviour change.

Payload size: if reminder text size is a concern in any high-volume case, options include a configurable max-bytes truncation parameter or a separate reminder_text_path field pointing to a temp file the hook can read on demand.

🤖 Generated with Claude Code