Reframe SessionStart hook messages as human-only (LLM ignores them)

[edmondscommerce]

Observation

SessionStart hook output in this repo is written as if the agent (LLM) will read and act on it — e.g. version_check, hook_registration_checker, optimal_config_checker, gitignore_safety_checker, suggest_status_line. Empirically, the LLM almost entirely ignores SessionStart content.

Direct evidence (dogfooded 2026-06-04): in a live session, the agent could not recall a single line of its own SessionStart message, while it reliably saw UserPromptSubmit additional context (git status, POST-CLEAR notice) on every turn and immediately obeyed PreToolUse blocks. SessionStart context is injected once, positionally buried, and compacted away.

Notably, Claude Code's own designers route the "act now" POST-CLEAR signal through UserPromptSubmit, not SessionStart — corroborating that SessionStart is not where agent-actionable guidance belongs.

Proposal

Treat SessionStart messages as entirely for the human developer (who DOES see them at session start), and stop expecting the LLM to act on them.

Concretely:

1. Audit every SessionStart handler's output and rewrite it to be human-targeted (status/summary the developer reads), not agent-instructions.
2. Move any LLM-actionable guidance that currently lives in SessionStart to a stickier channel:
   • PreToolUse interception (block/advisory at the relevant action — strongest),
   • UserPromptSubmit additionalContext (re-injected every turn; once-per-session for nudges, alongside post_clear_auto_execute),
   • get_claude_md() injection into the project CLAUDE.md <hooksdaemon> block (always-on policy).
3. Reassess whether version_check's "update available" advisory is effective at all given this — it may need to move channels.

Channel stickiness (observed ranking)

1. PreToolUse deny / action interception — strongest (stops the action, perfectly recalled)
2. UserPromptSubmit additionalContext — reliably seen every turn
3. get_claude_md() / CLAUDE.md block — always-on but "wallpaper"
4. PostToolUse advisory — tuned out (repetition ≠ attention)
5. SessionStart — weakest, nearly ignored

Context

Surfaced while designing Plan 00118 (docs-upgrade guidance mechanism), whose Phase 5 originally proposed a SessionStart advisory and was redesigned onto action-interception channels as a result. This issue tracks the broader audit of existing SessionStart handlers.