research: Stop/SubagentStop additionalContext (Claude Code 2.1.183) — candidate for knowledge write-back enforcement

[dean0x]

What the feature is

Claude Code 2.1.183 changelog: "additionalContext from Stop / SubagentStop — hooks can return context to keep the turn going."

Semantics (per hooks docs, verify at implementation time):

• A Stop hook may return hookSpecificOutput.additionalContext; the turn continues in the same context window with that text injected — a soft, opt-in advisory, unlike decision: "block" which hard-stops with an error label.
• Opt-in per fire: hook emits nothing → normal stop. Loop guard via stop_hook_active input field (hook must not re-inject when true). Known flakiness: Stop hook fires repeatedly when system reminders interleave with stop attempts (stop_hook_active not propagating) anthropics/claude-code#54360.
• SubagentStop variant injects into the parent session as a subagent finishes.
• Works in claude -p (single continuation, no loop).
• Cost: same turn, same window — no new session/model spawn.

Evaluation against our three background mechanisms

Mechanism	Fit	Why
Knowledge write-back (knowledge_writeback at end of implement/resolve/self-review/explore/debug)	Strong — the candidate use	Today write-back only happens if the command prompt survives to its final step (compaction or early exit can eat it). A Stop hook could detect "workflow ran but no knowledge write-back happened" and inject a reminder — the model completes write-back in the same turn. Deterministic safety net, zero extra sessions.
Working memory (detached claude -p --model haiku worker)	Poor	Refresh must run per-turn without burning main-session tokens/attention; injecting "rewrite WORKING-MEMORY.md" into the user's turn would do exactly that. Detached haiku worker stays.
Decisions/dream	Neutral	Cadence is per-session, not per-turn; Stop-time injection has no advantage over the SessionStart path.

Proposed follow-up

1. Prototype a Stop hook for knowledge write-back enforcement: cheap detection signal (e.g., a workflow-started sentinel written by the command, cleared by knowledge_writeback), inject only when the sentinel is stale, respect stop_hook_active, version-gate ≥ 2.1.183.
2. Decide whether it replaces or backstops the in-command knowledge_writeback partial (backstop first — keep the in-command path as primary).
3. Re-verify exact additionalContext semantics against the live version before building (some sources are community blogs, not official docs).

Origin: spotted in the changelog during the dream-system simplification review (2026-07-04). Out of scope for PR #248.