Reduce Stop hook block notification user-facing noise

[ikuwow]

Context

PR #152 introduced the 断り書き Stop hook (claude/hooks/block_excuse_phrases.py) and PR #153 fixed a Claude Code transcript flush race for pure-text turns. The hook now reliably catches 断り書き usage on every turn type, including pure-text responses.

A side effect surfaces in the chat UI: every block emits a verbose "Stop hook feedback: ..." message visible to the user, on top of the model's natural acknowledgment-and-rewrite. The signal is the correction itself; the noise is a multi-paragraph block notification plus an explicit "ごめん書き直す" preamble in the model's reply.

This issue tracks reducing that noise. Current behavior is acceptable for now but verbose.

Options

Approach	UX impact	Cost / risk
A. Replace reason with additionalContext in the hook output JSON	Block notification disappears from the chat. Model still receives the reconsideration prompt as silent context, so reconsideration behavior is unchanged. The model's reply may still contain an acknowledgment ("rewriting...") that surfaces in the chat.	One-line code change. Empirically verify Claude Code accepts additionalContext for Stop hook block decisions.
B. A combined with REASON text rewritten to instruct silent rewrite (e.g. "Rewrite without comment, do not apologize, output only the corrected response")	Block notification gone, model's acknowledgment also suppressed.	A plus prompt tuning; risk of the model occasionally ignoring the silent-rewrite instruction (LLM nondeterminism).
C. Retroactively erase the original output containing 「正直」 etc. so only the corrected version reaches the user	True no-trace-of-bad-version behavior.	Not achievable at the hook level. Requires Claude Code core to buffer assistant output until the Stop hook approves.

Decision (deferred)

Investigated 2026-05-01. Will revisit when verbosity becomes annoying in practice.

The current behavior is informative — the bad-then-corrected dual visibility preserves narrative flow ("here is what was wrong, here is the corrected version") that pure-silent rewrite would break. LLM nondeterminism makes Option B's acknowledgment suppression unreliable in the worst case.

Upstream

Option C would benefit from a Claude Code feature: buffered Stop hook output, where assistant text is held until the Stop hook decides whether to approve or block. Currently the assistant text is streamed to the user before the Stop hook fires. Filing this as a feature request to anthropics/claude-code is a separate decision; not pursued in this issue.

References

• PR Add Stop hook to pause once on 断り書き phrases #152: initial 断り書き Stop hook
• PR Poll transcript on Stop hook to handle pure-text flush race #153: pure-text flush race fix
• Claude Code hooks reference
• Stop hook output schema fields verified via WebFetch

[ikuwow]

Verify result: Option A is not supported

Verified against the official hooks reference at https://code.claude.com/docs/en/hooks .

• additionalContext is listed only under the "Context only" decision pattern for SessionStart, Setup, and SubagentStart. Not part of the Stop hook output schema.
• Stop hook block decision schema is {decision: "block", reason: "..."}. reason surfaces in the chat UI as "Stop hook feedback".
• suppressOutput: true is a universal field but only hides hook stdout from the transcript; it does not silence the block reason text.

Closest documented alternatives:

1. suppressOutput: true + reason — partial; reason still shown.
2. Convert to a type: "prompt" Stop hook — reason is routed to the model as feedback rather than shown as a separate UI message. Larger refactor.

Option A as originally proposed is infeasible. Leaving open until an alternative (likely option 2) is decided.

[ikuwow]

2026-06-07 re-check of https://code.claude.com/docs/en/hooks:

The decision-control table now lists Stop and SubagentStop as accepting hookSpecificOutput.additionalContext in addition to the top-level decision: "block" + reason pattern. This contradicts the 2026-05-30 verify above (which said additionalContext was Context-only). The official text:

Stop and SubagentStop also accept hookSpecificOutput.additionalContext for non-error feedback that continues the conversation

That makes Option A plausible again, with one open question the docs do not answer: does additionalContext alone (no decision: "block") actually force the assistant to continue and reconsider, or does the assistant still stop because decision is absent? "Continues the conversation" reads two ways. Empirical test on this hook is needed before flipping the output schema.

Three concrete options now:

Test	Behavior expected
A1. additionalContext only, no decision	Chat shows no block message; assistant proceeds to next turn with reason as system reminder. If assistant continues current turn rather than stopping → fixes the issue cleanly.
A2. additionalContext + decision: "block" + suppressOutput: true	Forces continuation; tests whether reason UI surface is suppressed by suppressOutput (per the prior verify it is not, but worth confirming the interaction with additionalContext).
Stay on the current decision: "block" + reason only	Current behavior; verbose but reliable.

Recommended test order: A1 first on a no-op rule (e.g. a Stop hook that emits additionalContext unconditionally) to settle the "continues" semantics, then decide.

Leaving open with this as the next-step pointer; not converting to a PR until A1 is empirically verified.