oxtail 0.8.0 → 0.10.0

package/README.md

@@ -21,7 +21,7 @@ End users — paste into your MCP config and oxtail is fetched from npm on first
 **Claude Code** — add to `~/.claude.json` (global) or any project's `.mcp.json`:
 
 ```jsonc
-{ "mcpServers": { "oxtail": { "command": "npx", "args": ["-y", "oxtail@0.8.0"] } } }
+{ "mcpServers": { "oxtail": { "command": "npx", "args": ["-y", "oxtail@0.10.0"] } } }
 ```
 
 **Codex CLI** — add to `~/.codex/config.toml`:
@@ -29,14 +29,14 @@ End users — paste into your MCP config and oxtail is fetched from npm on first
 ```toml
 [mcp_servers.oxtail]
 command = "npx"
-args = ["-y", "oxtail@0.8.0"]
+args = ["-y", "oxtail@0.10.0"]
 ```
 
 **Claude slash command** (`/oxtail-join`):
 
 ```sh
 mkdir -p ~/.claude/commands
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.8.0/.claude/commands/oxtail-join.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.10.0/.claude/commands/oxtail-join.md \
   -o ~/.claude/commands/oxtail-join.md
 ```
 
@@ -44,9 +44,9 @@ curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.8.0/.claude/commands
 
 ```sh
 mkdir -p ~/.codex/skills/oxtail-join/agents
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.8.0/integrations/codex/oxtail-join/SKILL.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.10.0/integrations/codex/oxtail-join/SKILL.md \
   -o ~/.codex/skills/oxtail-join/SKILL.md
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.8.0/integrations/codex/oxtail-join/agents/openai.yaml \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.10.0/integrations/codex/oxtail-join/agents/openai.yaml \
   -o ~/.codex/skills/oxtail-join/agents/openai.yaml
 ```
 
@@ -61,17 +61,17 @@ Contributing? `git clone https://github.com/d4j3y2k/oxtail && cd oxtail && npm i
 
 ## MCP tools
 
-- `list_project_sessions` — tmux sessions in or under a given project root, enriched with `client_type`, `client_session_id`, and the peer's `state` card. Returns **one row per registered agent** — rows may share `name` when peers share a tmux session (Terminator multi-window). Disambiguate via `client_session_id`.
-- `read_session` — the recent transcript of a peer session, as clean per-turn messages when the peer is oxtail-aware (Claude Code and Codex CLI), or as raw tmux pane text otherwise. Accepts a tmux session name OR a `client_session_id` UUID; an ambiguous tmux name returns `ambiguous-target` with the candidate UUIDs.
+- `list_project_sessions` — tmux sessions in or under a given project root, enriched with `client_type`, `client_session_id`, and the peer's `state` card. Returns **one row per registered agent** — rows may share `name` when peers share a tmux session (Terminator multi-window). Disambiguate via `client_session_id`. Pass `compact: true` for a de-duplicated `tmux_sessions[]` shape that hoists the shared tmux fields and nests agents (smaller when several agents share a session); the default flat `sessions[]` shape is unchanged.
+- `read_session` — the recent transcript of a peer session, as clean per-turn messages when the peer is oxtail-aware (Claude Code and Codex CLI), or as raw tmux pane text otherwise. Accepts a tmux session name OR a `client_session_id` UUID; an ambiguous tmux name returns `ambiguous-target` with the candidate UUIDs. Transcript reads are **budgeted** so a casual read can't blow your context window: by default the last 20 messages and ~24KB of text (newest-first), per-message ISO timestamps omitted. `count_truncated` / `bytes_truncated` say which budget bit; raise `limit` + `max_bytes` to pull more, set `include_timestamps: true` to keep timestamps, and pass `tail_scan: true` to read the file tail without parsing the whole transcript (qualifies `total_messages` via `total_messages_exact`).
 - `claim_session` — single-shot session registration. The routine path: `Bash echo $CLAUDE_CODE_SESSION_ID` (or `$CODEX_THREAD_ID` for Codex) → `claim_session({ session_id })`. Returns `{ ok, session_id, transcript_path }`.
 - `set_my_state` — write a small "state card" onto this session's registry entry so peers can see what we're doing without reading our transcript. v1 surfaces a single field, `purpose` (≤200 chars).
-- `send_message` — **fire-and-forget** message to a peer. **Does NOT wake an idle peer.** Target is a tmux session name or a raw `client_session_id` UUID. Body ≤ 8KB. Delivery is async via the peer's mailbox file. (v0.5+)
-- `read_my_messages` — drain this session's mailbox and return any queued messages. Codex peers (and unhooked Claude Code) poll this; Claude Code peers with the PreToolUse hook installed see messages mid-turn instead. (v0.5+)
+- `send_message` — **fire-and-forget** message to a peer. Target is a tmux session name or a raw `client_session_id` UUID. Body ≤ 8KB. Delivery is async via the peer's mailbox file. By default does **not** wake an idle peer; pass `wake: "auto"` to nudge one (state-gated — see [Waking an idle peer](#waking-an-idle-peer)). (v0.5+)
+- `read_my_messages` — drain this session's mailbox and return any queued messages. Codex peers (and unhooked Claude Code) poll this; Claude Code peers with the hooks installed see messages mid-turn (PreToolUse) or at turn end (Stop) instead. (v0.5+)
 - `ask_peer` — **delegate-and-wait**. Enqueues a message and blocks server-side until the peer replies (or the fixed timeout elapses, default 45s, tunable via `OXTAIL_ASK_PEER_TIMEOUT_MS`). Routes the wake per `client_type`: Codex gets a paste-burst-aware `tmux send-keys` wake (500ms gap before Enter to defeat the paste-burst heuristic); Claude Code gets the same send-keys mechanism without the gap (its TUI has no paste-burst). Response includes `wake_status` so the caller can distinguish "we polled and got nothing" from "no tmux pane resolved." Use `send_message` for fire-and-forget. (v0.7+)
 - `register_my_session` — pin this MCP server's `session_id` directly. Kept for debugging; prefer `claim_session`.
 - `get_my_session` — return this MCP server's own registry entry plus a per-strategy detection diagnosis. Useful for debugging.
 
-See [design principles](https://github.com/d4j3y2k/oxtail/blob/v0.5.0/AGENTS.md) for scope and architecture.
+See [design principles](https://github.com/d4j3y2k/oxtail/blob/v0.10.0/AGENTS.md) for scope and architecture.
 
 ## Usage from an agent
 
@@ -79,9 +79,11 @@ See [design principles](https://github.com/d4j3y2k/oxtail/blob/v0.5.0/AGENTS.md)
 claim_session({ session_id: "<uuid from $CLAUDE_CODE_SESSION_ID or $CODEX_THREAD_ID>" })
 set_my_state({ purpose: "wiring up state cards" })
 list_project_sessions({ project_root: "/path/to/project" })
-read_session({ name: "primary" })                    // auto: transcript if peer registered, else pane
-read_session({ name: "claude", mode: "transcript", limit: 50 })
-read_session({ name: "primary", mode: "pane", pane_lines: 500 })
+read_session({ name: "primary" })                    // auto: transcript if peer registered, else pane (budgeted: last 20 msgs, ~24KB)
+read_session({ name: "claude", mode: "transcript", limit: 50, max_bytes: 60000 })  // pull more
+read_session({ name: "claude", mode: "transcript", include_timestamps: true })      // keep ISO timestamps
+read_session({ name: "claude", mode: "transcript", tail_scan: true })               // fast tail read on huge transcripts
+read_session({ name: "primary", mode: "pane", pane_lines: 500, pane_max_chars: 40000 })
 read_session({ name: "<peer-uuid>", mode: "transcript" })   // UUID form: needed when peers share a tmux session
 send_message({ target: "primary", body: "<system-reminder>checking in</system-reminder>" })
 send_message({ target: "<peer-uuid>", body: "..." })        // UUID form: same disambiguation
@@ -94,7 +96,7 @@ Omitting `project_root` triggers a best-effort `.git`-ancestor walk from the ser
 
 ## Peer awareness without raw transcripts
 
-The cheapest way to learn what peers are doing is `list_project_sessions`. Each row carries an optional `state` card written by the peer via `set_my_state` — currently `{ purpose, updated_at }`. Reading the card costs almost nothing compared to `read_session`, which spends tokens on the full transcript. Use `read_session` when the card isn't enough.
+The cheapest way to learn what peers are doing is `list_project_sessions`. Each row carries an optional `state` card written by the peer via `set_my_state` — currently `{ purpose, updated_at }`. Reading the card costs almost nothing compared to `read_session`, which — even budgeted (last 20 messages / ~24KB by default) — spends real tokens on transcript content. Use `read_session` when the card isn't enough.
 
 ## Peer messaging (v0.5)
 
@@ -114,23 +116,42 @@ Cross-project sends are rejected, never silently dropped. Sending to a peer with
 
 ### Mid-turn vs next-turn delivery (the asymmetry)
 
-Claude Code peers can receive messages **mid-turn** via an opt-in PreToolUse hook:
+Claude Code peers can receive messages **autonomously** via three opt-in hooks:
 
 ```sh
 npx oxtail install-hook
 ```
 
-This drops a small bash script at `~/.oxtail/hooks/pretooluse.sh` and adds a `hooks.PreToolUse` entry in `~/.claude/settings.json`. The hook reads each `PreToolUse` event's `session_id` from stdin, locates the matching mailbox, and emits `additionalContext` into the next tool-call boundary. Reverse with `npx oxtail uninstall-hook`.
+This installs three small bash scripts under `~/.oxtail/hooks/` and adds matching entries to `~/.claude/settings.json` (tracked by a `_oxtailHook` marker). Reverse with `npx oxtail uninstall-hook`:
 
-Codex CLI peers and any Claude Code session without the hook installed receive messages **next-turn** by calling `read_my_messages` explicitly. Both clients send messages identically. The asymmetry exists because Claude Code exposes a PreToolUse hook surface that injects `additionalContext`; Codex CLI does not currently expose an equivalent.
+- **`hooks.PreToolUse`** → `pretooluse.sh` — delivers **mid-turn**. It reads each `PreToolUse` event's `session_id` from stdin, locates the matching mailbox, and emits the queued messages as `additionalContext` on the next tool-call boundary.
+- **`hooks.Stop`** → `stop.sh` — delivers **at turn end** (deliver-on-complete). When the agent finishes a turn with messages still waiting, it emits a `decision: "block"` envelope so the agent continues and reads + responds before going idle, instead of leaving the messages until the next turn.
+- **`hooks.UserPromptSubmit`** → `userpromptsubmit.sh` — no delivery; it maintains a **busy/idle activity flag** in `~/.oxtail/activity/<session_id>` (busy on a turn start, idle on a real Stop). A sender consults this so `send_message({ wake: "auto" })` only fires a send-keys wake when the peer is actually idle (see [Waking an idle peer](#waking-an-idle-peer)).
 
-**Caveat for Claude Code receivers:** PreToolUse fires only before a tool call. A turn that produces only text — no tool calls — never triggers the hook; messages enqueued during that turn surface on the next tool call (or via an explicit `read_my_messages`). For pair-debugging UX, senders should not assume mid-turn delivery is universal.
+The PreToolUse and Stop hooks include the message body plus `message_id` and `from_session_id` metadata when the sender is registered, so a receiver can reply with `send_message({ target: "<from_session_id>", body: "..." })` even when the sender is not visible in `list_project_sessions`.
+
+Codex CLI peers and any Claude Code session without the hooks installed receive messages **next-turn** by calling `read_my_messages` explicitly. Both clients send messages identically. The asymmetry exists because Claude Code exposes PreToolUse/Stop/UserPromptSubmit hook surfaces that inject context or fire on lifecycle events; Codex CLI does not currently expose an equivalent.
+
+**Coverage and its edges.** PreToolUse fires only before a tool call, so a turn that produces only text — no tool calls — never triggers it; the Stop hook closes that gap by delivering at turn end. One deliberate edge remains: the Stop hook honors the `stop_hook_active` flag and exits without blocking on a re-entry, so `decision: "block"` can never loop — which means a message that arrives *during* a Stop-blocked continuation waits for the next turn rather than extending the current one. A truly idle peer (no turn in flight) is reached by `send_message({ wake: "auto" })` or `ask_peer` (both fire an external wake), or by an explicit `read_my_messages`.
+
+### Waking an idle peer
+
+`send_message` is fire-and-forget by default. Pass `wake: "auto"` to also nudge an **idle** peer into a turn so it drains its mailbox promptly:
+
+```js
+send_message({ target: "<peer>", body: "...", wake: "auto" })
+// → { ok: true, message_id, ..., wake_status: "fired" | "skipped_busy" | "skipped_no_target" | "disabled" }
+```
+
+It is **state-gated** off the activity flag above: if the peer is mid-turn (`busy`), the wake is skipped (`skipped_busy`) because its PreToolUse/Stop hooks will deliver during the turn — no point typing into a busy composer. Idle, unknown (hooks not installed), or stale-busy peers get a per-client `tmux send-keys` wake (Codex gets the paste-burst-aware gap; Claude Code does not). `wake: "off"` (the default) preserves the pure fire-and-forget contract.
+
+**Codex and the wake matrix.** The send-keys wake needs a tmux pane. A Codex peer running **outside tmux** has none, so it returns `wake_status: "skipped_no_target"` — its idle delivery stays poll-based (`read_my_messages`). Run Codex **inside a tmux pane** to get symmetric idle-wake; the routing already handles the Codex paste-burst case.
 
 ### Hook coexistence
 
-The oxtail hook coexists with other `hooks.PreToolUse` entries. **Verified against Terminator's `_terminatorHook` v1 in Claude Code 2.1.139:** both hooks' `additionalContext` envelopes reached the model. Install order: Terminator first, oxtail second — `install-hook.mjs` appends to a non-empty array, which matches the verified configuration. If you reinstall hooks in a different order, you may need to re-test.
+`install-hook` manages three events (`PreToolUse`, `Stop`, `UserPromptSubmit`); on each it replaces any prior oxtail entry in place and otherwise appends, so existing third-party entries are preserved. **The PreToolUse path is verified against Terminator's `_terminatorHook` v1 in Claude Code 2.1.139:** both hooks' `additionalContext` envelopes reached the model (install order: Terminator first, oxtail second — which is what `install-hook.mjs` produces by appending). Coexistence of the Stop and UserPromptSubmit hooks with third-party entries on those events uses the same append logic but is not separately verified.
 
-If you have a PreToolUse hook installed that isn't from Terminator and isn't oxtail, `install-hook` prints a one-line note and proceeds — coexistence behavior with arbitrary third-party hooks is not pre-verified.
+If you have a hook installed on a managed event that isn't from Terminator and isn't oxtail, `install-hook` prints a one-line note and proceeds — coexistence behavior with arbitrary third-party hooks is not pre-verified.
 
 ### Trust model
 
@@ -177,7 +198,7 @@ ask_peer({ target, body })
 
 1. Enqueue `body` into the target's mailbox (same as `send_message`).
 2. Wait ~500ms for a hook-delivered reply (rare path — handles the case where the peer was already mid-tool-call and replied immediately).
-3. Route the wake via `wake_status` resolution (see above). For Claude Code, return immediately. Otherwise fire the wake.
+3. Route and fire the wake via `wake_status` resolution (see above).
 4. Poll the caller's mailbox at 200ms for a reply with `from_session_id == target.session_id`. Other peers' messages stay in the mailbox untouched.
 5. Return the reply on match, or `{ reply: null, timed_out: true, wake_status }` after the fixed timeout. Late replies fall back to the normal v0.5 hook / `read_my_messages` path — never lost, just delivered out of band.
 
@@ -195,7 +216,7 @@ Pane targeting can go stale: `tmux_pane` is cached at server startup, but tmux c
 If `ask_peer` returns an abort error before its built-in 45s timeout fires, your MCP client's tool-call ceiling is lower than 45s. Override the bound at server startup:
 
 ```sh
-OXTAIL_ASK_PEER_TIMEOUT_MS=30000 npx -y oxtail@0.8.0
+OXTAIL_ASK_PEER_TIMEOUT_MS=30000 npx -y oxtail@0.10.0
 ```
 
 The server reads the env var once at boot and uses it as the fixed timeout for all `ask_peer` calls in that session. Values must be positive numbers; anything else falls back to the 45000ms default.
@@ -242,4 +263,11 @@ If `MCP_TRACE_FILE` is set in the environment, every detection run appends an ND
 
 ## Status
 
-v0.8.0. Builds on v0.7's per-client wake routing — Codex peers wake via a 500ms-gap send-keys sequence that defeats their TUI's paste-burst heuristic (verified live 2026-05-13). Claude Code peers, originally fail-fasted under a misread of the Claude Code hook catalog, now wake via the same send-keys mechanism without the gap (no paste-burst in Claude Code's TUI). An end-to-end falsifying experiment 2026-05-13 against the live `oxtail-claudejr` peer in this repo confirmed the full round-trip works: ask_peer enqueue → send-keys → peer entered a turn → PreToolUse hook drained mailbox → peer replied via send_message. The symmetric-matrix vision (Claude↔Claude, Claude↔Codex, both directions, no human relay) is intact. ask_peer's response gains a `wake_status` field for caller diagnostics; `skipped_unsupported` is now reserved for forward compat with hypothetical future unwakeable client_types rather than firing on any current client. Wake strategy is overridable via `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` as a rollback. See [issue #3](https://github.com/d4j3y2k/oxtail/issues/3) for the v0.7 spike findings.
+v0.9.0. Completes the autonomous peer-messaging matrix: a message reaches a Claude Code peer whether it's mid-turn, finishing, or fully idle — in both directions, with no human relay.
+
+- **Deliver-on-complete (Stop hook).** PreToolUse only fires before a tool call, so a text-only turn never triggered it. The new `Stop` hook closes that gap: a message that lands as the agent finishes a turn blocks the stop and is read + answered before it goes idle. Loop-safe via `stop_hook_active`.
+- **State-gated idle wake.** `send_message({ wake: "auto" })` nudges an idle peer via per-client `tmux send-keys`, gated off a busy/idle activity flag maintained by the `UserPromptSubmit`/`Stop` hooks — so it never types into a peer that's mid-turn. Returns `wake_status: fired | skipped_busy | skipped_no_target | disabled`. A Codex peer must be inside a tmux pane to be idle-woken (otherwise `skipped_no_target`, and delivery stays poll-based).
+- **Sticky Codex claim.** A restarted Codex MCP child — whose `CODEX_THREAD_ID` is stripped from its subprocess env — recovers its `session_id` from a persisted claim keyed by client type + cwd + a bounded process-ancestor chain, so identity survives an MCP restart without a manual re-claim.
+- **Identity hardening.** Hooks and activity key on `client.session_id` (never `server_pid`), so a dual-scope agent's sibling MCP children act as one identity; delivery hooks drain all sibling mailboxes; nested git repos are treated as separate projects for scope matching.
+
+Builds on v0.7's per-client wake routing (verified live 2026-05-13): Codex peers wake via a 500ms-gap send-keys sequence that defeats their TUI's paste-burst heuristic; Claude Code peers wake via the same mechanism without the gap (no paste-burst in its TUI). `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` remains as a rollback. See [issue #3](https://github.com/d4j3y2k/oxtail/issues/3) for the v0.7 spike findings.

package/assets/pretooluse.sh

@@ -1,19 +1,21 @@
 #!/usr/bin/env bash
 # oxtail PreToolUse hook — delivers peer messages mid-turn to Claude Code.
 #
-# Reads ~/.oxtail/mailboxes/<my-server-pid>.jsonl, emits a hookSpecificOutput
-# envelope, and truncates the mailbox under lock. Pure bash + awk; no jq,
-# python, or node. Exits 0 on every error path so it never blocks a tool call.
+# Reads this session's mailbox(es), emits a hookSpecificOutput envelope, and
+# truncates under lock. Pure bash + awk (bash 3.2-compatible — no mapfile); no
+# jq, python, or node. Exits 0 on every error path so it never blocks a tool call.
+#
+# Identity is keyed by session_id, never server_pid (see AGENTS.md). A dual-scope
+# agent runs several MCP children sharing one session_id; the session's inbox is
+# the UNION of those children's mailboxes, so this drains ALL of them rather than
+# guessing one (the send side enqueues to readAll()'s freshest sibling).
 #
 # Step 0a verified that Claude Code strips CLAUDE_CODE_SESSION_ID from hook
-# subprocesses but delivers it via stdin JSON. Stdin is the only path; env
-# is dead code and not consulted here.
+# subprocesses but delivers it via stdin JSON. Stdin is the only path.
 
 set -u
 
-# 1. Read session_id from stdin JSON. Claude Code's PreToolUse contract
-#    delivers a single JSON line on stdin: {"session_id":"...", ...}. If
-#    stdin is a tty (interactive run), exit silently.
+# 1. Read session_id from stdin JSON. If stdin is a tty (interactive run), exit.
 sid=""
 if [ ! -t 0 ]; then
   payload=$(cat 2>/dev/null || true)
@@ -45,46 +47,45 @@ mailboxes_dir="$HOME/.oxtail/mailboxes"
 [ -d "$sessions_dir" ] || exit 0
 [ -d "$mailboxes_dir" ] || exit 0
 
-# 2. Find this session's MCP-server pid. Registry files are pretty-printed
-#    JSON (key/value separated by ": " with a space), so use grep -E with
-#    [[:space:]]* to tolerate either form. -F (fixed-string) is unsafe.
-entry_file=$(grep -lE "\"session_id\"[[:space:]]*:[[:space:]]*\"$sid\"" "$sessions_dir"/*.json 2>/dev/null | head -n 1) || true
-[ -z "$entry_file" ] && exit 0
-
-pid=$(basename "$entry_file" .json)
-case "$pid" in *[!0-9]*) exit 0 ;; esac
+# 2. Collect every non-empty sibling mailbox for this session_id. Registry files
+#    are pretty-printed JSON, so grep -E with [[:space:]]* tolerates the form.
+mboxes=()
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  pid=$(basename "$f" .json)
+  case "$pid" in *[!0-9]*) continue ;; esac
+  m="$mailboxes_dir/$pid.jsonl"
+  if [ -f "$m" ] && [ -s "$m" ]; then mboxes+=("$m"); fi
+done < <(grep -lE "\"session_id\"[[:space:]]*:[[:space:]]*\"$sid\"" "$sessions_dir"/*.json 2>/dev/null)
 
-mbox="$mailboxes_dir/$pid.jsonl"
-[ -f "$mbox" ] || exit 0
-[ -s "$mbox" ] || exit 0
+[ "${#mboxes[@]}" -eq 0 ] && exit 0
 
-# 3. Acquire mkdir-based lock. Staleness window is 30s; matches
-#    src/mailbox.ts:LOCK_STALE_MS. We can't use `find -mmin +0.5` portably —
-#    BSD find and `bfs` reject fractional -mmin — so we read mtime via stat.
-#    GNU and BSD stat formats differ, so try both.
-LOCK_STALE_SECS=30
-acquired=0
-for i in $(seq 1 50); do
-  if mkdir "$mbox.lock" 2>/dev/null; then acquired=1; break; fi
-  now=$(date +%s 2>/dev/null || echo 0)
-  mtime=$(stat -c %Y "$mbox.lock" 2>/dev/null || stat -f %m "$mbox.lock" 2>/dev/null || echo 0)
-  if [ "$mtime" -gt 0 ] && [ $((now - mtime)) -gt "$LOCK_STALE_SECS" ]; then
-    rmdir "$mbox.lock" 2>/dev/null
-  fi
-  sleep 0.01
+# 3. Acquire each mailbox's mkdir-based lock (best-effort; 30s staleness window,
+#    matching src/mailbox.ts:LOCK_STALE_MS). GNU and BSD stat formats differ.
+locked=()
+for m in "${mboxes[@]}"; do
+  for i in $(seq 1 50); do
+    if mkdir "$m.lock" 2>/dev/null; then locked+=("$m"); break; fi
+    now=$(date +%s 2>/dev/null || echo 0)
+    mtime=$(stat -c %Y "$m.lock" 2>/dev/null || stat -f %m "$m.lock" 2>/dev/null || echo 0)
+    if [ "$mtime" -gt 0 ] && [ $((now - mtime)) -gt 30 ]; then
+      rmdir "$m.lock" 2>/dev/null
+    fi
+    sleep 0.01
+  done
 done
-[ "$acquired" -eq 1 ] || exit 0
+[ "${#locked[@]}" -eq 0 ] && exit 0
 
-# 4. Extract every line's body field (still JSON-encoded), join with literal
-#    \n\n separators, emit hookSpecificOutput envelope. Truncating happens
-#    after the awk completes; if awk's output never reaches Claude Code we'd
-#    rather have the messages still in the box than lost.
+# 4. Extract every line's body + reply metadata across all locked mailboxes,
+#    join into one system-reminder envelope. Truncation happens only after awk
+#    produces a valid payload — if the output never reaches Claude Code we'd
+#    rather leave the messages in the box than lose them.
 output=$(awk '
-  BEGIN { count = 0 }
-  {
-    p = index($0, "\"body\":\"")
-    if (p == 0) next
-    rest = substr($0, p + 8)
+  function json_string_field(line, key,   needle, p, rest, out, i, n, c) {
+    needle = "\"" key "\":\""
+    p = index(line, needle)
+    if (p == 0) return ""
+    rest = substr(line, p + length(needle))
     out = ""
     i = 1; n = length(rest)
     while (i <= n) {
@@ -98,23 +99,40 @@ output=$(awk '
         i += 1
       }
     }
-    bodies[count++] = out
+    return out
+  }
+  BEGIN { count = 0 }
+  {
+    body = json_string_field($0, "body")
+    if (body == "") next
+    bodies[count] = body
+    ids[count] = json_string_field($0, "id")
+    froms[count] = json_string_field($0, "from_session_id")
+    count++
   }
   END {
     if (count == 0) exit 0
-    ctx = ""
+    ctx = "<system-reminder>\\n[oxtail] You have " count " new peer message(s)."
+    ctx = ctx "\\nReply to any that need it via mcp__oxtail__send_message (target = the from_session_id below)."
     for (j = 0; j < count; j++) {
-      if (j > 0) ctx = ctx "\\n\\n"
-      ctx = ctx bodies[j]
+      ctx = ctx "\\n\\n--- message " (j + 1) " ---"
+      if (ids[j] != "") ctx = ctx "\\nmessage_id: " ids[j]
+      if (froms[j] != "") {
+        ctx = ctx "\\nfrom_session_id: " froms[j]
+      } else {
+        ctx = ctx "\\nfrom_session_id: unknown"
+      }
+      ctx = ctx "\\nbody:\\n" bodies[j]
     }
+    ctx = ctx "\\n</system-reminder>"
     printf("{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"%s\"}}\n", ctx)
   }
-' < "$mbox")
+' "${locked[@]}")
 
 if [ -n "$output" ]; then
   printf '%s' "$output"
-  : > "$mbox"
+  for m in "${locked[@]}"; do : > "$m"; done
 fi
 
-rmdir "$mbox.lock" 2>/dev/null || true
+for m in "${locked[@]}"; do rmdir "$m.lock" 2>/dev/null || true; done
 exit 0

package/assets/stop.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# oxtail Stop hook — two jobs at turn end:
+#   1. Wake-routing: mark this session "idle" in ~/.oxtail/activity/<session_id>
+#      on a real stop (no pending messages). When it instead BLOCKS to deliver
+#      messages the turn continues, so it leaves the "busy" mark (set by the
+#      UserPromptSubmit hook) in place.
+#   2. Delivery: if peer messages landed as the turn finished, emit a
+#      {"decision":"block","reason":...} envelope so Claude reads + responds
+#      before going idle, and truncate the mailbox(es) under lock.
+#
+# Identity is keyed by session_id, never server_pid (see AGENTS.md). A dual-scope
+# agent runs several MCP children sharing one session_id; the session's inbox is
+# the UNION of those children's mailboxes, so delivery drains ALL of them rather
+# than guessing one. Activity is written under the session_id directly.
+#
+# Pure bash + awk (bash 3.2-compatible — no mapfile); no jq/python/node. Exits 0
+# on every error path so it never wedges the agent. stop_hook_active: on a
+# re-entry (already continuing from a prior block) this is a real stop — mark
+# idle and exit so decision:block can never loop.
+
+set -u
+
+# 1. Read the full stdin payload once. tty / empty → nothing to do.
+payload=""
+if [ ! -t 0 ]; then
+  payload=$(cat 2>/dev/null || true)
+fi
+[ -z "$payload" ] && exit 0
+
+# 2. Extract session_id (same scanner as pretooluse.sh).
+sid=$(printf '%s' "$payload" | awk '
+  {
+    p = index($0, "\"session_id\":\"")
+    if (p == 0) next
+    rest = substr($0, p + 14)
+    out = ""
+    i = 1; n = length(rest)
+    while (i <= n) {
+      c = substr(rest, i, 1)
+      if (c == "\\") {
+        if (i+1 <= n) { out = out substr(rest, i, 2); i += 2 } else { i += 1 }
+      } else if (c == "\"") {
+        break
+      } else {
+        out = out c; i += 1
+      }
+    }
+    print out; exit
+  }
+')
+[ -z "$sid" ] && exit 0
+
+activity_dir="$HOME/.oxtail/activity"
+# Sanitize to a safe filename (UUIDs pass through). Must match the server's
+# activitySessionKey() so reads and writes agree on the path.
+safe_sid=$(printf '%s' "$sid" | tr -c 'A-Za-z0-9_-' '_')
+mark_idle() {
+  [ -z "$safe_sid" ] && return 0
+  mkdir -p "$activity_dir" 2>/dev/null || true
+  printf 'idle' > "$activity_dir/$safe_sid" 2>/dev/null || true
+}
+
+# 3. Loop guard: a re-entry is a real stop → mark idle, allow the stop.
+if printf '%s' "$payload" | grep -Eq '"stop_hook_active"[[:space:]]*:[[:space:]]*true'; then
+  mark_idle
+  exit 0
+fi
+
+sessions_dir="$HOME/.oxtail/sessions"
+mailboxes_dir="$HOME/.oxtail/mailboxes"
+# Can't locate siblings → it's still a real stop; mark idle and allow it.
+if [ ! -d "$sessions_dir" ] || [ ! -d "$mailboxes_dir" ]; then
+  mark_idle
+  exit 0
+fi
+
+# 4. Collect every non-empty sibling mailbox for this session_id.
+mboxes=()
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  pid=$(basename "$f" .json)
+  case "$pid" in *[!0-9]*) continue ;; esac
+  m="$mailboxes_dir/$pid.jsonl"
+  if [ -f "$m" ] && [ -s "$m" ]; then mboxes+=("$m"); fi
+done < <(grep -lE "\"session_id\"[[:space:]]*:[[:space:]]*\"$sid\"" "$sessions_dir"/*.json 2>/dev/null)
+
+# Nothing to deliver → real stop.
+if [ "${#mboxes[@]}" -eq 0 ]; then
+  mark_idle
+  exit 0
+fi
+
+# 5. Lock each non-empty mailbox (best-effort; 30s staleness window).
+locked=()
+for m in "${mboxes[@]}"; do
+  for i in $(seq 1 50); do
+    if mkdir "$m.lock" 2>/dev/null; then locked+=("$m"); break; fi
+    now=$(date +%s 2>/dev/null || echo 0)
+    mt=$(stat -c %Y "$m.lock" 2>/dev/null || stat -f %m "$m.lock" 2>/dev/null || echo 0)
+    if [ "$mt" -gt 0 ] && [ $((now - mt)) -gt 30 ]; then rmdir "$m.lock" 2>/dev/null; fi
+    sleep 0.01
+  done
+done
+# Couldn't lock anything → leave messages for next time. This still allows the
+# turn to stop, so mark idle; otherwise wake:auto will suppress a wake for a
+# peer that is no longer actually busy.
+if [ "${#locked[@]}" -eq 0 ]; then
+  mark_idle
+  exit 0
+fi
+
+# 6. Build the decision:block reason from every locked mailbox's lines.
+output=$(awk '
+  function json_string_field(line, key,   needle, p, rest, out, i, n, c) {
+    needle = "\"" key "\":\""
+    p = index(line, needle)
+    if (p == 0) return ""
+    rest = substr(line, p + length(needle))
+    out = ""
+    i = 1; n = length(rest)
+    while (i <= n) {
+      c = substr(rest, i, 1)
+      if (c == "\\") {
+        if (i + 1 <= n) { out = out substr(rest, i, 2); i += 2 } else { i += 1 }
+      } else if (c == "\"") {
+        break
+      } else {
+        out = out c
+        i += 1
+      }
+    }
+    return out
+  }
+  BEGIN { count = 0 }
+  {
+    body = json_string_field($0, "body")
+    if (body == "") next
+    bodies[count] = body
+    ids[count] = json_string_field($0, "id")
+    froms[count] = json_string_field($0, "from_session_id")
+    count++
+  }
+  END {
+    if (count == 0) exit 0
+    r = "[oxtail] " count " new peer message(s) arrived as you finished your turn. Read them and respond before stopping."
+    r = r "\\nReply to any that need it via mcp__oxtail__send_message (target = the from_session_id below)."
+    for (j = 0; j < count; j++) {
+      r = r "\\n\\n--- message " (j + 1) " ---"
+      if (ids[j] != "") r = r "\\nmessage_id: " ids[j]
+      if (froms[j] != "") {
+        r = r "\\nfrom_session_id: " froms[j]
+      } else {
+        r = r "\\nfrom_session_id: unknown"
+      }
+      r = r "\\nbody:\\n" bodies[j]
+    }
+    printf("{\"decision\":\"block\",\"reason\":\"%s\"}\n", r)
+  }
+' "${locked[@]}")
+
+if [ -n "$output" ]; then
+  # Blocking: the turn continues, so leave the "busy" mark in place.
+  printf '%s' "$output"
+  for m in "${locked[@]}"; do : > "$m"; done
+else
+  # Nothing deliverable → real stop.
+  mark_idle
+fi
+
+for m in "${locked[@]}"; do rmdir "$m.lock" 2>/dev/null || true; done
+exit 0

package/assets/userpromptsubmit.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# oxtail UserPromptSubmit hook — marks this session "busy" for wake-routing.
+#
+# Writes "busy" to ~/.oxtail/activity/<session_id> whenever a turn starts (the
+# user — or a peer's send-keys wake — submits a prompt). The Stop hook writes
+# "idle" when a turn ends. A sender consults this file so send_message with
+# wake:"auto" only fires a send-keys wake when the peer is NOT mid-turn — the
+# PreToolUse/Stop hooks deliver during a turn, so waking then would type into a
+# busy composer.
+#
+# Keyed by session_id (the agent identity), NOT server_pid: a dual-scope agent
+# runs several MCP children that share one session_id, and the sender reads this
+# by the peer's session_id (see AGENTS.md — never key peer identity on
+# server_pid). No registry/pid lookup needed; the session_id comes straight from
+# the hook payload. Pure bash; no jq/python/node. Exits 0 on every path.
+
+set -u
+
+# Read session_id from stdin JSON (Claude Code delivers it the same way it does
+# for PreToolUse). tty / no payload → nothing to do.
+sid=""
+if [ ! -t 0 ]; then
+  payload=$(cat 2>/dev/null || true)
+  sid=$(printf '%s' "$payload" | awk '
+    {
+      p = index($0, "\"session_id\":\"")
+      if (p == 0) next
+      rest = substr($0, p + 14)
+      out = ""
+      i = 1; n = length(rest)
+      while (i <= n) {
+        c = substr(rest, i, 1)
+        if (c == "\\") {
+          if (i+1 <= n) { out = out substr(rest, i, 2); i += 2 } else { i += 1 }
+        } else if (c == "\"") {
+          break
+        } else {
+          out = out c; i += 1
+        }
+      }
+      print out; exit
+    }
+  ')
+fi
+[ -z "$sid" ] && exit 0
+
+# Sanitize to a safe filename (UUIDs pass through unchanged). Must match the
+# server's activitySessionKey() so reads and writes agree on the path.
+safe_sid=$(printf '%s' "$sid" | tr -c 'A-Za-z0-9_-' '_')
+[ -z "$safe_sid" ] && exit 0
+
+activity_dir="$HOME/.oxtail/activity"
+mkdir -p "$activity_dir" 2>/dev/null || true
+printf 'busy' > "$activity_dir/$safe_sid" 2>/dev/null || true
+exit 0