oxtail 0.6.1 → 0.7.0

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.6.0 shipped, dogfooding
+## Status: v0.7.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 the v0.6 delegate-and-wait primitive `ask_peer`. 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`).
 
@@ -31,7 +31,7 @@ The v0.5 change: two new MCP tools (`send_message`, `read_my_messages`) plus an
 
 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.
 
-**v0.6 known limitation (tracked in issue #3, scoped for v0.7).** The wake does *not* reliably rouse fully-idle TUI peers. Codex composer pollution is verified (2026-05-13 in `terminal-orchestrator`): the wake's `tmux send-keys ... Enter` lands as typed-but-not-submitted text in Codex's `›` composer, leaving the wake notification visible to the user but never flushing it as a turn. Idle Claude Code peers are also unwoken in practice — the PreToolUse hook only fires inside an existing turn, so idle Claude at its prompt has no polling path — but the root cause is not yet captured the same way (could be the same `\r`-as-newline issue; could be different). For now, `ask_peer` is reliable only when the target is already in a turn (or enters one on its own via user input) inside the timeout window. Against a fully idle peer with no human at the keyboard, expect `timed_out: true`.
+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.
 
 ## How to collaborate on this project
 
@@ -53,7 +53,8 @@ The v0.6 change: one new MCP tool (`ask_peer`) that turns v0.5's async pings int
 
 ## Recently shipped
 
-- **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, with a best-effort `tmux send-keys` wake attempted against the peer's pane. Late replies fall back to the v0.5 hook / poll delivery path. Target must have a registered `client.session_id`. **Idle-TUI wake is not reliable in v0.6** — see the limitation note above and issue #3.
+- **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.
+- **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.
 
 ## Deliberately deferred

package/README.md

@@ -65,9 +65,9 @@ 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+) (`ask_peer` attempts a wake but the v0.6 implementation does not reliably rouse idle TUI peers — see its description.)
+- `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`). Fires a best-effort `tmux send-keys` wake. **Known limitation (issue #3, planned v0.7):** the wake does not reliably rouse fully-idle TUI peers — see "Delegate-and-wait (v0.6)" below. Reliable when the target is already in a turn; against a fully idle peer expect timeout. Use `send_message` when you don't need a synchronous reply. (v0.6+)
+- `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)
 - `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.
 
@@ -136,30 +136,59 @@ If you have a PreToolUse hook installed that isn't from Terminator and isn't oxt
 
 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.
 
-## Delegate-and-wait (v0.6)
+## Delegate-and-wait (v0.7)
 
 `ask_peer` extends v0.5's mailbox transport into a blocking primitive:
 
 ```
 ask_peer({ target, body })
-  → { ok: true, message_id, reply: { id, body, enqueued_at, from_session_id } | null, timed_out }
+  → {
+      ok: true,
+      message_id,
+      wake_status: "fired" | "skipped_unsupported" | "skipped_no_target" | "disabled",
+      reply: { id, body, enqueued_at, from_session_id } | null,
+      timed_out,
+    }
 ```
 
-> **Known limitation in v0.6 — read this before relying on `ask_peer`.** The wake mechanism does not reliably rouse a fully-idle TUI peer. Verified 2026-05-13 against Codex CLI: the `tmux send-keys ... Enter` lands in Codex's `›` composer as typed-but-not-submitted text, leaving the wake notification visible to the user but never flushing it as a turn. Idle Claude Code peers are also unwoken in practice (no polling at the prompt), though the exact mechanism is not yet root-caused the same way. `ask_peer` is therefore reliable only when the target is already in a turn (or enters one on its own via user input or another tool call's PreToolUse hook) inside the timeout window. Against a fully idle peer with no human at the keyboard, expect `timed_out: true`. Tracked in [issue #3](https://github.com/d4j3y2k/oxtail/issues/3); per-client wake strategy is scoped for v0.7.
+`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.
 
-Mechanics:
+`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.
+
+### Per-client wake routing
+
+v0.7 routes the wake mechanism per `client_type`. Verified 2026-05-13 via spike investigation and falsifying experiment:
+
+- **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`).
+
+- **Unknown** — legacy v0.6 wake (text + Enter, no gap). No implied promise; if a new TUI lands, treat it as unknown until verified.
+
+### Wake strategy override
+
+`OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off` (default `auto`):
+
+- `auto` — per-client routing above.
+- `legacy` — v0.6 behavior for every client (no paste-burst gap, no per-client routing). Escape hatch if auto mode misfires.
+- `off` — wake disabled entirely; ask_peer becomes a pure blocking poll. Response surfaces `wake_status: "disabled"`. Useful as a rollback if a Codex update changes the paste-burst constants and the auto-mode delay no longer covers the window.
+
+### Mechanics
 
 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. Fire a best-effort `tmux send-keys` wake against the peer's pane (see known limitation above): a single literal line `[oxtail] new peer message — run mcp__oxtail__read_my_messages and respond via mcp__oxtail__send_message` followed by `Enter`. In a shell prompt this would flush as a command; in a TUI composer it currently lands as composer text.
+3. Route the wake via `wake_status` resolution (see above). For Claude Code, return immediately. Otherwise fire the wake.
 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 }` 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.
+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.
+
+### Pane staleness
+
+Pane targeting can go stale: `tmux_pane` is cached at server startup, but tmux can reuse pane ids after a pane is killed. v0.7 re-resolves the pane from the peer's `server_pid` at wake-time (via process-tree ancestry), preferring the live pane id over the cached one. If the peer is no longer in any tmux pane (orphaned), oxtail falls back to the registered tmux session name. If both targeting attempts fail, `wake_status` returns `skipped_no_target`.
 
-Constraints:
+### Constraints
 
 - The target peer must have a registered `client.session_id`. Codex peers must call `claim_session` / `register_my_session` first; without that, `ask_peer` returns `error: "peer-has-no-session-id"` rather than guessing.
 - Timeout defaults to 45000ms (conservative under typical MCP-client tool-call abort windows). For longer dialogues, the calling agent chains multiple `ask_peer` calls in one turn rather than configuring a longer single block.
-- Pane targeting can go stale: if `tmux send-keys` fails against the cached pane id (Terminator-style window churn can leave the id stale), oxtail retries against the tmux session name (which targets the currently-active pane). Reaching the right pane is a separate concern from the pane-actually-submitting-the-wake limitation above.
 
 ### Tuning the timeout
 
@@ -213,4 +242,4 @@ If `MCP_TRACE_FILE` is set in the environment, every detection run appends an ND
 
 ## Status
 
-v0.6.0. Adds `ask_peer` on top of v0.5's mailbox transport: an agent can send a message and block server-side until the peer replies. The implementation attempts a `tmux send-keys` wake against the peer's pane — but in practice that wake does not reliably rouse fully-idle TUI peers; `ask_peer` is reliable only when the peer is already in a turn (or enters one on its own inside the timeout). When both sides are mid-turn, the existing PreToolUse hook handles mid-turn delivery cleanly. Codex peers are supported as targets once they've claimed a session. Per-client wake strategy is scoped for v0.7 (issue #3).
+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.

package/dist/registry.js

@@ -116,6 +116,15 @@ export function resolveTmuxPane(env = process.env, pid = process.pid) {
         return env.TMUX_PANE;
     return findTmuxPaneByAncestry(pid, listTmuxPanePids(), listAllPpids());
 }
+// Resolve the tmux pane currently hosting a given server pid by walking the
+// process tree. Unlike resolveTmuxPane(), this does NOT trust env vars — it
+// queries live tmux + ps state. Used by the ask_peer wake path to detect a
+// stale cached tmux_pane: if a peer's pane was killed and its pane_id reused
+// by an unrelated pane, the cached id no longer points at our peer. Returns
+// null if the server pid is no longer in any tmux pane's process tree.
+export function currentPaneForServerPid(serverPid) {
+    return findTmuxPaneByAncestry(serverPid, listTmuxPanePids(), listAllPpids());
+}
 export function buildEntry(client, env = process.env) {
     const tmux_pane = resolveTmuxPane(env);
     return {

package/dist/server.js

@@ -9,7 +9,7 @@ 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 { buildEntry, currentPaneForServerPid, 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
@@ -797,6 +797,32 @@ const ASK_PEER_TIMEOUT_MS = (() => {
 const ASK_PEER_GRACE_MS = 500;
 const ASK_PEER_POLL_MS = 200;
 const ASK_PEER_WAKE_TEXT = "[oxtail] new peer message — run mcp__oxtail__read_my_messages and respond via mcp__oxtail__send_message";
+// Codex's TUI has a paste-burst heuristic at codex-rs/tui/src/bottom_pane/
+// paste_burst.rs (PASTE_BURST_MIN_CHARS=3, PASTE_BURST_CHAR_INTERVAL=8ms,
+// PASTE_ENTER_SUPPRESS_WINDOW=120ms). When `tmux send-keys` blasts the
+// literal-text payload followed immediately by Enter, Codex detects the
+// pattern as a paste and forcibly converts Enter→newline for ~120ms,
+// suppressing the submit. Inserting a delay between the text and the Enter
+// keystrokes lets the suppression window expire so Enter is treated as a
+// real keypress. 500ms is a generous multiple of the documented window for
+// upstream-drift safety — Codex point releases may bump the constant.
+// Verified empirically 2026-05-13 against Codex (gpt-5.5 xhigh).
+const ASK_PEER_CODEX_SUBMIT_DELAY_MS = 500;
+// OXTAIL_ASK_PEER_WAKE_STRATEGY = "auto" | "legacy" | "off"
+//   auto    — per-client routing: Codex gets paste-burst-aware wake (500ms gap
+//             between text and Enter); Claude Code is skipped (no idle hook
+//             surface — verified via Claude Code hook docs); unknown clients
+//             get legacy v0.6 behavior.
+//   legacy  — v0.6 behavior for every client (text + Enter, no gap, no
+//             per-client routing). Escape hatch if auto mode misfires.
+//   off     — wake disabled entirely; ask_peer becomes a blocking poll.
+//             Caller can rely solely on the peer's natural turn cadence.
+const ASK_PEER_WAKE_STRATEGY = (() => {
+    const v = (process.env.OXTAIL_ASK_PEER_WAKE_STRATEGY ?? "auto").toLowerCase();
+    if (v === "auto" || v === "legacy" || v === "off")
+        return v;
+    return "auto";
+})();
 function askPeerDelay(ms, signal) {
     return new Promise((resolve, reject) => {
         if (signal.aborted) {
@@ -815,42 +841,58 @@ function askPeerDelay(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
-// KNOWN ISSUE (tracked in #3, planned for v0.7): this wake does not actually
-// rouse idle TUI peers. Verified 2026-05-13 against Codex CLI — the trailing
-// `tmux send-keys ... Enter` lands as composer-newline rather than submit,
-// leaving the wake text typed-but-not-flushed in Codex's `›` composer. Idle
-// Claude Code peers are also unwoken in practice; the PreToolUse hook only
-// fires inside an existing turn, so an idle Claude at its prompt sees nothing
-// until the user types. ask_peer is therefore effectively async-only against
-// idle peers: replies arrive once the peer enters a turn on its own.
+// Wake routing (v0.7). The wake's job is to nudge an idle peer into a turn so
+// it drains its mailbox. Mechanics differ per client:
+//
+//   Codex — `tmux send-keys -l <text>` followed by `send-keys Enter` would
+//   work, EXCEPT Codex's paste-burst heuristic suppresses Enter for 120ms
+//   after a fast typing burst (codex-rs/tui/src/bottom_pane/paste_burst.rs).
+//   We insert ASK_PEER_CODEX_SUBMIT_DELAY_MS between the text and the Enter
+//   so the suppression window expires. Verified live 2026-05-13.
+//
+//   Claude Code — has no hook event that fires while idle (verified via
+//   Claude Code's documented hook catalog at code.claude.com/docs/en/hooks;
+//   Notification is outbound-only; FileChanged cannot start a turn).
+//   No external surface can rouse an idle Claude Code peer. wakePeer()
+//   short-circuits with skipped_unsupported for this client_type.
+//
+//   Unknown — legacy v0.6 behavior (text + Enter, no gap). No implied
+//   promise; if a new TUI lands and breaks, we treat it as unknown until
+//   verified.
 //
 // Two send-keys calls: the text is interpreted literally (-l) and Enter is
 // parsed as a key event. The -l flag neutralizes any tmux keysequences a
 // malicious peer could plant in its registry entry.
 //
-// Pane targeting can go stale: tmux_pane is cached at server startup (registry
-// resolveTmuxPane), but Terminator-style window churn can move or close the
-// pane after registration. send-keys against a dead pane id errors; if pane
-// targeting fails and a sessionName is also available, retry against it
-// (targets the session's currently-active pane).
-function defaultFireWakeKeystrokes(target) {
+// Pane targeting can go stale: tmux_pane is cached at server startup
+// (registry resolveTmuxPane), but Terminator-style window churn can move or
+// close the pane after registration. send-keys against a dead pane id
+// errors; if pane targeting fails and a sessionName is also available,
+// retry against it (targets the session's currently-active pane).
+async function defaultFireWakeKeystrokes(target, clientType) {
     execFileSync("tmux", ["send-keys", "-t", target, "-l", ASK_PEER_WAKE_TEXT], {
         stdio: ["ignore", "pipe", "pipe"],
     });
+    if (clientType === "codex") {
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, ASK_PEER_CODEX_SUBMIT_DELAY_MS);
+            timer.unref?.();
+        });
+    }
     execFileSync("tmux", ["send-keys", "-t", target, "Enter"], {
         stdio: ["ignore", "pipe", "pipe"],
     });
 }
-// Exported for unit testing the retry path; production callers use askPeerWake
-// which wires defaultFireWakeKeystrokes.
-export function askPeerWakeImpl(pane, sessionName, fire) {
+// Exported for unit testing the retry path; production callers use wakePeer
+// which wires defaultFireWakeKeystrokes via routing.
+export async function askPeerWakeImpl(pane, sessionName, fire) {
     if (!pane && !sessionName) {
         trace("ask_peer_wake_skipped", { reason: "no-pane-or-session" });
         return false;
     }
     const primary = pane ?? sessionName;
     try {
-        fire(primary);
+        await fire(primary);
         trace("ask_peer_wake_fired", { target: primary });
         return true;
     }
@@ -859,7 +901,7 @@ export function askPeerWakeImpl(pane, sessionName, fire) {
     }
     if (pane && sessionName && pane !== sessionName) {
         try {
-            fire(sessionName);
+            await fire(sessionName);
             trace("ask_peer_wake_fired_retry", { target: sessionName });
             return true;
         }
@@ -869,8 +911,55 @@ export function askPeerWakeImpl(pane, sessionName, fire) {
     }
     return false;
 }
-function askPeerWake(pane, sessionName) {
-    return askPeerWakeImpl(pane, sessionName, defaultFireWakeKeystrokes);
+// Route a wake to a peer based on OXTAIL_ASK_PEER_WAKE_STRATEGY and the
+// peer's client_type. Returns the wake_status that should surface in the
+// ask_peer response so callers can distinguish "we tried, no answer" from
+// "we didn't try because the client can't be woken."
+async function wakePeer(peer) {
+    if (ASK_PEER_WAKE_STRATEGY === "off") {
+        trace("ask_peer_wake_skipped", { reason: "strategy-off" });
+        return "disabled";
+    }
+    const clientType = peer.client.type;
+    if (ASK_PEER_WAKE_STRATEGY === "auto" && clientType === "claude-code") {
+        trace("ask_peer_wake_skipped", { reason: "client-unsupported", client_type: clientType });
+        return "skipped_unsupported";
+    }
+    if (!peer.tmux_pane && !peer.tmux_session) {
+        return "skipped_no_target";
+    }
+    // Race-fix: tmux_pane is cached at registration but pane ids can be reused
+    // by tmux after a pane is killed. If we send-keys against a reused id we
+    // wake the wrong shell. When the peer registered WITH a cached pane,
+    // re-resolve from its server_pid at wake-time and prefer the live value.
+    // If the peer registered without a pane (no TMUX_PANE in env, no ancestry
+    // match), skip the re-resolution entirely — fishing for a pane based on
+    // server_pid alone is unsafe (server_pid may not even still be alive, and
+    // in tests it can coincide with the test runner's process tree).
+    const livePane = peer.tmux_pane
+        ? currentPaneForServerPid(peer.server_pid)
+        : null;
+    if (peer.tmux_pane && livePane && livePane !== peer.tmux_pane) {
+        trace("ask_peer_wake_pane_refreshed", {
+            cached: peer.tmux_pane,
+            live: livePane,
+            server_pid: peer.server_pid,
+        });
+    }
+    else if (peer.tmux_pane && !livePane) {
+        trace("ask_peer_wake_pane_orphaned", {
+            cached: peer.tmux_pane,
+            server_pid: peer.server_pid,
+        });
+    }
+    const effectivePane = livePane ?? peer.tmux_pane;
+    // Legacy mode bypasses per-client routing: every wake is the v0.6 sequence
+    // (no inter-keystroke delay). Cast to "unknown" so defaultFireWakeKeystrokes
+    // skips the Codex delay branch.
+    const fireType = ASK_PEER_WAKE_STRATEGY === "legacy" ? "unknown" : clientType;
+    const fire = (target) => defaultFireWakeKeystrokes(target, fireType);
+    const ok = await askPeerWakeImpl(effectivePane, peer.tmux_session, fire);
+    return ok ? "fired" : "skipped_no_target";
 }
 // Poll my mailbox at ASK_PEER_POLL_MS until a matching reply lands or the
 // deadline elapses. Each tick checks mtime first and only acquires the
@@ -907,9 +996,11 @@ server.registerTool("ask_peer", {
     description: [
         "Enqueue a message to a peer and block until they reply (or timeout).",
         "Use this when you want a back-and-forth with another agent in the same project root, rather than fire-and-forget like send_message.",
-        "KNOWN LIMITATION (v0.6, tracked in issue #3, planned v0.7): the tmux send-keys wake does NOT reliably rouse idle TUI peers. Codex composer pollution verified 2026-05-13 — wake text lands as typed-but-not-submitted input. Idle Claude Code peers are also unwoken in practice. ask_peer reliably returns a reply only if the target enters a turn on its own (user types into it, or another tool call fires its PreToolUse hook) within the timeout. Against a fully idle peer with no human at the keyboard, expect timeout.",
-        "Behavior: enqueues the body to the target's mailbox, waits ~500ms for a hook-delivered reply, fires a best-effort tmux send-keys wake (see limitation above), then polls this session's mailbox at 200ms for a reply from the target.",
-        "Returns when the target sends a message back (via send_message) whose from_session_id matches them, or when the timeout elapses (returns reply: null, timed_out: true). Timeout defaults to 45000ms; user-tunable via OXTAIL_ASK_PEER_TIMEOUT_MS env var.",
+        "Wake behavior (v0.7) varies per client_type. Codex peers are woken via paste-burst-aware tmux send-keys (literal text + 500ms gap + Enter) so the composer submits. Claude Code peers cannot be woken externally — Claude Code's hook surface has no idle event (verified against the documented hook catalog), so ask_peer fails fast for Claude Code targets and returns wake_status: \"skipped_unsupported\" rather than burning the timeout. Unknown clients use legacy send-keys wake.",
+        "Response includes a wake_status field: \"fired\" (wake attempted or reply received during grace window), \"skipped_unsupported\" (target client cannot be woken — fail-fast, no poll), \"skipped_no_target\" (no tmux pane or session resolved for target), \"disabled\" (OXTAIL_ASK_PEER_WAKE_STRATEGY=off).",
+        "Behavior: enqueues the body to the target's mailbox, waits ~500ms for a hook-delivered reply (rare: peer was mid-turn, hook delivered as additionalContext), fires the per-client wake, then polls this session's mailbox at 200ms for a reply from the target. Fail-fast for skipped_unsupported skips polling entirely; the message is still enqueued and will be delivered the next time the peer enters a turn.",
+        "Returns when the target sends a message back (via send_message) whose from_session_id matches them, or when the timeout elapses (returns reply: null, timed_out: true). timed_out is false on fail-fast (we didn't actually poll). Timeout defaults to 45000ms; user-tunable via OXTAIL_ASK_PEER_TIMEOUT_MS env var.",
+        "Wake strategy can be overridden via OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off (default auto). legacy = v0.6 behavior for every client (no gap, no per-client routing). off = no wake fired; ask_peer becomes a pure blocking poll until the peer naturally enters a turn or timeout.",
         "Target must have a registered client.session_id (Codex peers must call register_my_session first).",
         "Late replies that arrive after timeout are delivered normally via read_my_messages / the PreToolUse hook.",
         "Body framing: peers see the body verbatim. Include a short assignment-style framing (objective, what you want them to do) so they treat it as a delegation, not chat.",
@@ -984,6 +1075,7 @@ server.registerTool("ask_peer", {
     });
     let reply = null;
     let aborted = false;
+    let wakeStatus = "skipped_no_target";
     try {
         // Grace window: rare hook-delivery path. If peer was mid-tool-call when
         // our outbound arrived, their hook delivered it as additionalContext and
@@ -991,9 +1083,24 @@ server.registerTool("ask_peer", {
         await askPeerDelay(ASK_PEER_GRACE_MS, extra.signal);
         reply = mailbox.drainMatchingSession(entry.server_pid, expectedSessionId);
         if (!reply) {
-            // Common path: peer was idle; fire wake + poll.
-            askPeerWake(peer.tmux_pane, peer.tmux_session);
-            reply = await askPeerPoll(entry.server_pid, expectedSessionId, deadlineMs, extra.signal);
+            // Common path: peer was idle. Route the wake per client_type.
+            wakeStatus = await wakePeer(peer);
+            if (wakeStatus === "skipped_unsupported") {
+                // Claude Code idle has no external wake surface — polling would just
+                // burn the caller's wall-clock budget for no reason. Return fast so
+                // the caller can fall back to send_message + read_my_messages, or
+                // wait until the peer is observed mid-turn via list_project_sessions.
+                // The outbound has been enqueued; it'll be delivered next time the
+                // peer enters a turn (via PreToolUse hook or explicit read_my_messages).
+            }
+            else {
+                reply = await askPeerPoll(entry.server_pid, expectedSessionId, deadlineMs, extra.signal);
+            }
+        }
+        else {
+            // Reply arrived during grace window — peer was already mid-turn and
+            // the hook delivered the outbound to it as additionalContext.
+            wakeStatus = "fired";
         }
     }
     catch (e) {
@@ -1021,11 +1128,18 @@ server.registerTool("ask_peer", {
         // Throw to signal the framework that the request did not complete.
         throw new Error("ask_peer aborted by client");
     }
+    // timed_out is reserved for "we waited and got nothing" — i.e. we actually
+    // polled to the deadline. A fail-fast for an unwakeable client (no poll
+    // attempted) is NOT a timeout; the message has been enqueued and will be
+    // delivered when the peer next enters a turn.
+    const polled = wakeStatus !== "skipped_unsupported";
+    const timedOut = polled && reply === null;
     trace("ask_peer_end", {
         target_session_id: expectedSessionId,
         message_id: msg.id,
         duration_ms: Date.now() - startedAt,
-        timed_out: reply === null,
+        wake_status: wakeStatus,
+        timed_out: timedOut,
     });
     return {
         content: [
@@ -1035,6 +1149,7 @@ server.registerTool("ask_peer", {
                     schema_version: 1,
                     ok: true,
                     message_id: msg.id,
+                    wake_status: wakeStatus,
                     reply: reply
                         ? {
                             id: reply.id,
@@ -1043,7 +1158,7 @@ server.registerTool("ask_peer", {
                             from_session_id: reply.from_session_id ?? null,
                         }
                         : null,
-                    timed_out: reply === null,
+                    timed_out: timedOut,
                 }, null, 2),
             },
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxtail",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "Coordination layer for parallel AI coding agent sessions, exposed over MCP.",