[FEATURE/DOCS] SessionStart `initialUserMessage` is ignored in interactive sessions — support it, or warn and document as `-p`-only

Update 2026-08-18. Not a regression. My v2.1.227 evidence came from headless runs (claude -p, entrypoint: sdk-cli), not the interactive TUI. initialUserMessage is -p-only by design and the TUI has never consumed it. See the maintainer's reproduction and my correction. What remains: support initialUserMessage in interactive sessions, or at minimum warn when it is dropped and add the -p-only caveat to the hooks summary table. Original report below, unedited.

Summary

A SessionStart hook that returns hookSpecificOutput.initialUserMessage no longer has any effect as of v2.1.228. The hook still runs (exit 0, stdout captured in the transcript), but the message is never enqueued. The exact same configuration enqueues and executes the message on v2.1.227. The v2.1.228 changelog does not mention any change to SessionStart hook output or queued messages.

Environment

• Claude Code v2.1.228 (regression) vs v2.1.227 (works), native installer, arm64
• macOS (Darwin 25.5.0), Terminal.app, tui: fullscreen
• Interactive TUI sessions (entrypoint cli)

Reproduction

1. Hook script ~/.claude/hooks/session-color.sh:

#!/usr/bin/env bash
printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","initialUserMessage":"/color purple"}}'

1. Register it in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "$HOME/.claude/hooks/session-color.sh", "timeout": 5 }
        ]
      }
    ]
  }
}

1. Start a new interactive session (claude).

Expected (= v2.1.227 behavior)

The message is enqueued as the first user input and, being a slash command, executes locally. Transcript on v2.1.227 shows the full chain:

{"attachment":{"type":"hook_success","hookName":"SessionStart:startup","exitCode":0,"stdout":"{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"initialUserMessage\":\"/color purple\"}}", ...}}
{"type":"queue-operation","operation":"enqueue","content":"/color purple", ...}
{"type":"system","subtype":"local_command","content":"<local-command-stdout>Session color set to: purple</local-command-stdout>", ...}
{"type":"agent-color","agentColor":"purple", ...}

Actual on v2.1.228

The hook runs and its stdout is captured identically, but no enqueue ever happens. Transcript shows the hook_success record with the same valid JSON stdout — then nothing. The first queue-operation in the session is the user's own typed message.

Ruled out

• Hook not firing: hook_success with hookName: "SessionStart:startup", exit 0, correct stdout is present in the v2.1.228 transcript.
• suppressOutput interaction: fails with and without "suppressOutput": true alongside hookSpecificOutput.
• Environment: reproduced with a scrubbed environment (env -i HOME=... PATH=... TERM=xterm-256color).
• -n <name> flag: fails with and without it.
• Feature removal: strings on the v2.1.228 binary still contains initialUserMessage (same count as v2.1.227).
• Changelog: no entry in 2.1.228 mentions SessionStart output, initialUserMessage, or message queueing. The only command-dispatch-adjacent entry is the skill-shadowing hardening.

Impact

initialUserMessage is the only documented way for a hook to run a local slash command at session start (e.g. auto-assigning /color per session — see feature requests #58588 and #49293, which point users at exactly this mechanism). With it silently dropped, those workflows break with no error anywhere.