claude-code - 💡(How to fix) Fix [FEATURE] Revive #24244 — Stop hook needs additionalContext (or continueWith) for clean workflow continuation

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

Stop hooks cannot deliver "soft" workflow reminders back to Claude. The current schema disallows hookSpecificOutput.additionalContext on Stop hook outputs (validation error: "hookEventName: Stop" is not a permitted value for hookSpecificOutput). The only mechanism that injects context from a Stop hook is decision: "block" + reason, which:

1. Renders as a red "Stop hook blocked" error banner in the UI (semantically wrong — this is workflow continuation, not failure).
2. Forces Claude to continue. There is no "soft" mode that lets Claude show the reminder, and lets the user decide whether to act on it.
3. Has no built-in infinite-loop protection — if the hook keeps detecting the same condition (e.g. an artifact that never gets written), Claude is forced to retry indefinitely.
4. Conflates two semantically distinct outcomes (block = error vs block = continuation hint) into one field.

Concrete use case (the one that surfaced this for us)

I'm building a multi-agent orchestrator (dev-orchestrator + worker subagents, YAML task contracts, SQLite ledger). One requirement: after a task is marked done, if the task's risk_class=high or touched sensitive paths (auth/payments/schema/migration), the orchestrator MUST run /codex:review or /codex:adversarial-review and persist the result as a task artifact.

In practice, the LLM-driven orchestrator occasionally forgets this discipline in long sessions. A Stop hook is the natural safety net: read the task DB, find recently-done tasks missing a codex_review artifact, gently nudge the orchestrator to address them before the user's next interaction.

My first attempt:

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "⚠ Codex debt detected:\n  - TASK-599a: needs /codex:adversarial-review\n  - TASK-601: needs /codex:review"
  }
}

Rejected by the schema validator. I had to fall back to a UserPromptSubmit hook that fires the reminder on the NEXT user turn — a one-turn delay that defeats the safety-net intent. If the user closes the session right after the orchestrator's "done" turn, the reminder never fires at all, and the unchecked task ships.

The decision: "block" + reason workaround would fire immediately, but every reminder would show as a UI error to a non-developer end-user, which is unacceptable for a polished agent product.

Proposed Solution

Allow Stop hooks to emit hookSpecificOutput.additionalContext (matching the semantics of UserPromptSubmit / PostToolUse). Treat it as a soft hint: Claude receives the context as a reminder before deciding whether to continue, surface it to the user, or quietly note it.

OR — if the schema team prefers a distinct field for "this is a continuation, not an error" — implement the continueWith proposal from #24244 verbatim:

interface StopHookOutput {
  decision?: "approve" | "block";
  reason?: string;
  continueWith?: string;   // Inject as follow-up context, no error UI
  showAsError?: boolean;   // default false
}

Either option closes the gap. The key requirement: a way to inject context from Stop hook that does not paint a red error banner and does not force-block.

Alternative Solutions

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

No response

Additional Context

No response