From 94e54f69453dea0feda4722347ba3c60c9822c2b Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 19 Jul 2026 21:04:43 -0500
Subject: feat(hooks): soft-nudge pending inbox handoffs at task boundaries

The "check inbox/ at every task boundary" rule was prose-only in protocols.org, so it held only as well as the agent remembered it and a handoff could pass a turn unseen. inbox-boundary-check.sh is a Stop hook that backs the rule: when inbox-status -q reports pending items it blocks the yield once and injects the count, so the agent processes them before returning.

It soft-nudges rather than hard-blocks. On the harness re-entry (stop_hook_active: true) the hook steps aside and lets the turn end, so a mid-task pause to ask a question, or an item the agent genuinely can't process, never wedges the session. A hard block would instead push inbox processing ahead of that clarifying question.

The hook self-skips where it doesn't apply: no inbox/ dir, no inbox-status, or a clean inbox each exit 0 silently, so one global hook covers every project with no config. It prefers the project-local .ai/scripts/inbox-status and falls back to one on PATH. It's wired into the Stop array ahead of ai-wrap-teardown in both the tracked settings.json (which the live ~/.claude/settings.json symlinks to) and the documented snippet. bats covers pending, clean, the re-entry step-aside, no-inbox, and the absent-status degrade.
---
 scripts/tests/inbox-boundary-check-hook.bats | 83 ++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 scripts/tests/inbox-boundary-check-hook.bats

(limited to 'scripts')

diff --git a/scripts/tests/inbox-boundary-check-hook.bats b/scripts/tests/inbox-boundary-check-hook.bats
new file mode 100644
index 0000000..58668a5
--- /dev/null
+++ b/scripts/tests/inbox-boundary-check-hook.bats
@@ -0,0 +1,83 @@
+#!/usr/bin/env bats
+# hooks/inbox-boundary-check.sh — Stop hook that soft-nudges the agent to
+# process pending inbox/ handoffs before yielding. Blocks the stop ONCE (emits
+# a block decision + reason) when inbox-status reports pending items; on the
+# harness re-entry (stop_hook_active: true) it steps aside so an unprocessable
+# item or a mid-task pause never wedges. Self-skips where there's no inbox/ or
+# no inbox-status. The real inbox-status is copied into the test project so the
+# hook runs against real code, not a stub.
+
+setup() {
+    REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)"
+    SCRIPT="$REPO_ROOT/hooks/inbox-boundary-check.sh"
+    INBOX_STATUS="$REPO_ROOT/claude-templates/.ai/scripts/inbox-status"
+    TMPDIR_T="$(mktemp -d)"
+    CWD="$TMPDIR_T/proj"
+    mkdir -p "$CWD/.ai/scripts"
+    cp "$INBOX_STATUS" "$CWD/.ai/scripts/inbox-status"
+    chmod +x "$CWD/.ai/scripts/inbox-status"
+}
+
+teardown() {
+    rm -rf "$TMPDIR_T"
+}
+
+# Feed Stop-hook JSON on stdin. $1 = stop_hook_active (default false).
+run_hook() {
+    local active="${1:-false}"
+    printf '{"cwd":"%s","hook_event_name":"Stop","stop_hook_active":%s}' \
+        "$CWD" "$active" | bash "$SCRIPT"
+}
+
+@test "pending handoffs block the stop with a count in the reason" {
+    mkdir -p "$CWD/inbox"
+    printf 'x\n' >"$CWD/inbox/2026-07-19-from-home-thing.org"
+    printf 'y\n' >"$CWD/inbox/2026-07-19-from-work-other.org"
+    run run_hook
+    [ "$status" -eq 0 ]
+    # Valid JSON with a block decision.
+    echo "$output" | jq -e '.decision == "block"'
+    echo "$output" | jq -e '.reason | test("2 pending")'
+    echo "$output" | jq -e '.reason | test("inbox.org")'
+}
+
+@test "a clean inbox (only artifacts) emits nothing" {
+    mkdir -p "$CWD/inbox"
+    touch "$CWD/inbox/.gitkeep"
+    printf 'done\n' >"$CWD/inbox/PROCESSED-2026-07-19-old.org"
+    run run_hook
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+}
+
+@test "soft-nudge: stop_hook_active=true steps aside even with pending items" {
+    mkdir -p "$CWD/inbox"
+    printf 'x\n' >"$CWD/inbox/2026-07-19-from-home-thing.org"
+    run run_hook true
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+}
+
+@test "no inbox/ directory is a silent no-op" {
+    run run_hook
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+}
+
+@test "inbox-status absent degrades to a silent no-op" {
+    mkdir -p "$CWD/inbox"
+    printf 'x\n' >"$CWD/inbox/2026-07-19-from-home-thing.org"
+    rm -f "$CWD/.ai/scripts/inbox-status"
+    # Also ensure nothing named inbox-status is on PATH for this run.
+    run env PATH="/usr/bin:/bin" bash -c '
+        printf "{\"cwd\":\"'"$CWD"'\",\"hook_event_name\":\"Stop\"}" | bash "'"$SCRIPT"'"'
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+}
+
+@test "the emitted reason names the project for context" {
+    mkdir -p "$CWD/inbox"
+    printf 'x\n' >"$CWD/inbox/2026-07-19-from-home-thing.org"
+    run run_hook
+    echo "$output" | jq -e '.reason | test("proj")'
+}
-- 
cgit v1.2.3