oxtail 0.4.0 → 0.5.0

package/AGENTS.md

@@ -17,15 +17,17 @@ 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.4.0 shipped, dogfooding
+## Status: v0.5.0 shipped, dogfooding
 
-Six MCP tools live: `list_project_sessions`, `read_session`, `claim_session`, `set_my_state`, `register_my_session`, and `get_my_session`. 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`).
+Eight MCP tools live: `list_project_sessions`, `read_session`, `claim_session`, `set_my_state`, `register_my_session`, `get_my_session`, plus the v0.5 messaging pair `send_message` and `read_my_messages`. 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`).
 
 The v0.4.0 change: peer `client_session_id` and `transcript_path` now resolve reliably for Claude Code and Codex peers, even though Claude Code strips its session-id env var from MCP children. Detection layers in `src/detect/` — env, then birth-time fingerprint matching of transcript files, with a `claim_session` escape hatch (`register_my_session` is kept for debugging) — see `README.md` for details.
 
 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 (v1 list_project_sessions → v0.2 read_session → v0.3 reliable peer identity → v0.4 peer-awareness state cards) 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) 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`).
 
 ## How to collaborate on this project
 
@@ -41,9 +43,16 @@ Current phase remains **dogfooding**: use the tools in real parallel-agent work,
 3. **Both Claude Code and Codex CLI must work** with whatever we build. MCP is the cross-tool protocol; Skills are Claude-specific syntactic sugar that wraps MCP tools, never primary functionality.
 4. **Minimum viable first.** One MCP tool that's actually used > five speculative ones.
 
+## Recently shipped
+
+- **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.
+
 ## Deliberately deferred
 
 - **Output capture** (vs. metadata only). Costs a wrapper layer (`script -F` or pty-mirror). Only worth doing if real friction shows metadata isn't enough.
-- **Cross-session messaging** (note from session A to session B). Probably useful eventually; not until real use names the shape.
+- **Codex mid-turn delivery.** Pending Codex CLI exposing a hook surface.
+- **Delivery receipts / read receipts.** Sender learns `{ ok: true, message_id }`; whether the recipient saw it is invisible. Add when real use names the shape.
+- **Broadcast / multi-recipient send_message.** 1:1 only in v0.5.
+- **Orphan mailbox cleanup.** Mailbox files for dead pids accumulate in `~/.oxtail/mailboxes/`. Tiny and harmless; revisit when real waste shows up in `du`.
 - **Skill set.** Decide after the first MCP tool exists and we know what it feels like to use raw.
 - **MCP tool naming.** Pick after observation tells us the verbs.

package/README.md

@@ -19,7 +19,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.4.0"] } } }
+{ "mcpServers": { "oxtail": { "command": "npx", "args": ["-y", "oxtail@0.5.0"] } } }
 ```
 
 **Codex CLI** — add to `~/.codex/config.toml`:
@@ -27,14 +27,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.4.0"]
+args = ["-y", "oxtail@0.5.0"]
 ```
 
 **Claude slash command** (`/oxtail-join`):
 
 ```sh
 mkdir -p ~/.claude/commands
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.4.0/.claude/commands/oxtail-join.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.5.0/.claude/commands/oxtail-join.md \
   -o ~/.claude/commands/oxtail-join.md
 ```
 
@@ -42,9 +42,9 @@ curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.4.0/.claude/commands
 
 ```sh
 mkdir -p ~/.codex/skills/oxtail-register/agents
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.4.0/integrations/codex/oxtail-register/SKILL.md \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.5.0/integrations/codex/oxtail-register/SKILL.md \
   -o ~/.codex/skills/oxtail-register/SKILL.md
-curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.4.0/integrations/codex/oxtail-register/agents/openai.yaml \
+curl -L https://raw.githubusercontent.com/d4j3y2k/oxtail/v0.5.0/integrations/codex/oxtail-register/agents/openai.yaml \
   -o ~/.codex/skills/oxtail-register/agents/openai.yaml
 ```
 
@@ -63,10 +63,12 @@ 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.
 - `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` — send a short text message to a peer session in the same project root. 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+)
 - `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.4.0/AGENTS.md) for scope and architecture.
+See [design principles](https://github.com/d4j3y2k/oxtail/blob/v0.5.0/AGENTS.md) for scope and architecture.
 
 ## Usage from an agent
 
@@ -77,6 +79,8 @@ 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 })
+send_message({ target: "primary", body: "<system-reminder>checking in</system-reminder>" })
+read_my_messages()
 ```
 
 Omitting `project_root` triggers a best-effort `.git`-ancestor walk from the server's own cwd. The response includes `inferred: true` when this happens. Pass `project_root` explicitly when you can.
@@ -85,6 +89,46 @@ Omitting `project_root` triggers a best-effort `.git`-ancestor walk from the ser
 
 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.
 
+## Peer messaging (v0.5)
+
+Two MCP tools let peers in the same project root talk to each other:
+
+```
+send_message({ target: "<tmux-session-name OR client_session_id UUID>", body: "..." })
+  → { ok: true, message_id, target_session_id, target_server_pid }
+
+read_my_messages()
+  → { ok: true, drained: true, count, messages: [...] }
+```
+
+The mailbox lives at `~/.oxtail/mailboxes/<server_pid>.jsonl`, append-only JSONL, drained under an `mkdir`-based advisory lock. The transport is intentionally dumb: 8KB UTF-8 body cap, sender chooses the framing (raw text or pre-wrapped `<system-reminder>...</system-reminder>`).
+
+Cross-project sends are rejected, never silently dropped. Sending to a peer with the same tmux session name as another live peer returns `ambiguous-target` with the candidate `client_session_id`s — use the UUID form to disambiguate.
+
+### Mid-turn vs next-turn delivery (the asymmetry)
+
+Claude Code peers can receive messages **mid-turn** via an opt-in PreToolUse hook:
+
+```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`.
+
+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.
+
+**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.
+
+### 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.
+
+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.
+
+### Trust model
+
+oxtail trusts any process running as the **same local user** to enqueue messages. The mailbox directory is mode `0o700` (private), so other users on the host cannot read or write. **On a shared-tenancy box (containers, multi-user dev hosts, etc.), do not run oxtail-aware agents:** any local process under your user can inject `<system-reminder>` content directly into a Claude session. The threat boundary is the same as `~/.ssh/` — what your user processes do, you trust.
+
 ## Self-registration and the peer registry
 
 Each oxtail server, when spawned by an agent, writes a small record to `~/.oxtail/sessions/<pid>.json` containing the client type, session id, transcript path, and tmux pane. Sibling servers read this directory to find peer transcripts. Records auto-clean on process exit and on read (dead PIDs pruned). Sessions whose agents are not oxtail-aware (or are not LLM agents at all — bash, vim, vite dev servers) still show up in `list_project_sessions` and are readable via `read_session` in pane mode.
@@ -105,4 +149,4 @@ If `MCP_TRACE_FILE` is set in the environment, every detection run appends an ND
 
 ## Status
 
-v0.4.0. Reliable peer identity: `client_session_id` resolves automatically for Claude Code and Codex via filesystem fingerprint matching, with a self-register escape hatch for ambiguous cases. Project-local and global registrations both supported.
+v0.5.0. Peer-to-peer messaging is live: `send_message` / `read_my_messages` over a per-pid mailbox file at `~/.oxtail/mailboxes/`. Claude Code peers receive mid-turn via an opt-in PreToolUse hook (`npx oxtail install-hook`); Codex CLI peers poll. Coexistence with Terminator's `_terminatorHook` verified in Claude Code 2.1.139.

package/assets/pretooluse.sh

@@ -0,0 +1,120 @@
+#!/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.
+#
+# 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.
+
+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.
+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
+
+sessions_dir="$HOME/.oxtail/sessions"
+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
+
+mbox="$mailboxes_dir/$pid.jsonl"
+[ -f "$mbox" ] || exit 0
+[ -s "$mbox" ] || 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
+done
+[ "$acquired" -eq 1 ] || 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.
+output=$(awk '
+  BEGIN { count = 0 }
+  {
+    p = index($0, "\"body\":\"")
+    if (p == 0) next
+    rest = substr($0, p + 8)
+    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
+      }
+    }
+    bodies[count++] = out
+  }
+  END {
+    if (count == 0) exit 0
+    ctx = ""
+    for (j = 0; j < count; j++) {
+      if (j > 0) ctx = ctx "\\n\\n"
+      ctx = ctx bodies[j]
+    }
+    printf("{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"%s\"}}\n", ctx)
+  }
+' < "$mbox")
+
+if [ -n "$output" ]; then
+  printf '%s' "$output"
+  : > "$mbox"
+fi
+
+rmdir "$mbox.lock" 2>/dev/null || true
+exit 0

package/dist/mailbox.js

@@ -0,0 +1,173 @@
+import { randomBytes } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, rmdirSync, statSync, truncateSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { trace } from "./trace.js";
+// Resolved lazily so tests can swap HOME between cases. Each call re-reads
+// homedir(), which on POSIX defers to $HOME.
+function mailboxesDir() {
+    return join(homedir(), ".oxtail", "mailboxes");
+}
+// Lock staleness window. The drainer reads the file, builds the JSON envelope,
+// and writes the truncate back to disk all under lock — under slow disks or OS
+// hiccups, a legitimate-but-slow drain can approach the original 5s threshold
+// and let a peer steal the lock. 30s widens the window to make accidental
+// theft very rare; the trade-off is that a genuinely crashed drainer holds the
+// lock 25s longer before recovery. Worth it.
+//
+// Sync this value with assets/pretooluse.sh (find -mmin +0.5 ≈ 30s).
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_LIMIT = 50;
+const LOCK_RETRY_DELAY_MS = 10;
+function mailboxPath(pid) {
+    return join(mailboxesDir(), `${pid}.jsonl`);
+}
+function lockPath(pid) {
+    return `${mailboxPath(pid)}.lock`;
+}
+function sleepSync(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // tight spin — short enough (10ms) that this is acceptable
+    }
+}
+export function acquireLock(pid) {
+    mkdirSync(mailboxesDir(), { recursive: true, mode: 0o700 });
+    const lock = lockPath(pid);
+    for (let i = 0; i < LOCK_RETRY_LIMIT; i++) {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            return;
+        }
+        catch (e) {
+            const err = e;
+            if (err.code !== "EEXIST")
+                throw err;
+            // Check staleness. If older than LOCK_STALE_MS, force-clear and retry.
+            try {
+                const st = statSync(lock);
+                if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                    try {
+                        rmdirSync(lock);
+                        trace("mailbox_lock_stale_clear", { pid });
+                    }
+                    catch {
+                        // raced with another clearer; fall through to retry
+                    }
+                    continue;
+                }
+            }
+            catch {
+                // stat may race; just retry
+            }
+            sleepSync(LOCK_RETRY_DELAY_MS);
+        }
+    }
+    throw new Error(`could not acquire mailbox lock for pid ${pid}`);
+}
+export function releaseLock(pid) {
+    try {
+        rmdirSync(lockPath(pid));
+    }
+    catch {
+        // ignore ENOENT / not-empty / EPERM
+    }
+}
+// Critical: the serialized JSONL line must always begin
+// `{"schema_version":1,"id":"...","body":"`. The awk extractor in
+// assets/pretooluse.sh assumes `"body":"` is the third key. A future refactor
+// that uses Object.assign / spread / inserts a key could silently reorder and
+// break the hook without breaking unit tests that don't check serialization.
+// The runtime regex below catches that.
+const FIELD_ORDER_PREFIX = /^\{"schema_version":1,"id":"[0-9a-f]{16}","body":"/;
+export function enqueue(target_pid, body, from_session_id) {
+    const msg = {
+        schema_version: 1,
+        id: randomBytes(8).toString("hex"),
+        body,
+        enqueued_at: Math.floor(Date.now() / 1000),
+        ...(from_session_id ? { from_session_id } : {}),
+    };
+    // Build the line by inserting keys in the invariant order. Node's
+    // JSON.stringify preserves insertion order for non-integer string keys,
+    // which the test suite pins.
+    const obj = {
+        schema_version: msg.schema_version,
+        id: msg.id,
+        body: msg.body,
+        enqueued_at: msg.enqueued_at,
+    };
+    if (from_session_id)
+        obj.from_session_id = from_session_id;
+    const line = JSON.stringify(obj) + "\n";
+    if (!FIELD_ORDER_PREFIX.test(line)) {
+        throw new Error(`mailbox enqueue: serialized line violates field-order invariant. ` +
+            `Got prefix: ${line.slice(0, 80)}`);
+    }
+    acquireLock(target_pid);
+    try {
+        appendFileSync(mailboxPath(target_pid), line);
+    }
+    finally {
+        releaseLock(target_pid);
+    }
+    return msg;
+}
+export function drain(my_pid) {
+    acquireLock(my_pid);
+    try {
+        let raw;
+        try {
+            raw = readFileSync(mailboxPath(my_pid), "utf8");
+        }
+        catch (e) {
+            const err = e;
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        if (!raw)
+            return [];
+        const out = [];
+        for (const line of raw.split("\n")) {
+            if (!line)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                trace("mailbox_drain_skip_invalid", { pid: my_pid, line });
+                continue;
+            }
+            if (parsed &&
+                typeof parsed === "object" &&
+                parsed.schema_version === 1 &&
+                typeof parsed.id === "string" &&
+                typeof parsed.body === "string") {
+                out.push(parsed);
+            }
+            else {
+                trace("mailbox_drain_skip_invalid", { pid: my_pid, line });
+            }
+        }
+        try {
+            truncateSync(mailboxPath(my_pid), 0);
+        }
+        catch (e) {
+            const err = e;
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        return out;
+    }
+    finally {
+        releaseLock(my_pid);
+    }
+}
+export function mailboxFilePath(pid) {
+    return mailboxPath(pid);
+}
+export function mailboxLockPath(pid) {
+    return lockPath(pid);
+}

package/dist/registry.js

@@ -2,25 +2,29 @@ import { execFileSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-const REGISTRY_DIR = join(homedir(), ".oxtail", "sessions");
+// Lazy so tests can swap HOME between cases; homedir() defers to $HOME on POSIX.
+function registryDir() {
+    return join(homedir(), ".oxtail", "sessions");
+}
 function ensureDir() {
-    if (!existsSync(REGISTRY_DIR)) {
-        mkdirSync(REGISTRY_DIR, { recursive: true, mode: 0o700 });
+    const dir = registryDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
         return;
     }
     // Migration: tighten perms for users upgrading from <0.4.0, where the dir
     // and entries were created at default umask (typically 0o755 / 0o644).
     try {
-        chmodSync(REGISTRY_DIR, 0o700);
+        chmodSync(dir, 0o700);
     }
     catch {
         // not our dir or fs doesn't support; leave it
     }
-    for (const file of readdirSync(REGISTRY_DIR)) {
+    for (const file of readdirSync(dir)) {
         if (!file.endsWith(".json"))
             continue;
         try {
-            chmodSync(join(REGISTRY_DIR, file), 0o600);
+            chmodSync(join(dir, file), 0o600);
         }
         catch {
             // ignore
@@ -28,7 +32,7 @@ function ensureDir() {
     }
 }
 function entryPath(pid) {
-    return join(REGISTRY_DIR, `${pid}.json`);
+    return join(registryDir(), `${pid}.json`);
 }
 function resolveTmuxSessionFromPane(pane) {
     if (!pane)
@@ -168,13 +172,14 @@ function isAlive(pid) {
     }
 }
 export function readAll() {
-    if (!existsSync(REGISTRY_DIR))
+    const dir = registryDir();
+    if (!existsSync(dir))
         return [];
     const out = [];
-    for (const file of readdirSync(REGISTRY_DIR)) {
+    for (const file of readdirSync(dir)) {
         if (!file.endsWith(".json"))
             continue;
-        const full = join(REGISTRY_DIR, file);
+        const full = join(dir, file);
         let entry;
         try {
             entry = JSON.parse(readFileSync(full, "utf8"));

package/dist/server.js

@@ -4,11 +4,33 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import * as z from "zod/v4";
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, sep } from "node:path";
 import { clientFromHandshake, detectClient, enrichWithDiagnosis, transcriptPathFor, } from "./clients.js";
 import { isAbstain } from "./detect/index.js";
 import { trace } from "./trace.js";
 import { buildEntry, findByTmuxSession, readAll, refreshTmuxBinding, register, unregister, } from "./registry.js";
+import * as mailbox from "./mailbox.js";
+// CLI subcommand dispatch must run before any MCP setup so that
+// `npx oxtail install-hook` doesn't open an MCP transport or register a
+// session. Use named exports and await them; calling `await import(...)`
+// alone resolves at module-evaluation but would let process.exit(0) race
+// the script's async work.
+{
+    const sub = process.argv[2];
+    if (sub === "install-hook") {
+        const url = new URL("../scripts/install-hook.mjs", import.meta.url).href;
+        const mod = (await import(url));
+        await mod.install();
+        process.exit(0);
+    }
+    if (sub === "uninstall-hook") {
+        const url = new URL("../scripts/uninstall-hook.mjs", import.meta.url).href;
+        const mod = (await import(url));
+        await mod.uninstall();
+        process.exit(0);
+    }
+}
 import { readClaudeTranscript, readCodexTranscript, } from "./transcripts.js";
 const TMUX_LIST_FORMAT = "#{session_name}|#{session_path}|#{session_created}|#{session_attached}|#{session_windows}";
 const TMUX_PANES_FORMAT = "#{session_name}|#{pane_current_path}";
@@ -555,5 +577,165 @@ server.registerTool("set_my_state", {
         ],
     };
 });
+function projectRootsMatch(caller, peer) {
+    const myRoot = safeRealpath(inferProjectRoot(caller.client.cwd));
+    const peerRoot = safeRealpath(inferProjectRoot(peer.client.cwd));
+    if (myRoot === peerRoot)
+        return true;
+    if (isDescendantOrEqual(safeRealpath(peer.client.cwd), myRoot))
+        return true;
+    if (isDescendantOrEqual(safeRealpath(caller.client.cwd), peerRoot))
+        return true;
+    return false;
+}
+function isAliveLocal(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        const err = e;
+        return err.code === "EPERM";
+    }
+}
+function reReadRegistryEntry(server_pid) {
+    // PID-reuse guard: re-read the on-disk file and compare started_at to the
+    // one we cached in memory at lookup time. A reused pid lands on a freshly
+    // written entry with a different started_at.
+    const path = join(homedir(), ".oxtail", "sessions", `${server_pid}.json`);
+    try {
+        const raw = readFileSync(path, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+const UUID_RE = /^[0-9a-f-]{36}$/;
+function resolveTarget(target, caller) {
+    const all = readAll();
+    let candidates;
+    if (UUID_RE.test(target)) {
+        candidates = all.filter((e) => e.client.session_id === target);
+    }
+    else {
+        candidates = all.filter((e) => e.tmux_session === target);
+    }
+    // Liveness + PID-reuse guard: keep only entries whose pid is alive AND whose
+    // on-disk started_at still matches what readAll() returned. A reused pid
+    // would have been overwritten with a different started_at.
+    candidates = candidates.filter((e) => {
+        if (!isAliveLocal(e.server_pid))
+            return false;
+        const fresh = reReadRegistryEntry(e.server_pid);
+        if (!fresh)
+            return false;
+        return fresh.started_at === e.started_at;
+    });
+    if (candidates.length === 0)
+        return { ok: false, error: "target-not-found" };
+    if (candidates.length > 1) {
+        return {
+            ok: false,
+            error: "ambiguous-target",
+            candidates: candidates.map((c) => c.client.session_id ?? `pid:${c.server_pid}`),
+        };
+    }
+    const peer = candidates[0];
+    // Self-send by pid (definitive identity), not by tmux name / session_id.
+    if (peer.server_pid === caller.server_pid)
+        return { ok: false, error: "self-send" };
+    if (!projectRootsMatch(caller, peer))
+        return { ok: false, error: "cross-project" };
+    return { ok: true, entry: peer };
+}
+server.registerTool("send_message", {
+    description: [
+        "Send a short text message to a peer session in the same project root. Target may be a tmux session name (as shown by list_project_sessions) or a raw client_session_id (UUID).",
+        "Delivery is asynchronous: the message lands in the target's mailbox and is delivered mid-turn via the oxtail PreToolUse hook (Claude Code) or next-turn via read_my_messages (Codex, or any client without the hook installed).",
+        "Sender-side wrapping: if you want the message to appear as a system-reminder, include the <system-reminder>...</system-reminder> tags in `body`. The mailbox is a dumb transport.",
+        "Cross-project targets are rejected, never silently dropped.",
+    ].join(" "),
+    inputSchema: {
+        target: z
+            .string()
+            .min(1)
+            .describe("tmux session name OR client_session_id (UUID) of the peer."),
+        body: z
+            .string()
+            .min(1)
+            .refine((s) => Buffer.byteLength(s, "utf8") <= 8192, {
+            message: "body exceeds 8192 UTF-8 bytes",
+        })
+            .describe("Message body, ≤8KB UTF-8. The sender chooses the framing."),
+    },
+}, async ({ target, body }) => {
+    const resolved = resolveTarget(target, entry);
+    if (!resolved.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ schema_version: 1, ...resolved }, null, 2),
+                },
+            ],
+        };
+    }
+    const peer = resolved.entry;
+    const fromSessionId = entry.client.session_id ?? undefined;
+    const msg = mailbox.enqueue(peer.server_pid, body, fromSessionId);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    schema_version: 1,
+                    ok: true,
+                    message_id: msg.id,
+                    target_session_id: peer.client.session_id,
+                    target_server_pid: peer.server_pid,
+                }, null, 2),
+            },
+        ],
+    };
+});
+server.registerTool("read_my_messages", {
+    description: "Drain this session's mailbox and return any messages peers have sent via send_message. Codex peers and any Claude Code peer without the PreToolUse hook installed must poll this tool explicitly; Claude Code peers with the hook installed will see messages mid-turn instead. Always safe to call — returns an empty list when the mailbox is empty.",
+    inputSchema: {},
+}, async () => {
+    const messages = mailbox.drain(entry.server_pid);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    schema_version: 1,
+                    ok: true,
+                    drained: true,
+                    count: messages.length,
+                    messages,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// Hook-install hint, emitted once per server startup when no `_oxtailHook`
+// marker is present in ~/.claude/settings.json. Stderr surfacing in Claude
+// Code is a soft assumption; if the hint never reaches the user they miss
+// the prompt and fall back to polling — acceptable.
+function maybeHookHint() {
+    if (entry.client.type !== "claude-code")
+        return;
+    try {
+        const settings = readFileSync(join(homedir(), ".claude", "settings.json"), "utf8");
+        if (settings.includes("_oxtailHook"))
+            return;
+    }
+    catch {
+        // settings file missing is itself a signal the hook isn't installed
+    }
+    process.stderr.write("[oxtail] PreToolUse hook not installed — run `npx oxtail install-hook` to enable mid-turn peer messaging.\n");
+}
 const transport = new StdioServerTransport();
 await server.connect(transport);
+maybeHookHint();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxtail",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "Coordination layer for parallel AI coding agent sessions, exposed over MCP.",
@@ -10,6 +10,8 @@
   },
   "files": [
     "dist",
+    "scripts",
+    "assets",
     "integrations",
     ".claude/commands/oxtail-join.md",
     "AGENTS.md",
@@ -47,6 +49,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "jsonc-parser": "^3.3.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/scripts/hook-constants.mjs

@@ -0,0 +1,19 @@
+// Shared constants for install-hook.mjs / uninstall-hook.mjs.
+// Tiny on purpose — only the things both scripts genuinely need.
+
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+
+export const SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
+export const HOOK_MARKER_KEY = "_oxtailHook";
+export const HOOK_MARKER_VERSION = 1;
+export const HOOK_SCRIPT_PATH = path.join(os.homedir(), ".oxtail", "hooks", "pretooluse.sh");
+// The literal command string that ends up in settings.json. Stable across
+// installs — only the script file at HOOK_SCRIPT_PATH may drift, which is
+// why we only hash the script (not the command).
+export const HOOK_COMMAND = `"$HOME/.oxtail/hooks/pretooluse.sh"`;
+
+export function scriptHash(text) {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}

package/scripts/install-hook.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// Install the oxtail PreToolUse hook into ~/.claude/settings.json.
+//
+// Idempotent: re-running on an installed system reports "already installed"
+// and exits 0 without writing. Format-preserving: edits use jsonc-parser so
+// unrelated keys, whitespace, and comments survive.
+//
+// Reverse with: npx oxtail uninstall-hook
+
+import { readFile, writeFile, mkdir, rename, chmod } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { applyEdits, modify, parse } from "jsonc-parser";
+import {
+  SETTINGS_PATH,
+  HOOK_MARKER_KEY,
+  HOOK_MARKER_VERSION,
+  HOOK_SCRIPT_PATH,
+  HOOK_COMMAND,
+  scriptHash,
+} from "./hook-constants.mjs";
+
+const SHIPPED_HOOK_PATH = new URL("../assets/pretooluse.sh", import.meta.url).pathname;
+const FORMATTING = { tabSize: 2, insertSpaces: true };
+
+function findOxtailHookIndex(parsed) {
+  const arr = parsed?.hooks?.PreToolUse;
+  if (!Array.isArray(arr)) return -1;
+  return arr.findIndex((entry) => {
+    if (!entry || typeof entry !== "object") return false;
+    if (!Array.isArray(entry.hooks)) return false;
+    return entry.hooks.some(
+      (h) =>
+        h &&
+        typeof h === "object" &&
+        typeof h.command === "string" &&
+        // Loose match: any command referencing our installed script path.
+        h.command.includes("oxtail/hooks/pretooluse.sh"),
+    );
+  });
+}
+
+export async function install() {
+  const shipped = await readFile(SHIPPED_HOOK_PATH, "utf8");
+  const wantHash = scriptHash(shipped);
+
+  let source = "{}\n";
+  if (existsSync(SETTINGS_PATH)) source = await readFile(SETTINGS_PATH, "utf8");
+  const parsed = parse(source) ?? {};
+
+  const marker = parsed[HOOK_MARKER_KEY];
+  const existingIdx = findOxtailHookIndex(parsed);
+  const upToDate =
+    marker &&
+    typeof marker === "object" &&
+    marker.version === HOOK_MARKER_VERSION &&
+    marker.scriptHash === wantHash &&
+    existingIdx >= 0 &&
+    existsSync(HOOK_SCRIPT_PATH);
+  if (upToDate) {
+    console.log(
+      `oxtail hook already installed (v${HOOK_MARKER_VERSION}, hash ${wantHash.slice(0, 8)}). No changes.`,
+    );
+    return;
+  }
+
+  // Detect competing PreToolUse hooks (e.g. Terminator's _terminatorHook).
+  // Behavior under multi-hook coexistence is determined live in Step 5
+  // case 11 — for now, warn so users know install order may matter.
+  const otherHooks = (parsed?.hooks?.PreToolUse ?? []).filter((entry, idx) => {
+    if (idx === existingIdx) return false;
+    if (!entry || !Array.isArray(entry.hooks)) return false;
+    return entry.hooks.some(
+      (h) => h && typeof h.command === "string" && !h.command.includes("oxtail/hooks/pretooluse.sh"),
+    );
+  });
+  if (otherHooks.length > 0) {
+    console.warn(
+      `[oxtail] note: ${otherHooks.length} other PreToolUse hook(s) already installed. ` +
+      `Multi-hook coexistence is supported but install order may matter; ` +
+      `see README "Hook coexistence" for details.`,
+    );
+  }
+
+  // Back up settings.json before mutating it (Skeptic M4).
+  if (existsSync(SETTINGS_PATH)) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backup = `${SETTINGS_PATH}.oxtail-backup.${stamp}`;
+    await writeFile(backup, source, "utf8");
+    console.log(`Backed up existing settings to ${backup}`);
+  }
+
+  // Install the shipped script atomically.
+  const hooksDir = path.dirname(HOOK_SCRIPT_PATH);
+  await mkdir(hooksDir, { recursive: true, mode: 0o755 });
+  const scriptTmp = `${HOOK_SCRIPT_PATH}.tmp-${randomBytes(6).toString("hex")}`;
+  await writeFile(scriptTmp, shipped, { mode: 0o755 });
+  // writeFile's `mode` option only applies on file creation; an existing
+  // tmp file would keep its previous perms. Explicit chmod for belt+braces.
+  await chmod(scriptTmp, 0o755);
+  await rename(scriptTmp, HOOK_SCRIPT_PATH);
+
+  // Edit settings.json. Replace any prior oxtail entry; else append.
+  let text = source;
+  const newEntry = { hooks: [{ type: "command", command: HOOK_COMMAND }] };
+  const arr = parsed?.hooks?.PreToolUse;
+  if (existingIdx >= 0) {
+    text = applyEdits(
+      text,
+      modify(text, ["hooks", "PreToolUse", existingIdx], newEntry, { formattingOptions: FORMATTING }),
+    );
+  } else {
+    const insertIdx = Array.isArray(arr) ? arr.length : 0;
+    text = applyEdits(
+      text,
+      modify(text, ["hooks", "PreToolUse", insertIdx], newEntry, { formattingOptions: FORMATTING }),
+    );
+  }
+  text = applyEdits(
+    text,
+    modify(
+      text,
+      [HOOK_MARKER_KEY],
+      {
+        version: HOOK_MARKER_VERSION,
+        installedAt: new Date().toISOString(),
+        scriptHash: wantHash,
+      },
+      { formattingOptions: FORMATTING },
+    ),
+  );
+
+  // Atomic write of settings.json.
+  const settingsTmp = `${SETTINGS_PATH}.oxtail-tmp-${randomBytes(6).toString("hex")}`;
+  await mkdir(path.dirname(SETTINGS_PATH), { recursive: true });
+  await writeFile(settingsTmp, text, "utf8");
+  await rename(settingsTmp, SETTINGS_PATH);
+
+  console.log(`Installed oxtail PreToolUse hook in ${SETTINGS_PATH}.`);
+  console.log("Reverse with: npx oxtail uninstall-hook");
+}
+
+const invokedDirectly =
+  typeof process.argv[1] === "string" &&
+  import.meta.url === new URL(process.argv[1], "file:").href;
+if (invokedDirectly) {
+  install().catch((err) => {
+    console.error("install-hook failed:", err?.message ?? err);
+    process.exit(1);
+  });
+}

package/scripts/uninstall-hook.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// Remove the oxtail PreToolUse hook entry and marker from
+// ~/.claude/settings.json, and delete the installed ~/.oxtail/hooks/pretooluse.sh.
+//
+// Idempotent: a clean run on an uninstalled system exits 0 with "nothing to do."
+
+import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { applyEdits, modify, parse } from "jsonc-parser";
+import {
+  SETTINGS_PATH,
+  HOOK_MARKER_KEY,
+  HOOK_SCRIPT_PATH,
+} from "./hook-constants.mjs";
+
+const FORMATTING = { tabSize: 2, insertSpaces: true };
+
+function findOxtailHookIndex(parsed) {
+  const arr = parsed?.hooks?.PreToolUse;
+  if (!Array.isArray(arr)) return -1;
+  return arr.findIndex((entry) => {
+    if (!entry || typeof entry !== "object") return false;
+    if (!Array.isArray(entry.hooks)) return false;
+    return entry.hooks.some(
+      (h) =>
+        h &&
+        typeof h === "object" &&
+        typeof h.command === "string" &&
+        h.command.includes("oxtail/hooks/pretooluse.sh"),
+    );
+  });
+}
+
+export async function uninstall() {
+  if (!existsSync(SETTINGS_PATH)) {
+    console.log(`No ${SETTINGS_PATH} — nothing to do.`);
+    // Still try to remove the installed script in case it's a leftover.
+    if (existsSync(HOOK_SCRIPT_PATH)) {
+      try {
+        await unlink(HOOK_SCRIPT_PATH);
+        console.log(`Removed ${HOOK_SCRIPT_PATH}.`);
+      } catch (err) {
+        console.warn(`Could not remove ${HOOK_SCRIPT_PATH}: ${err?.message ?? err}`);
+      }
+    }
+    return;
+  }
+
+  const source = await readFile(SETTINGS_PATH, "utf8");
+  const parsed = parse(source) ?? {};
+
+  const idx = findOxtailHookIndex(parsed);
+  const hasMarker =
+    parsed[HOOK_MARKER_KEY] && typeof parsed[HOOK_MARKER_KEY] === "object";
+
+  if (idx < 0 && !hasMarker && !existsSync(HOOK_SCRIPT_PATH)) {
+    console.log("oxtail hook not installed — nothing to do.");
+    return;
+  }
+
+  let text = source;
+  if (idx >= 0) {
+    text = applyEdits(
+      text,
+      modify(text, ["hooks", "PreToolUse", idx], undefined, { formattingOptions: FORMATTING }),
+    );
+  }
+  if (hasMarker) {
+    text = applyEdits(
+      text,
+      modify(text, [HOOK_MARKER_KEY], undefined, { formattingOptions: FORMATTING }),
+    );
+  }
+
+  const settingsTmp = `${SETTINGS_PATH}.oxtail-tmp-${randomBytes(6).toString("hex")}`;
+  await mkdir(path.dirname(SETTINGS_PATH), { recursive: true });
+  await writeFile(settingsTmp, text, "utf8");
+  await rename(settingsTmp, SETTINGS_PATH);
+  console.log(`Removed oxtail PreToolUse hook from ${SETTINGS_PATH}.`);
+
+  if (existsSync(HOOK_SCRIPT_PATH)) {
+    try {
+      await unlink(HOOK_SCRIPT_PATH);
+      console.log(`Removed ${HOOK_SCRIPT_PATH}.`);
+    } catch (err) {
+      console.warn(`Could not remove ${HOOK_SCRIPT_PATH}: ${err?.message ?? err}`);
+    }
+  }
+}
+
+const invokedDirectly =
+  typeof process.argv[1] === "string" &&
+  import.meta.url === new URL(process.argv[1], "file:").href;
+if (invokedDirectly) {
+  uninstall().catch((err) => {
+    console.error("uninstall-hook failed:", err?.message ?? err);
+    process.exit(1);
+  });
+}