feat(hooks): title sessions "host project" for the remote session list

Remote sessions showed up on claude.ai/code and mobile under auto-generated names, so picking the right one meant guessing. Claude Code 2.1.152+ lets a SessionStart hook set the title via hookSpecificOutput.sessionTitle.

hooks/session-title.sh emits "<uname -n> <project>" (ratio rulesets, velox work) on startup and resume. Project is the git-toplevel basename so a session started in a subdirectory still names the project, with the cwd basename as fallback. The hook stays silent when a title already exists, so a /rename or an earlier run isn't clobbered on resume. The harness ignores titles on clear and compact, so the settings matcher restricts to startup|resume.

Wired in settings.json and the install-hooks snippet. As a default hook it reaches every machine through make install on the next session start.

1 files changed, 70 insertions, 0 deletions

diff --git a/scripts/tests/session-title-hook.bats b/scripts/tests/session-title-hook.bats
new file mode 100644
index 0000000..60b633d
--- /dev/null
+++ b/scripts/tests/session-title-hook.bats
@@ -0,0 +1,70 @@
+#!/usr/bin/env bats
+# hooks/session-title.sh — SessionStart hook that titles the session
+# "<host> <project>" (uname -n + git-toplevel basename, cwd basename outside
+# a repo) so remote sessions are identifiable on web/mobile. It only sets a
+# title when the session doesn't have one yet: a /rename or an earlier run
+# must not be clobbered on resume.
+
+setup() {
+    REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)"
+    SCRIPT="$REPO_ROOT/hooks/session-title.sh"
+    TMPDIR_T="$(mktemp -d)"
+    HOST="$(uname -n)"
+}
+
+teardown() {
+    rm -rf "$TMPDIR_T"
+}
+
+run_hook() {
+    # $1 = cwd, $2 = optional existing session_title
+    if [ -n "${2:-}" ]; then
+        printf '{"cwd":"%s","source":"startup","session_title":"%s"}' "$1" "$2" | sh "$SCRIPT"
+    else
+        printf '{"cwd":"%s","source":"startup"}' "$1" | sh "$SCRIPT"
+    fi
+}
+
+@test "titles host + repo basename inside a git repo" {
+    git -C "$TMPDIR_T" init -q -b main
+    mkdir -p "$TMPDIR_T/sub/dir"
+    run run_hook "$TMPDIR_T"
+    [ "$status" -eq 0 ]
+    title=$(echo "$output" | jq -r '.hookSpecificOutput.sessionTitle')
+    [ "$title" = "$HOST $(basename "$TMPDIR_T")" ]
+}
+
+@test "uses the repo toplevel basename from a subdirectory" {
+    git -C "$TMPDIR_T" init -q -b main
+    mkdir -p "$TMPDIR_T/sub/dir"
+    run run_hook "$TMPDIR_T/sub/dir"
+    [ "$status" -eq 0 ]
+    title=$(echo "$output" | jq -r '.hookSpecificOutput.sessionTitle')
+    [ "$title" = "$HOST $(basename "$TMPDIR_T")" ]
+}
+
+@test "falls back to cwd basename outside a git repo" {
+    mkdir -p "$TMPDIR_T/chime"
+    run run_hook "$TMPDIR_T/chime"
+    [ "$status" -eq 0 ]
+    title=$(echo "$output" | jq -r '.hookSpecificOutput.sessionTitle')
+    [ "$title" = "$HOST chime" ]
+}
+
+@test "emits valid SessionStart hookSpecificOutput" {
+    run run_hook "$TMPDIR_T"
+    [ "$status" -eq 0 ]
+    event=$(echo "$output" | jq -r '.hookSpecificOutput.hookEventName')
+    [ "$event" = "SessionStart" ]
+}
+
+@test "stays silent when a session title already exists" {
+    run run_hook "$TMPDIR_T" "my custom name"
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+}
+
+@test "emits no stderr noise" {
+    err="$(printf '{"cwd":"%s","source":"startup"}' "$TMPDIR_T" | sh "$SCRIPT" 2>&1 >/dev/null)"
+    [ -z "$err" ]
+}