[FEATURE] `OnSystemReminder` hook event with `reminder_text` payload

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] 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.

1. The harness emits a <system-reminder> to the model: "file X was

modified externally; this change was intentional".

1. With this hook, an OnSystemReminder integration receives

reminder_text and reminder_kind="file_modified". It writes a
marker file ~/.claude/.pending_external_edit_<hash>.

1. 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".

1. The user resolves the conflict explicitly (re-read the file,

acknowledge the change, etc.). The integration clears the marker.

1. 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