oxtail 0.7.1 → 0.9.1

package/AGENTS.md

@@ -17,7 +17,7 @@ Scope is **project-root as the unit**. Sessions in one project root see each oth
 - **Registry (leaning):** `tmux list-sessions` filtered by project-derived names, rather than a custom JSON registry. Free dead-session detection, free naming, no daemon to maintain. Decision pending real-use signals.
 - **Project scoping:** project root inferred from session CWD at agent startup.
 
-## Status: v0.7.0 shipped, dogfooding
+## Status: v0.8.0 shipped, dogfooding
 
 Nine MCP tools live: `list_project_sessions`, `read_session`, `claim_session`, `set_my_state`, `register_my_session`, `get_my_session`, the v0.5 messaging pair `send_message` and `read_my_messages`, and `ask_peer` (delegate-and-wait, introduced v0.6, per-client wake routing in v0.7). Registered both project-locally (via `.mcp.json` using `tsx ./src/server.ts` for the dev loop) and globally (in `~/.claude.json` and `~/.codex/config.toml`, pointing at `dist/server.js`).
 
@@ -25,13 +25,13 @@ The v0.4.0 change: peer `client_session_id` and `transcript_path` now resolve re
 
 The follow-on additions (`claim_session`, `set_my_state`) introduce a peer-awareness layer: `list_project_sessions` now surfaces each peer's `state` card so an agent can learn what its peers are doing without paying for `read_session`. Raw transcripts become the deep-dive fallback, not the default mode of peer awareness.
 
-Current phase remains **dogfooding**: use the tools in real parallel-agent work, log friction in `NOTES.md`. Each version (v0.1 list_project_sessions → v0.2 read_session → v0.3 reliable peer identity → v0.4 peer-awareness state cards → v0.5 peer-to-peer messaging → v0.6 delegate-and-wait → v0.7 per-client wake routing) shipped only after observed friction named the next addition; the same gating applies to whatever comes next.
+Current phase remains **dogfooding**: use the tools in real parallel-agent work, log friction in `NOTES.md`. Each version (v0.1 list_project_sessions → v0.2 read_session → v0.3 reliable peer identity → v0.4 peer-awareness state cards → v0.5 peer-to-peer messaging → v0.6 delegate-and-wait → v0.7 per-client wake routing → v0.8 symmetric Claude Code wake) shipped only after observed friction named the next addition; the same gating applies to whatever comes next.
 
 The v0.5 change: two new MCP tools (`send_message`, `read_my_messages`) plus an opt-in `PreToolUse` hook installable via `npx oxtail install-hook`. Friction observed while pairing on Terminator — two agents in the same project root can see each other's state cards and transcripts but couldn't say anything to each other. Now they can. Claude Code peers see messages mid-turn (via the hook); Codex peers (or unhooked Claude Code) see them next-turn (via polling `read_my_messages`).
 
 The v0.6 change: one new MCP tool (`ask_peer`) that turns v0.5's async pings into a blocking delegate-and-wait. Friction observed while dogfooding v0.5 — `send_message` lets agents say things to each other, but the sender doesn't stay in-turn waiting for a reply. `ask_peer` blocks server-side until a reply with a matching `from_session_id` lands (or a fixed timeout elapses) and fires a `tmux send-keys` wake against the peer's pane.
 
-The v0.7 change: per-client wake routing after the v0.6 wake was found to be broken against idle TUI peers. Spike investigation (issue #3) revealed two distinct constraints, fixed differently. For **Codex**: the root cause was not `\r`-as-newline as initially suspected, but Codex's paste-burst heuristic (`codex-rs/tui/src/bottom_pane/paste_burst.rs`) suppressing Enter for ~120ms after a fast typed burst — `tmux send-keys -l text` + immediate `send-keys Enter` looked like a paste, so the trailing Enter was forcibly converted to newline. Fix: a 500ms gap between the text and the Enter. Verified live 2026-05-13 against the live `oxtail-codex` peer in this repo. For **Claude Code**: idle peers are architecturally unwakeable from outside the process — the documented Claude Code hook surface has no idle event, no polling, no external "start a turn" mechanism (`Notification` is outbound-only; `FileChanged` only fires inside an in-flight turn). v0.7 ask_peer fail-fasts for Claude Code targets with `wake_status: "skipped_unsupported"` rather than burning the 45s timeout. The outbound is still enqueued and delivered next time the peer enters a turn. Wake strategy is overridable via `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` as a rollback.
+The v0.7 change: per-client wake routing after the v0.6 wake was found to be broken against idle TUI peers. Spike investigation (issue #3) revealed Codex's paste-burst heuristic (`codex-rs/tui/src/bottom_pane/paste_burst.rs`) was suppressing Enter for ~120ms after a fast typed burst — `tmux send-keys -l text` + immediate `send-keys Enter` looked like a paste, so the trailing Enter was forcibly converted to newline. Fix: a 500ms gap between the text and the Enter for Codex peers. Verified live 2026-05-13 against the live `oxtail-codex` peer in this repo. v0.7 also fail-fasted Claude Code targets with `wake_status: "skipped_unsupported"` based on a reading of the Claude Code hook catalog (no idle hook surface → "architecturally unwakeable") — but that reasoning conflated *hook events* (which Claude Code doesn't expose for idle) with *TUI input* (which works fine via `tmux send-keys`, the same mechanism that wakes Codex). A falsifying experiment 2026-05-13 against the live `oxtail-claudejr` peer confirmed the full round-trip works: ask_peer enqueue → manual send-keys → peer entered a turn → PreToolUse hook drained mailbox → peer replied via send_message. The fail-fast was a self-inflicted regression against oxtail's symmetric-matrix vision (Claude↔Claude, Claude↔Codex, both directions), so the short-circuit was removed in the follow-up. Claude Code peers now wake via the same send-keys mechanism, just without the Codex paste-burst gap. Wake strategy is overridable via `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` as a rollback.
 
 ## How to collaborate on this project
 
@@ -53,7 +53,7 @@ The v0.7 change: per-client wake routing after the v0.6 wake was found to be bro
 
 ## Recently shipped
 
-- **Per-client wake routing (v0.7).** `ask_peer` now routes its wake mechanism per `client_type`. Codex: paste-burst-aware send-keys (500ms gap between text and Enter) — verified to actually submit. Claude Code: fail-fast with `wake_status: "skipped_unsupported"` since the hook surface has no idle event. Response gains a `wake_status` field for caller diagnostics. Pre-wake pane re-resolution closes the stale-pane-ID race from v0.6. `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` env override for rollback. Issue #3 has the spike findings.
+- **Per-client wake routing (v0.7, refined).** `ask_peer` routes its wake mechanism per `client_type`. **Codex**: paste-burst-aware send-keys (500ms gap between text and Enter) — verified to submit. **Claude Code**: same send-keys mechanism without the gap (no paste-burst in its TUI) — verified end-to-end 2026-05-13 against `oxtail-claudejr`. v0.7 originally fail-fasted Claude Code targets under a hook-catalog argument; the follow-up restored symmetric wake after falsifying that conclusion empirically. Response includes a `wake_status` field for caller diagnostics. Pre-wake pane re-resolution closes the stale-pane-ID race from v0.6. `OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` env override for rollback. Issue #3 has the spike findings.
 - **Delegate-and-wait (v0.6).** `ask_peer({ target, body })` blocks server-side until the peer replies (filtered by `from_session_id`) or a fixed timeout elapses. Late replies fall back to the v0.5 hook / poll delivery path. Target must have a registered `client.session_id`.
 - **Cross-session messaging (v0.5).** `send_message({ target, body })` + `read_my_messages()`. Mailbox lives at `~/.oxtail/mailboxes/<server_pid>.jsonl`, drained under an `mkdir`-based advisory lock. Opt-in PreToolUse hook (`npx oxtail install-hook`) for mid-turn delivery to Claude Code.
 

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.7.1"] } } }
+{ "mcpServers": { "oxtail": { "command": "npx", "args": ["-y", "oxtail@0.9.1"] } } }
 ```
 
 **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.7.1"]
+args = ["-y", "oxtail@0.9.1"]
 ```
 
 **Claude slash command** (`/oxtail-join`):
 
 ```sh
 mkdir -p ~/.claude/commands
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.7.1/.claude/commands/oxtail-join.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.9.1/.claude/commands/oxtail-join.md \
   -o ~/.claude/commands/oxtail-join.md
 ```
 
@@ -44,9 +44,9 @@ curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.7.1/.claude/commands
 
 ```sh
 mkdir -p ~/.codex/skills/oxtail-join/agents
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.7.1/integrations/codex/oxtail-join/SKILL.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.9.1/integrations/codex/oxtail-join/SKILL.md \
   -o ~/.codex/skills/oxtail-join/SKILL.md
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.7.1/integrations/codex/oxtail-join/agents/openai.yaml \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.9.1/integrations/codex/oxtail-join/agents/openai.yaml \
   -o ~/.codex/skills/oxtail-join/agents/openai.yaml
 ```
 
@@ -65,13 +65,13 @@ Contributing? `git clone https://github.com/d4j3y2k/oxtail && cd oxtail && npm i
 - `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.
 - `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+)
-- `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`). v0.7 routes the wake per `client_type`: Codex gets a paste-burst-aware `tmux send-keys` wake that actually submits; Claude Code targets fail-fast (no wake surface for idle Claude — see "Delegate-and-wait" below). Response includes `wake_status` so the caller can distinguish "we polled and got nothing" from "this peer can't be woken." Use `send_message` for fire-and-forget. (v0.7+; v0.6 caveats below)
+- `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.9.1/AGENTS.md) for scope and architecture.
 
 ## Usage from an agent
 
@@ -114,23 +114,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
 
@@ -151,17 +170,17 @@ ask_peer({ target, body })
     }
 ```
 
-`wake_status` distinguishes the four outcomes a caller may need to handle differently. `fired` means the wake was attempted (or the reply arrived during the grace window, so no wake was needed). `skipped_unsupported` means the target's `client_type` cannot be woken externally — currently Claude Code, see "Per-client wake routing" below. `skipped_no_target` means no tmux pane/session resolved for the target. `disabled` means `OXTAIL_ASK_PEER_WAKE_STRATEGY=off` is in effect.
+`wake_status` distinguishes the four outcomes a caller may need to handle differently. `fired` means the wake was attempted (or the reply arrived during the grace window, so no wake was needed). `skipped_unsupported` is reserved — no client currently returns this in auto mode (both Codex and Claude Code wake via send-keys). `skipped_no_target` means no tmux pane/session resolved for the target. `disabled` means `OXTAIL_ASK_PEER_WAKE_STRATEGY=off` is in effect.
 
-`timed_out` is `true` only when the poll loop ran to its deadline without a reply. Fail-fast for `skipped_unsupported` returns `timed_out: false` because no polling was attempted — the message is still enqueued and will be delivered when the peer next enters a turn.
+`timed_out` is `true` only when the poll loop ran to its deadline without a reply.
 
 ### Per-client wake routing
 
-v0.7 routes the wake mechanism per `client_type`. Verified 2026-05-13 via spike investigation and falsifying experiment:
+`ask_peer` routes the wake mechanism per `client_type`. Verified 2026-05-13 via spike investigations and end-to-end falsifying experiments against the live `oxtail-codex` and `oxtail-claudejr` peers in this repo:
 
 - **Codex** — `tmux send-keys -l <text>` followed by `send-keys Enter` is the wake. The keystrokes are split by 500ms because Codex's TUI has a paste-burst heuristic in `codex-rs/tui/src/bottom_pane/paste_burst.rs` (`PASTE_BURST_MIN_CHARS=3`, `PASTE_ENTER_SUPPRESS_WINDOW=120ms`) that converts Enter→newline for ~120ms after a fast typed burst. Without the gap, the wake text accumulates in the composer and Enter is suppressed. With the gap, Codex submits and enters a turn. 500ms is a deliberately generous multiple of the documented window for upstream-drift safety.
 
-- **Claude Code** — fail-fast. Claude Code's hook surface (per [docs](https://code.claude.com/docs/en/hooks)) has no event that fires while the agent is idle: no polling hook, no external "start a turn" mechanism, `Notification` is outbound-only, `FileChanged` only fires inside an in-flight turn. An external process cannot rouse an idle Claude Code peer. ask_peer returns immediately with `wake_status: "skipped_unsupported"` rather than burning the timeout. The message is enqueued and delivered to the peer's PreToolUse hook on their next tool call (or via explicit `read_my_messages`).
+- **Claude Code** — `tmux send-keys -l <text>` + immediate `send-keys Enter`, no inter-keystroke gap. The Claude Code TUI has no paste-burst suppression, so back-to-back text+Enter submits cleanly. Once the peer is in a turn, the oxtail PreToolUse hook drains queued messages as `additionalContext` on the peer's first tool call (or the peer reads them explicitly via `read_my_messages`). v0.7 originally shipped a fail-fast here, reasoning from the [hook catalog](https://code.claude.com/docs/en/hooks) that "no idle hook" meant "unwakeable" — but send-keys is a TUI-input mechanism, not a hook event, and it submits the same way a human keypress would. The fail-fast was a self-inflicted gap against oxtail's symmetric-matrix vision (Claude↔Claude, Claude↔Codex, both directions); restored to symmetric wake in the v0.7 follow-up after an end-to-end falsifying experiment confirmed the full round-trip works.
 
 - **Unknown** — legacy v0.6 wake (text + Enter, no gap). No implied promise; if a new TUI lands, treat it as unknown until verified.
 
@@ -177,7 +196,7 @@ v0.7 routes the wake mechanism per `client_type`. Verified 2026-05-13 via spike
 
 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 +214,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.7.1
+OXTAIL_ASK_PEER_TIMEOUT_MS=30000 npx -y oxtail@0.9.1
 ```
 
 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 +261,11 @@ If `MCP_TRACE_FILE` is set in the environment, every detection run appends an ND
 
 ## Status
 
-v0.7.0. Replaces v0.6's wake mechanism with per-client routing after a spike investigation found the root cause was Codex's paste-burst heuristic suppressing Enter, not `\r`-as-newline. Codex idle peers now wake reliably via a 500ms-gap send-keys sequence (verified live 2026-05-13). Claude Code idle peers fail-fast with `wake_status: "skipped_unsupported"` — Claude Code's hook surface has no idle event so they're architecturally unwakeable from outside; the message is still enqueued and delivered next turn. ask_peer's response gains a `wake_status` field for caller diagnostics. 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 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 "\\nIf a message asks for a response and from_session_id is present, reply with mcp__oxtail__send_message using that UUID as target."
     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 "\\nIf a message asks for a response and from_session_id is present, reply with mcp__oxtail__send_message using that UUID as target."
+    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