oxtail 0.10.1 → 0.10.2

package/dist/server.js

@@ -1052,6 +1052,19 @@ const ASK_PEER_TIMEOUT_MS = (() => {
 })();
 const ASK_PEER_GRACE_MS = 500;
 const ASK_PEER_POLL_MS = 200;
+// Ceiling for the per-call `timeout_ms` override. A server-side wait longer
+// than the CLIENT's own tool-call abort window makes the client kill the
+// tools/call (a hard error: "tool call failed after Ns") instead of letting
+// ask_peer return its graceful {reply:null, timed_out:true}. Observed: Codex
+// aborts around 120s. 100s stays safely under common client limits. Raise via
+// OXTAIL_ASK_PEER_MAX_TIMEOUT_MS only if your client tolerates longer waits.
+const ASK_PEER_MAX_TIMEOUT_MS = (() => {
+    const env = process.env.OXTAIL_ASK_PEER_MAX_TIMEOUT_MS;
+    if (!env)
+        return 100_000;
+    const n = Number(env);
+    return Number.isFinite(n) && n > 0 ? n : 100_000;
+})();
 // Typed into the peer's TUI as a synthetic prompt, so it lands in their context
 // once per wake — kept terse. For HOOKED Claude Code the delivered envelope
 // carries the full reply instruction, but Codex and hookless Claude peers only
@@ -1301,7 +1314,7 @@ function drainAskPeerReply(my_pid, from_session_id, request_id, require_reply_to
 server.registerTool("ask_peer", {
     description: [
         "Delegate-and-wait: enqueue a message to a peer in the same project root, wake them, and block until they reply (via send_message) or the timeout elapses. Use this for back-and-forth; use send_message for fire-and-forget.",
-        "Wakes the peer via per-client tmux send-keys (Codex gets a paste-burst-aware gap, Claude Code doesn't), then polls for a reply. For reply_to-capable peers, only from_session_id + reply_to == request_id satisfies the wait; legacy peers fall back to best-effort from_session_id matching and the response reports correlation:\"uncorrelated\". Response carries wake_status: \"fired\" | \"skipped_no_target\" | \"disabled\" (skipped_unsupported is reserved). Returns reply: null, timed_out: true on timeout (default 45000ms, override per call with timeout_ms, or set OXTAIL_ASK_PEER_TIMEOUT_MS at startup). Late replies still arrive via read_my_messages / the hook.",
+        "Wakes the peer via per-client tmux send-keys (Codex gets a paste-burst-aware gap, Claude Code doesn't), then polls for a reply. For reply_to-capable peers, only from_session_id + reply_to == request_id satisfies the wait; legacy peers fall back to best-effort from_session_id matching and the response reports correlation:\"uncorrelated\". Response carries wake_status: \"fired\" | \"skipped_no_target\" | \"disabled\" (skipped_unsupported is reserved). Returns reply: null, timed_out: true on timeout (default 45000ms, override per call with timeout_ms, or set OXTAIL_ASK_PEER_TIMEOUT_MS at startup). timeout_ms is clamped to a safe ceiling (default 100000ms, env OXTAIL_ASK_PEER_MAX_TIMEOUT_MS) so the wait can't outlast the client's tool-call abort window — exceeding it makes the client hard-fail the call instead of returning graceful timed_out; the response reports timeout_clamped_from_ms when clamped. Late replies still arrive via read_my_messages / the hook.",
         "Target must have a registered client.session_id (Codex peers call claim_session first). Body is verbatim — frame it as an assignment (objective + requested action) so it reads as delegation, not chat. Wake overridable via OXTAIL_ASK_PEER_WAKE_STRATEGY=auto|legacy|off.",
     ].join(" "),
     inputSchema: {
@@ -1322,7 +1335,10 @@ server.registerTool("ask_peer", {
             .positive()
             .max(300_000)
             .optional()
-            .describe("Optional per-call timeout in milliseconds."),
+            .describe("Optional per-call timeout in milliseconds. Clamped to a safe ceiling " +
+            "(default 100000ms, env OXTAIL_ASK_PEER_MAX_TIMEOUT_MS) so the wait can't " +
+            "outlast the client's tool-call abort window; the response reports " +
+            "timeout_clamped_from_ms when clamped."),
     },
 }, async ({ target, body, timeout_ms }, extra) => {
     const resolved = resolveTarget(target, entry);
@@ -1351,7 +1367,12 @@ server.registerTool("ask_peer", {
         request_id: requestId,
     });
     const startedAt = Date.now();
-    const effectiveTimeoutMs = timeout_ms ?? ASK_PEER_TIMEOUT_MS;
+    const requestedTimeoutMs = timeout_ms ?? ASK_PEER_TIMEOUT_MS;
+    // Clamp below the client tool-call abort window: a longer wait would make
+    // the client hard-fail the tools/call instead of receiving our graceful
+    // timed_out response. Surface the clamp so the caller isn't surprised.
+    const effectiveTimeoutMs = Math.min(requestedTimeoutMs, ASK_PEER_MAX_TIMEOUT_MS);
+    const timeoutClamped = effectiveTimeoutMs < requestedTimeoutMs;
     const deadlineMs = startedAt + effectiveTimeoutMs;
     trace("ask_peer_start", {
         target_session_id: expectedSessionId,
@@ -1450,25 +1471,39 @@ server.registerTool("ask_peer", {
             : null,
         correlation: reply ? (requireReplyTo ? "correlated" : "uncorrelated") : "none",
         timeout_ms: effectiveTimeoutMs,
+        ...(timeoutClamped ? { timeout_clamped_from_ms: requestedTimeoutMs } : {}),
         timed_out: timedOut,
     });
 });
-// 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() {
+// Hook-install hint, emitted once per server startup. Warns in two cases:
+//   - absent: no `_oxtailHook` marker → hooks never installed.
+//   - stale:  marker present but an installed hook's hash drifted from what
+//             this package version ships (i.e. the user upgraded oxtail but
+//             never re-ran install-hook, so the OLD script keeps running).
+// The stale case is the one that bit v0.10.1: a present-but-outdated
+// pretooluse.sh silently strips request_id and breaks correlated ask/reply,
+// and the old presence-only check never noticed. Stderr surfacing in Claude
+// Code is a soft assumption; a missed hint just degrades to polling.
+async function maybeHookHint() {
     if (entry.client.type !== "claude-code")
         return;
     try {
-        const settings = readFileSync(join(homedir(), ".claude", "settings.json"), "utf8");
-        if (settings.includes("_oxtailHook"))
-            return;
+        const url = new URL("../scripts/hook-constants.mjs", import.meta.url).href;
+        const { assessHookFreshness } = (await import(url));
+        const fresh = assessHookFreshness();
+        if (fresh.status === "absent") {
+            process.stderr.write("[oxtail] PreToolUse hook not installed — run `npx oxtail install-hook` to enable mid-turn peer messaging.\n");
+        }
+        else if (fresh.status === "stale") {
+            process.stderr.write(`[oxtail] installed hooks are out of date (${fresh.driftedHooks.join(", ")} drifted from this version) — ` +
+                "run `npx oxtail install-hook` to upgrade. A stale PreToolUse hook silently breaks correlated " +
+                "ask/reply by not surfacing request_id to the receiving peer.\n");
+        }
+        // "ok" / "unknown" → stay silent.
     }
     catch {
-        // settings file missing is itself a signal the hook isn't installed
+        // Best-effort hint; never block or crash startup on a freshness-check error.
     }
-    process.stderr.write("[oxtail] PreToolUse hook not installed — run `npx oxtail install-hook` to enable mid-turn peer messaging.\n");
 }
 // Importing server.ts (e.g. from a test that needs an exported helper) used
 // to await server.connect(transport) at module load — which never resolves
@@ -1479,5 +1514,5 @@ const invokedDirectly = typeof process.argv[1] === "string" &&
 if (invokedDirectly) {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    maybeHookHint();
+    await maybeHookHint();
 }

package/package.json

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

package/scripts/check-hook-version.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// CI guard: any change to a shipped hook asset (assets/*.sh) MUST bump
+// HOOK_MARKER_VERSION in scripts/hook-constants.mjs. Without the bump, an asset
+// change ships silently and users who upgraded oxtail keep running the OLD hook
+// (nothing re-runs install-hook on upgrade). That is exactly the bug that broke
+// v0.10.1's correlated ask/reply on the receive side: pretooluse.sh gained
+// request_id rendering but the marker version stayed put, so existing installs
+// never refreshed and silently stripped request_id.
+//
+// Usage: node scripts/check-hook-version.mjs [baseRef]
+//   baseRef defaults to $GITHUB_BASE_SHA, then origin/main.
+//
+// Deliberately dependency-free (only node:child_process + node:fs) so CI can
+// run it without `npm ci`. Reads both versions by regex rather than importing
+// hook-constants.mjs (which now pulls jsonc-parser).
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+function git(args) {
+  return execFileSync("git", args, { encoding: "utf8" }).trim();
+}
+
+function parseVersion(text) {
+  const m = text.match(/HOOK_MARKER_VERSION\s*=\s*(\d+)/);
+  return m ? Number(m[1]) : null;
+}
+
+const base = process.argv[2] || process.env.GITHUB_BASE_SHA || "origin/main";
+const HOOK_ASSET_RE = /^assets\/.*\.sh$/;
+
+let changed;
+try {
+  changed = git(["diff", "--name-only", `${base}...HEAD`]).split("\n").filter(Boolean);
+} catch (e) {
+  const msg = (e && e.message ? String(e.message).split("\n")[0] : String(e));
+  console.warn(
+    `[check-hook-version] could not diff against base "${base}" (${msg}); skipping guard. ` +
+      "Ensure the base ref is fetched (actions/checkout fetch-depth: 0).",
+  );
+  process.exit(0);
+}
+
+const changedAssets = changed.filter((f) => HOOK_ASSET_RE.test(f));
+if (changedAssets.length === 0) {
+  console.log("[check-hook-version] no hook asset changes — OK.");
+  process.exit(0);
+}
+
+const headVersion = parseVersion(readFileSync("scripts/hook-constants.mjs", "utf8"));
+let baseVersion = null;
+try {
+  baseVersion = parseVersion(git(["show", `${base}:scripts/hook-constants.mjs`]));
+} catch {
+  baseVersion = null;
+}
+
+if (headVersion == null || baseVersion == null) {
+  console.error(
+    "[check-hook-version] hook asset(s) changed but HOOK_MARKER_VERSION could not be read:\n  " +
+      changedAssets.join("\n  ") +
+      `\n(head=${headVersion}, base=${baseVersion}). Verify scripts/hook-constants.mjs and bump the version.`,
+  );
+  process.exit(1);
+}
+
+if (headVersion > baseVersion) {
+  console.log(
+    `[check-hook-version] OK — ${changedAssets.length} hook asset(s) changed and ` +
+      `HOOK_MARKER_VERSION bumped ${baseVersion} → ${headVersion}.`,
+  );
+  process.exit(0);
+}
+
+console.error(
+  "[check-hook-version] FAIL — these hook asset(s) changed:\n  " +
+    changedAssets.join("\n  ") +
+    `\nbut HOOK_MARKER_VERSION did not increase (base ${baseVersion}, head ${headVersion}).\n` +
+    "Bump HOOK_MARKER_VERSION in scripts/hook-constants.mjs so existing installs are forced to " +
+    "re-run `npx oxtail install-hook`; otherwise upgraded users silently keep the old hook.",
+);
+process.exit(1);

package/scripts/hook-constants.mjs

@@ -2,8 +2,11 @@
 // Tiny on purpose — only the things both scripts genuinely need.
 
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseJsonc } from "jsonc-parser";
 
 export const SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
 export const HOOK_MARKER_KEY = "_oxtailHook";
@@ -11,7 +14,14 @@ export const HOOK_MARKER_KEY = "_oxtailHook";
 // managed hooks) on the next `npx oxtail install-hook`.
 //   v2: added the Stop hook alongside PreToolUse.
 //   v3: added the UserPromptSubmit hook (busy/idle activity for wake-routing).
-export const HOOK_MARKER_VERSION = 3;
+//   v4: pretooluse renders request_id/reply_to/origin + body-budget truncation
+//       (v0.10.x correlated ask/reply). A stale pre-v4 pretooluse.sh silently
+//       breaks Codex→Claude correlation by stripping request_id from the
+//       delivered envelope, so the receiver can't reply_to=request_id.
+// INVARIANT: any change to an assets/*.sh script MUST bump this version, so
+// existing installs are forced to re-install. scripts/check-hook-version.mjs
+// enforces this in CI.
+export const HOOK_MARKER_VERSION = 4;
 
 const HOOKS_DIR = path.join(os.homedir(), ".oxtail", "hooks");
 
@@ -55,3 +65,77 @@ export const HOOK_COMMAND = MANAGED_HOOKS[0].command;
 export function scriptHash(text) {
   return createHash("sha256").update(text).digest("hex").slice(0, 16);
 }
+
+// Directory holding the shipped hook scripts, resolved relative to this module
+// so it works both from src (dev/tests) and dist (published) — scripts/ and
+// assets/ ship side by side in the npm tarball.
+const ASSETS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "assets");
+
+// Hash of each shipped hook asset as it exists in THIS install of the package.
+// Compared against the marker's recorded hashes to detect a stale install.
+// A null entry means the asset couldn't be read (skip it rather than alarm).
+export function shippedHookHashes() {
+  const hashes = {};
+  for (const h of MANAGED_HOOKS) {
+    try {
+      hashes[h.id] = scriptHash(readFileSync(path.join(ASSETS_DIR, h.asset), "utf8"));
+    } catch {
+      hashes[h.id] = null;
+    }
+  }
+  return hashes;
+}
+
+// Assess whether the installed oxtail hooks match what this package version
+// ships. The flagship failure mode this guards: a package upgrade changes a
+// hook asset, but nothing re-runs install-hook, so the OLD script keeps running
+// (e.g. v0.10.1's pretooluse.sh added request_id rendering; pre-v4 installs
+// silently stripped it and broke correlated ask/reply). install-hook's
+// presence check alone never noticed — a present-but-stale marker looked fine.
+//
+// Never throws; defaults to a silent "unknown"/"ok" on any read/parse failure
+// so server startup never nags spuriously. Returns:
+//   status: "ok"      — marker present and every shipped hash matches the marker
+//           "absent"  — no _oxtailHook marker (hooks never installed)
+//           "stale"   — marker present but one or more script hashes drifted
+//           "unknown" — settings unreadable/unparseable; caller should stay quiet
+//   driftedHooks      — ids whose installed hash != shipped hash
+//   versionMismatch   — marker.version != HOOK_MARKER_VERSION (informational)
+export function assessHookFreshness(settingsPath = SETTINGS_PATH) {
+  let text;
+  try {
+    text = readFileSync(settingsPath, "utf8");
+  } catch {
+    // No settings file == hooks were never installed.
+    return { status: "absent", driftedHooks: [], versionMismatch: false };
+  }
+  // Cheap pre-check mirrors the original presence test.
+  if (!text.includes(HOOK_MARKER_KEY)) {
+    return { status: "absent", driftedHooks: [], versionMismatch: false };
+  }
+  let parsed;
+  try {
+    parsed = parseJsonc(text);
+  } catch {
+    return { status: "unknown", driftedHooks: [], versionMismatch: false };
+  }
+  const marker = parsed && typeof parsed === "object" ? parsed[HOOK_MARKER_KEY] : null;
+  if (!marker || typeof marker !== "object") {
+    return { status: "absent", driftedHooks: [], versionMismatch: false };
+  }
+  const installedHashes =
+    marker.hashes && typeof marker.hashes === "object" ? marker.hashes : {};
+  const shipped = shippedHookHashes();
+  const driftedHooks = [];
+  for (const h of MANAGED_HOOKS) {
+    const want = shipped[h.id];
+    if (want == null) continue; // can't compare; don't false-alarm
+    if (installedHashes[h.id] !== want) driftedHooks.push(h.id);
+  }
+  const versionMismatch = marker.version !== HOOK_MARKER_VERSION;
+  // Trigger "stale" on actual script drift only — a version-only mismatch with
+  // identical content is benign bookkeeping (install-hook will refresh the
+  // marker) and not worth a startup warning.
+  const status = driftedHooks.length > 0 ? "stale" : "ok";
+  return { status, driftedHooks, versionMismatch };
+}