fix(hook): emit SessionStart hint on stdout so it's visible (#4)

Author: nnemirovsky

.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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.0",
+  "version": "0.2.1",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "license": "MIT"
 }

hooks/handlers/session-start.sh

@@ -5,19 +5,20 @@
 #   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
-#   stderr message at the start of the Claude Code session (SessionStart
-#   stderr is visible to the user) and touches a marker so the hint does
-#   not fire again.
+#   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.
 #
 # 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 - `{}` (no additional context). SessionStart hooks can return
-#            an `additionalContext` field, but we keep the session-log
-#            hint off-session via stderr to avoid nagging inside the
-#            conversation.
-#   exit   - always 0. Any error fails open.
+#   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.
+#   exit   - always 0. Any error fails open (empty stdout, exit 0).
 #
 # Gating:
 #   - If the marker file `${PASSTHRU_USER_HOME}/.claude/passthru.bootstrap-hint-shown`
@@ -27,7 +28,7 @@
 #     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 to stderr, touch
+#   - Otherwise: count the allow entries, emit the hint on stdout, touch
 #     the marker.
 #
 # Paths honor PASSTHRU_USER_HOME and PASSTHRU_PROJECT_DIR so bats tests
@@ -46,17 +47,16 @@ else
   _PASSTHRU_COMMON="${_PASSTHRU_HANDLER_DIR}/../common.sh"
   if [ ! -f "$_PASSTHRU_COMMON" ]; then
     # Never block session start, even on a broken install.
-    printf '{}\n'
     exit 0
   fi
   # shellcheck disable=SC1090
   source "$_PASSTHRU_COMMON"
 fi
 
 # ---------------------------------------------------------------------------
-# Fail-open wrapper: any unexpected error prints {} + exit 0.
+# Fail-open wrapper: any unexpected error prints nothing + exit 0.
 # ---------------------------------------------------------------------------
-trap 'printf "[passthru] unexpected error in session-start.sh\n" >&2; printf "{}\n"; exit 0' ERR
+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
@@ -74,7 +74,6 @@ MARKER="${USER_HOME}/.claude/passthru.bootstrap-hint-shown"
 # 1. Marker already set -> silent no-op.
 # ---------------------------------------------------------------------------
 if [ -e "$MARKER" ]; then
-  printf '{}\n'
   exit 0
 fi
 
@@ -86,7 +85,6 @@ fi
 MARKER_DIR="$(dirname "$MARKER")"
 if [ ! -d "$MARKER_DIR" ]; then
   mkdir -p "$MARKER_DIR" 2>/dev/null || {
-    printf '{}\n'
     exit 0
   }
 fi
@@ -107,7 +105,6 @@ PROJECT_IMPORTED="$(passthru_project_imported_path)"
 if [ -f "$USER_AUTHORED" ] || [ -f "$USER_IMPORTED" ] \
    || [ -f "$PROJECT_AUTHORED" ] || [ -f "$PROJECT_IMPORTED" ]; then
   touch_marker
-  printf '{}\n'
   exit 0
 fi
 
@@ -131,17 +128,14 @@ fi
 
 if [ "$COUNT" -eq 0 ]; then
   touch_marker
-  printf '{}\n'
   exit 0
 fi
 
 # ---------------------------------------------------------------------------
-# 4. Emit the one-time hint and persist the marker.
+# 4. Emit the one-time hint on stdout and persist the marker.
+#    Single line keeps the session header readable.
 # ---------------------------------------------------------------------------
-printf '[passthru] Detected %s importable rule(s) in your existing settings.json.\n' "$COUNT" >&2
-printf '[passthru] Run /passthru:bootstrap to import them into passthru'\''s regex format.\n' >&2
-printf '[passthru] This hint only shows once.\n' >&2
+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"
 
 touch_marker
-printf '{}\n'
 exit 0

hooks/hooks.json

@@ -27,6 +27,7 @@
     ],
     "SessionStart": [
       {
+        "matcher": "startup",
         "hooks": [
           {
             "type": "command",

tests/plugin_loads.bats

@@ -137,6 +137,14 @@ setup() {
   [ "$output" = "1" ]
 }
 
+@test "hooks/hooks.json SessionStart matcher is startup" {
+  # Restricts the one-time hint to brand-new sessions. Resume/clear/compact
+  # must not re-fire it.
+  run jq -r '.hooks.SessionStart[0].matcher' "$REPO_ROOT/hooks/hooks.json"
+  [ "$status" -eq 0 ]
+  [ "$output" = "startup" ]
+}
+
 @test "hooks/hooks.json SessionStart command uses CLAUDE_PLUGIN_ROOT" {
   run jq -r '.hooks.SessionStart[0].hooks[0].command' "$REPO_ROOT/hooks/hooks.json"
   [ "$status" -eq 0 ]

tests/session_start_hook.bats

@@ -14,10 +14,17 @@
 #   * marker absent + no passthru files + settings.json with empty allow
 #                                                          -> marker created, no hint
 #   * marker absent + no passthru files + settings.json with N allow entries
-#                                                          -> hint on stderr, marker created
+#                                                          -> hint on stdout, marker created
 #   * malformed stdin                                      -> fail open (exit 0, no crash)
 #
 # 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.
 
 setup() {
   REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/.." && pwd)"
@@ -70,8 +77,8 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  # stdout is just "{}\n".
-  [ "$STDOUT" = "{}" ]
+  # stdout must be empty - no `{}` noise in the session header.
+  [ -z "$STDOUT" ]
   # No stderr hint.
   [ -z "$STDERR" ]
 }
@@ -86,7 +93,7 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
   [ -f "$(marker_path)" ]
 }
@@ -97,7 +104,7 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
   [ -f "$(marker_path)" ]
 }
@@ -108,7 +115,7 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
   [ -f "$(marker_path)" ]
 }
@@ -119,7 +126,7 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
   [ -f "$(marker_path)" ]
 }
@@ -131,7 +138,7 @@ run_handler() {
 @test "session-start: no passthru files and no settings.json -> marker created, no hint" {
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
   [ -f "$(marker_path)" ]
 }
@@ -141,7 +148,7 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
   [ -f "$(marker_path)" ]
 }
@@ -151,7 +158,7 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
   [ -f "$(marker_path)" ]
 }
@@ -160,18 +167,20 @@ run_handler() {
 # Actual hint path.
 # ---------------------------------------------------------------------------
 
-@test "session-start: settings.json with N allow entries -> hint on stderr mentions N and /passthru:bootstrap" {
+@test "session-start: settings.json with N allow entries -> hint on stdout 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 ]
-  [ "$STDOUT" = "{}" ]
 
-  # Hint mentions the count (3) and the slash command name.
-  [[ "$STDERR" == *"Detected 3 importable rule(s)"* ]]
-  [[ "$STDERR" == *"/passthru:bootstrap"* ]]
-  [[ "$STDERR" == *"only shows once"* ]]
+  # Hint lands on stdout so Claude Code can surface it in the session header.
+  [[ "$STDOUT" == *"3 importable"* ]]
+  [[ "$STDOUT" == *"/passthru:bootstrap"* ]]
+  [[ "$STDOUT" == *"only shows once"* ]]
+
+  # Nothing on stderr in the happy path.
+  [ -z "$STDERR" ]
 
   # Marker is created so we do not re-hint.
   [ -f "$(marker_path)" ]
@@ -183,12 +192,13 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ -n "$STDERR" ]
+  [ -n "$STDOUT" ]
   [ -f "$(marker_path)" ]
 
-  # Second invocation must be silent.
+  # Second invocation must be silent on both streams.
   run_handler '{}'
   [ "$status" -eq 0 ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
 }
 
@@ -203,8 +213,8 @@ run_handler() {
 
   run_handler 'not-json{{{'
   [ "$status" -eq 0 ]
-  # stdout is still valid (either {} or the hint, but process did not crash).
-  [ "$STDOUT" = "{}" ]
+  # The hint should still fire (stdin is drained, never parsed).
+  [[ "$STDOUT" == *"/passthru:bootstrap"* ]]
   # Marker must still be touched since nothing else went wrong.
   [ -f "$(marker_path)" ]
 }
@@ -215,7 +225,7 @@ run_handler() {
 
   run_handler ''
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [[ "$STDOUT" == *"/passthru:bootstrap"* ]]
   [ -f "$(marker_path)" ]
 }
 
@@ -228,7 +238,7 @@ run_handler() {
 
   run_handler '{}'
   [ "$status" -eq 0 ]
-  [ "$STDOUT" = "{}" ]
+  [ -z "$STDOUT" ]
   [ -z "$STDERR" ]
   [ -f "$(marker_path)" ]
 }