fix(hook): emit SessionStart hint via systemMessage JSON contract (#5)

Author: nnemirovsky

.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "owner": {
     "name": "nnemirovsky"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "license": "MIT"
 }

hooks/handlers/session-start.sh

@@ -4,20 +4,21 @@
 # Purpose:
 #   One-time, best-effort hint nudging brand-new passthru users to run
 #   `/passthru:bootstrap` if they already have native permission rules in
-#   their `~/.claude/settings.json` that could be imported. Prints a
-#   single-line plain-text message on stdout, which Claude Code surfaces
-#   in the session header as "SessionStart:startup says: <text>". Then
-#   touches a marker so the hint does not fire again.
+#   their `~/.claude/settings.json` that could be imported. Emits a JSON
+#   envelope `{"systemMessage": "<text>"}` on stdout, which Claude Code
+#   surfaces in the session view as "SessionStart:startup says: <text>".
+#   Then touches a marker so the hint does not fire again.
 #
 # Contract:
 #   stdin  - JSON envelope from Claude Code (SessionStart hook). We do
-#            not need any of its fields; we still drain stdin defensively
-#            so the writer does not hit SIGPIPE.
-#   stdout - a single line of plain text when the hint should fire,
-#            otherwise EMPTY. Per Claude Code docs, SessionStart stdout
-#            is appended to the session view as
-#            "SessionStart:startup says: <text>". Anything else (e.g.
-#            `{}`) would appear verbatim to the user.
+#            not need any of its fields, and `exec < /dev/null` up front
+#            ensures nothing downstream ever blocks on reading it.
+#   stdout - a single-line JSON object `{"systemMessage":"<text>"}` when
+#            the hint should fire, otherwise EMPTY. Per Claude Code
+#            docs, SessionStart `systemMessage` is surfaced in the
+#            session view as "SessionStart:startup says: <text>". Plain
+#            text stdout does NOT surface - the JSON envelope is the
+#            correct contract.
 #   exit   - always 0. Any error fails open (empty stdout, exit 0).
 #
 # Gating:
@@ -28,14 +29,23 @@
 #     marker and exit silently.
 #   - If `~/.claude/settings.json` has no `.permissions.allow` entries,
 #     there is nothing to import - touch the marker and exit silently.
-#   - Otherwise: count the allow entries, emit the hint on stdout, touch
-#     the marker.
+#   - Otherwise: count the allow entries, emit the hint as a JSON
+#     `systemMessage` envelope on stdout, touch the marker.
 #
 # Paths honor PASSTHRU_USER_HOME and PASSTHRU_PROJECT_DIR so bats tests
 # never touch the real ~/.claude.
 
 set -euo pipefail
 
+# ---------------------------------------------------------------------------
+# Redirect stdin to /dev/null before sourcing common.sh or running any
+# command that might read from it. SessionStart never needs stdin contents,
+# and on macOS Claude Code can keep the pipe open across `claude --resume`
+# which would hang any cat/read call. This mirrors the pattern used by
+# memsearch's session-start.sh.
+# ---------------------------------------------------------------------------
+exec < /dev/null
+
 # ---------------------------------------------------------------------------
 # Locate and source common.sh (same pattern as pre/post handlers)
 # ---------------------------------------------------------------------------
@@ -58,15 +68,6 @@ fi
 # ---------------------------------------------------------------------------
 trap 'printf "[passthru] unexpected error in session-start.sh\n" >&2; exit 0' ERR
 
-# ---------------------------------------------------------------------------
-# Drain stdin defensively so the parent does not see SIGPIPE on its
-# write end. We do not use the payload; SessionStart fields are not needed
-# for this one-time hint.
-# ---------------------------------------------------------------------------
-if [ ! -t 0 ]; then
-  cat >/dev/null 2>&1 || true
-fi
-
 USER_HOME="$(passthru_user_home)"
 MARKER="${USER_HOME}/.claude/passthru.bootstrap-hint-shown"
 
@@ -132,10 +133,17 @@ if [ "$COUNT" -eq 0 ]; then
 fi
 
 # ---------------------------------------------------------------------------
-# 4. Emit the one-time hint on stdout and persist the marker.
-#    Single line keeps the session header readable.
+# 4. Emit the one-time hint on stdout as a JSON `systemMessage` envelope
+#    and persist the marker. Claude Code surfaces the systemMessage in the
+#    session view as "SessionStart:startup says: <text>".
 # ---------------------------------------------------------------------------
-printf 'passthru: detected %s importable permission rule(s) in ~/.claude/settings.json. Run /passthru:bootstrap to convert them. This tip only shows once.\n' "$COUNT"
+HINT_MSG="passthru: detected ${COUNT} importable permission rule(s) in ~/.claude/settings.json. Run /passthru:bootstrap to convert them. This tip only shows once."
+
+# jq -nc builds a compact JSON object with proper escaping. Fail-open: if
+# jq cannot produce output, we stay silent rather than emit broken JSON.
+if ENVELOPE="$(jq -nc --arg msg "$HINT_MSG" '{systemMessage:$msg}' 2>/dev/null)"; then
+  printf '%s\n' "$ENVELOPE"
+fi
 
 touch_marker
 exit 0

tests/session_start_hook.bats

@@ -20,11 +20,13 @@
 # Hermetic via PASSTHRU_USER_HOME / PASSTHRU_PROJECT_DIR.
 #
 # Contract notes:
-#   Per Claude Code docs, SessionStart stdout is plain text and surfaces in the
-#   session view as "SessionStart:startup says: <text>". The handler therefore
-#   emits the hint on stdout (not stderr) when it fires, and emits nothing on
-#   stdout in all other cases - including the marker-present short-circuit -
-#   so the session header stays clean.
+#   Per Claude Code docs, the SessionStart hook surfaces its `systemMessage`
+#   JSON field in the session view as "SessionStart:startup says: <text>".
+#   The handler therefore emits `{"systemMessage":"<text>"}` on stdout when
+#   the hint fires, and emits nothing on stdout in all other cases -
+#   including the marker-present short-circuit - so the session header stays
+#   clean. Plain text stdout does NOT surface, so earlier versions of this
+#   hook were silently ignored by Claude Code.
 
 setup() {
   REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/.." && pwd)"
@@ -65,6 +67,19 @@ run_handler() {
   export status STDOUT STDERR
 }
 
+# assert_hint_envelope: verify STDOUT is a well-formed JSON object with
+# `.systemMessage` containing the passthru hint fragments. Requires jq.
+assert_hint_envelope() {
+  # Must be parseable as JSON.
+  jq -e '.' <<<"$STDOUT" >/dev/null
+  # Must have a systemMessage string field.
+  jq -e '.systemMessage | type == "string"' <<<"$STDOUT" >/dev/null
+  local msg
+  msg="$(jq -r '.systemMessage' <<<"$STDOUT")"
+  [[ "$msg" == *"/passthru:bootstrap"* ]]
+  [[ "$msg" == *"only shows once"* ]]
+}
+
 # ---------------------------------------------------------------------------
 # Marker short-circuit
 # ---------------------------------------------------------------------------
@@ -77,7 +92,7 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  # stdout must be empty - no `{}` noise in the session header.
+  # stdout must be empty - no JSON envelope in the session header.
   [ -z "$STDOUT" ]
   # No stderr hint.
   [ -z "$STDERR" ]
@@ -167,17 +182,27 @@ run_handler() {
 # Actual hint path.
 # ---------------------------------------------------------------------------
 
-@test "session-start: settings.json with N allow entries -> hint on stdout mentions N and /passthru:bootstrap" {
+@test "session-start: settings.json with N allow entries -> hint systemMessage mentions N and /passthru:bootstrap" {
   printf '%s\n' '{"permissions":{"allow":["Bash(ls:*)","Bash(echo hello)","mcp__context7__query-docs"]}}' \
     > "$USER_ROOT/.claude/settings.json"
 
   run_handler '{}'
   [ "$status" -eq 0 ]
 
-  # Hint lands on stdout so Claude Code can surface it in the session header.
-  [[ "$STDOUT" == *"3 importable"* ]]
-  [[ "$STDOUT" == *"/passthru:bootstrap"* ]]
-  [[ "$STDOUT" == *"only shows once"* ]]
+  # Hint lands on stdout wrapped in the Claude Code JSON contract so it
+  # surfaces as "SessionStart:startup says: <text>".
+  jq -e '.' <<<"$STDOUT" >/dev/null
+  local msg
+  msg="$(jq -r '.systemMessage' <<<"$STDOUT")"
+  [[ "$msg" == *"3 importable"* ]]
+  [[ "$msg" == *"/passthru:bootstrap"* ]]
+  [[ "$msg" == *"only shows once"* ]]
+
+  # Only the systemMessage key should be present - keep the envelope
+  # minimal so we do not accidentally inject context.
+  local keys
+  keys="$(jq -r 'keys | join(",")' <<<"$STDOUT")"
+  [ "$keys" = "systemMessage" ]
 
   # Nothing on stderr in the happy path.
   [ -z "$STDERR" ]
@@ -193,6 +218,7 @@ run_handler() {
   run_handler '{}'
   [ "$status" -eq 0 ]
   [ -n "$STDOUT" ]
+  assert_hint_envelope
   [ -f "$(marker_path)" ]
 
   # Second invocation must be silent on both streams.
@@ -213,8 +239,8 @@ run_handler() {
 
   run_handler 'not-json{{{'
   [ "$status" -eq 0 ]
-  # The hint should still fire (stdin is drained, never parsed).
-  [[ "$STDOUT" == *"/passthru:bootstrap"* ]]
+  # The hint should still fire (stdin is redirected to /dev/null, never parsed).
+  assert_hint_envelope
   # Marker must still be touched since nothing else went wrong.
   [ -f "$(marker_path)" ]
 }
@@ -225,7 +251,7 @@ run_handler() {
 
   run_handler ''
   [ "$status" -eq 0 ]
-  [[ "$STDOUT" == *"/passthru:bootstrap"* ]]
+  assert_hint_envelope
   [ -f "$(marker_path)" ]
 }