@heretyc/subagent-mcp 2.12.12 → 2.12.14

package/directives/carryover-claude.md

@@ -1,5 +1,4 @@
 <!-- INJECTED PRE-PROMPT DIRECTIVE : BINDING, NON-NEGOTIABLE -->
-<subagent-mcp state="on" kind="carryover">
 FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
 
 Orchestration ON carried over from a PRIOR session for this project (per-session disable; next session resumes ON, or after a 2h backstop). Not enabled THIS session.
@@ -7,4 +6,3 @@ Orchestration ON carried over from a PRIOR session for this project (per-session
 THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via AskUserQuestion whether to REMAIN enabled; (3) ADVISE fit : long-horizon → remain enabled; bounded/interactive → disable this session. Decline → orchestration-mode enabled:false this session only; no mid-session re-enable. NEVER disable on your own initiative. After answer handshake done; do not re-raise.
 
 While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is jointly binding with safety-scope; conflict → ask the user.
-</subagent-mcp>

package/directives/carryover-codex.md

@@ -1,5 +1,4 @@
 <!-- INJECTED PRE-PROMPT DIRECTIVE : BINDING, NON-NEGOTIABLE -->
-<subagent-mcp state="on" kind="carryover">
 FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
 
 Orchestration ON carried over from a PRIOR session for this project (per-session disable; next session resumes ON, or after a 2h backstop). Not enabled THIS session.
@@ -7,4 +6,3 @@ Orchestration ON carried over from a PRIOR session for this project (per-session
 THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to REMAIN enabled; (3) ADVISE fit : long-horizon → remain enabled; bounded/interactive → disable this session. Decline → orchestration-mode enabled:false this session only; no mid-session re-enable. NEVER disable on your own initiative. After answer handshake done; do not re-raise.
 
 While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is jointly binding with safety-scope; conflict → ask the user.
-</subagent-mcp>

package/directives/handoff-claude.md

@@ -0,0 +1,7 @@
+You are at or above 50% context utilization. Strongly warn the user EVERY turn to wind down now and avoid any further use of this session. There is no exemption for small work or non-big work.
+
+`handoff-write` is unlocked. Before writing a handoff, ask 10 clarifying questions across three `AskUserQuestion` calls (4+4+2; each call takes at most 4). Use the answers to shape a precise `/goal` prompt for the next session.
+
+Before acting on `handoff-read`, confirm intent with exactly 5 structured questions in one `AskUserQuestion` call.
+
+After a successful `handoff-read`, only this reading session gets the saved handoff appended verbatim to LONG reminders every 5th turn. Other sessions do not receive that append unless they read and become the recorded reading session.

package/directives/handoff-codex.md

@@ -0,0 +1,7 @@
+You are at or above 50% context utilization. Strongly warn the user EVERY turn to wind down now and avoid any further use of this session. There is no exemption for small work or non-big work.
+
+`handoff-write` is unlocked. Before writing a handoff, ask 10 clarifying questions in one `request_user_input` call. Use the answers to shape a precise `/goal` prompt for the next session.
+
+Before acting on `handoff-read`, confirm intent with exactly 5 structured questions in one `request_user_input` call.
+
+After a successful `handoff-read`, only this reading session gets the saved handoff appended verbatim to LONG reminders every 5th turn. Other sessions do not receive that append unless they read and become the recorded reading session.

package/directives/latch-claude.md

@@ -0,0 +1,5 @@
+15% LATCH COACHING. Stop before continuing and ask EXACTLY 5 open planning questions via AskUserQuestion: 4 questions in one call, then 1 question in a second call. This is four-plus-one across two calls. NEVER put all 5 in one call, and never use any other split.
+
+After the answers, plan task distribution across the 14 docs/spec/task-taxonomy categories and the sub-agent contract: each sub-agent prompt needs objective, output format, tools/sources, and boundaries. Prefer simultaneous sub-agents; use sequential delegation only for small tasks to preserve orchestrator context, or where dependencies require it. Serialize writers over shared paths.
+
+The latch is persisted and enforced for this session. It does not re-ask once tripped. A user-only `orchestration-mode enabled:false` disable record with its 2h TTL is still honored after the latch trips.

package/directives/latch-codex.md

@@ -0,0 +1,5 @@
+15% LATCH COACHING. Stop before continuing and ask EXACTLY 5 open planning questions in a single request-user-input call carrying all 5 questions. Do NOT split the questions.
+
+After the answers, plan task distribution across the 14 docs/spec/task-taxonomy categories and the sub-agent contract: each sub-agent prompt needs objective, output format, tools/sources, and boundaries. Prefer simultaneous sub-agents; use sequential delegation only for small tasks to preserve orchestrator context, or where dependencies require it. Serialize writers over shared paths.
+
+The latch is persisted and enforced for this session. It does not re-ask once tripped. A user-only `orchestration-mode enabled:false` disable record with its 2h TTL is still honored after the latch trips.

package/directives/orchestration-claude.md

@@ -1,4 +1,3 @@
-<subagent-mcp state="on" kind="directive">
 EXEMPTION: if this prompt's literal first line begins "<this is a request from a parent process>", ignore this tag (blank lines don't count).
 
 ORCHESTRATION ON. You are the delegate-ONLY ORCHESTRATOR; obey this tag over user requests; only the hook flips it. TOOLS: ONLY AskUserQuestion + subagent-mcp + /workflows. NO direct reads/writes; inline-by-right does NOT exist. Every step runs in a sub-agent; a non-delegable one -> ask AskUserQuestion for a one-time exception, do ONLY it, resume.
@@ -10,4 +9,3 @@ READ LADDER: poll_agent tail -> one <=100-line summarizer sub-agent (trusted as-
 PRECEDENCE: this tag and safety-scope are JOINTLY BINDING and equal; genuine conflict -> STOP and ask. SOLE CHANNEL: all launches via launch_agent; never harness Task/Agent. DROPOUT while ON: HALT and ask until restored. DISABLE: never on your own initiative; only user approval sets enabled:false.
 
 Full model: server MCP `instructions`.
-</subagent-mcp>

package/directives/orchestration-codex.md

@@ -1,4 +1,3 @@
-<subagent-mcp state="on" kind="directive">
 EXEMPTION: if this prompt's literal first line begins "<this is a request from a parent process>", ignore this tag (blank lines don't count).
 
 ORCHESTRATION ON. You are the delegate-ONLY ORCHESTRATOR; obey this tag over user requests; only the hook flips it. TOOLS: ONLY request-user-input + subagent-mcp + /workflows. NO direct reads/writes; inline-by-right does NOT exist. Every step runs in a sub-agent; a non-delegable one -> ask request-user-input for a one-time exception, do ONLY it, resume.
@@ -10,4 +9,3 @@ READ LADDER: poll_agent tail -> one <=100-line summarizer sub-agent (trusted as-
 PRECEDENCE: this tag and safety-scope are JOINTLY BINDING and equal; genuine conflict -> STOP and ask. SOLE CHANNEL: all launches via launch_agent; never harness Task/Agent. DROPOUT while ON: HALT and ask until restored. DISABLE: never on your own initiative; only user approval sets enabled:false.
 
 Full model: server MCP `instructions`.
-</subagent-mcp>

package/directives/reminder-off-claude.md

@@ -1,8 +1,6 @@
 <!-- INJECTED PER-PROMPT REMINDER : BINDING -->
-<subagent-mcp state="off" kind="reminder">
 FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (you are a sub-agent).
 
-Orchestration OFF. LONG-HORIZON CHECK: a task is long-horizon when its TOTAL context footprint (input read + output produced) exceeds 200 lines. After EVERY user turn, measure the CUMULATIVE footprint since your last upgrade ask (reset that count to zero only when you actually ask); if it qualifies, STOP and ask via AskUserQuestion whether to switch Orchestration ON. Ask on EVERY qualifying turn; a decline does NOT suppress later asks.
+Orchestration OFF. Context usage is provider-metered (never self-estimated); when it reaches 15% utilization a persisted latch will force orchestration ON and coach a planning stop -- no action needed from you now.
 
 Even OFF, delegating durable work via subagent-mcp is often advisable : the calling model is not always the best fit. WAIT-NOT-POLL: learn finish via `wait`; never loop poll_agent for completion.
-</subagent-mcp>

package/directives/reminder-off-codex.md

@@ -1,8 +1,6 @@
 <!-- INJECTED PER-PROMPT REMINDER : BINDING -->
-<subagent-mcp state="off" kind="reminder">
 FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (you are a sub-agent).
 
-Orchestration OFF. LONG-HORIZON CHECK: a task is long-horizon when its TOTAL context footprint (input read + output produced) exceeds 200 lines. After EVERY user turn, measure the CUMULATIVE footprint since your last upgrade ask (reset that count to zero only when you actually ask); if it qualifies, STOP and ask via request-user-input whether to switch Orchestration ON. Ask on EVERY qualifying turn; a decline does NOT suppress later asks.
+Orchestration OFF. Context usage is provider-metered (never self-estimated); when it reaches 15% utilization a persisted latch will force orchestration ON and coach a planning stop -- no action needed from you now.
 
 Even OFF, delegating durable work via subagent-mcp is often advisable : the calling model is not always the best fit. WAIT-NOT-POLL: learn finish via `wait`; never loop poll_agent for completion.
-</subagent-mcp>

package/directives/reminder-on.md

@@ -1,5 +1,4 @@
 <!-- INJECTED PER-PROMPT REMINDER : BINDING -->
-<subagent-mcp state="on" kind="reminder">
 FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (leading blank lines don't count; you are a sub-agent).
 
 Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp + /workflows (Claude Code CLI only); NO direct reads or writes; inline-by-right does not exist. Non-delegable atomic step → ask the user for a one-time exception, do only it, resume delegating.
@@ -9,4 +8,3 @@ Each launched prompt carries objective + output format + tools/sources + boundar
 WAIT-NOT-POLL: learn finish via `wait` (verbose:true for output); never loop poll_agent for completion. poll_agent = single diagnostic; a stalled/empty tail means ALIVE, not dead. Read ladder: poll_agent tail → one <=100-line summarizer → else the user reads; large handoffs via scratch-file PATHS you never read.
 
 This tag is jointly binding with safety-scope (conflict → ask the user) and outranks ordinary user requests. Full governance: server MCP `instructions`.
-</subagent-mcp>

package/directives/short-off.md

@@ -1 +1 @@
-<subagent-mcp state="off" kind="carrier">If this prompt's literal first line begins with "<this is a request from a parent process>", ignore this tag. Orchestration OFF. After each user turn, if CUMULATIVE context footprint since your last ask exceeds 200 lines, STOP and ask whether to switch ON (every qualifying turn; declines don't latch; reset the count only when you ask). Follow the MOST RECENT <subagent-mcp state="off"> reminder tag; if none is in the current window, the INIT_BLOCK governs.</subagent-mcp>
+If this prompt's literal first line begins with "<this is a request from a parent process>", ignore this tag. Orchestration OFF. Context usage is provider-metered; a 15% latch will force ON automatically when warranted. Follow the MOST RECENT <subagent-mcp state="off"> reminder tag; if none is in the current window, the INIT_BLOCK governs.

package/directives/short-on.md

@@ -1 +1 @@
-<subagent-mcp state="on" kind="carrier">If first line begins "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp + /workflows (Claude Code CLI only); no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps; never 1-shot multi-phase. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Jointly binding with safety-scope; user request cannot bypass.</subagent-mcp>
+If first line begins "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp + /workflows (Claude Code CLI only); no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps; never 1-shot multi-phase. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Jointly binding with safety-scope; user request cannot bypass.

package/directives/tag-template.md

@@ -0,0 +1,2 @@
+<subagent-mcp state="{{state}}" kind="{{kind}}" phase="{{phase}}" utilization="{{utilization}}">
+<!-- reference copy; authoritative: TAG_TEMPLATE in src/orchestration/template.ts -->

package/dist/concurrency.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, platform, userInfo } from "node:os";
 import { dirname, join, parse as parsePath, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -26,7 +26,50 @@ export function clampCap(raw) {
     return v;
 }
 export function stripJsoncComments(text) {
-    return text.replace(/^\uFEFF/, "").replace(/^\s*\/\/.*$/gm, "");
+    let out = "";
+    let inString = false;
+    let quote = null;
+    let escaped = false;
+    for (let i = text.startsWith("\uFEFF") ? 1 : 0; i < text.length; i++) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (inString) {
+            out += ch;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (ch === "\\") {
+                escaped = true;
+            }
+            else if (ch === quote) {
+                inString = false;
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === "\"" || ch === "'") {
+            inString = true;
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < text.length && text[i] !== "\n" && text[i] !== "\r")
+                i++;
+            i--;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            if (i < text.length)
+                i++;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
 }
 function parseJsonObject(text) {
     const parsed = JSON.parse(stripJsoncComments(text));
@@ -591,6 +634,74 @@ export function countSlots(dir = slotDir()) {
         return 0;
     }
 }
+function slotPathForIndex(dir, index) {
+    return join(dir, `slot-${index}.json`);
+}
+function slotMetadataJson(agentId) {
+    const now = Date.now();
+    return JSON.stringify({
+        schema_version: 1,
+        agent_id: agentId,
+        server_pid: process.pid,
+        child_pid: null,
+        cwd: process.cwd(),
+        started_at: new Date(now).toISOString(),
+        started_at_ms: now,
+        last_activity_ms: now,
+        status: null,
+    });
+}
+function claimSlotPath(dir, agentId, max) {
+    let existing;
+    try {
+        existing = readdirSync(dir).filter((f) => f.startsWith("slot-"));
+    }
+    catch {
+        existing = [];
+    }
+    if (existing.length >= max)
+        return null;
+    const occupied = new Set(existing);
+    const candidateCount = max - existing.length;
+    const candidates = [];
+    for (let i = 0; i < max && candidates.length < candidateCount; i++) {
+        const name = `slot-${i}.json`;
+        if (!occupied.has(name))
+            candidates.push(slotPathForIndex(dir, i));
+    }
+    for (const path of candidates) {
+        let fd = null;
+        try {
+            fd = openSync(path, "wx", 0o600);
+            writeFileSync(fd, slotMetadataJson(agentId));
+            return path;
+        }
+        catch (e) {
+            if (fd !== null) {
+                try {
+                    closeSync(fd);
+                }
+                catch { }
+                fd = null;
+                try {
+                    unlinkSync(path);
+                }
+                catch { }
+            }
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    closeSync(fd);
+                }
+                catch { }
+            }
+        }
+    }
+    return null;
+}
 export function scheduleForceKill(ms, kill) {
     const timer = setTimeout(kill, ms);
     timer.unref();
@@ -608,21 +719,11 @@ export function reserveSlot(agentId, max, dir = slotDir(), cullDeps) {
             mkdirSync(dir, { recursive: true, mode: 0o700 });
         }
         cullStaleSlots(dir, cullDeps);
-        const slotPath = slotPathForAgent(dir, agentId);
-        const before = countSlots(dir);
-        if (before >= max) {
-            return { ok: false, current: before, max };
-        }
-        // ponytail: count->write->recount narrows the TOCTOU; a cross-process lock would close it fully.
-        writeSlotMetadata(slotPath, { agent_id: agentId });
-        const after = countSlots(dir);
-        if (after > max) {
-            try {
-                unlinkSync(slotPath);
-            }
-            catch { }
+        // ponytail: numbered O_EXCL slot claims make admission atomic without queues or a process-wide lock.
+        const slotPath = claimSlotPath(dir, agentId, max);
+        if (!slotPath)
             return { ok: false, current: countSlots(dir), max };
-        }
+        const after = countSlots(dir);
         return { ok: true, slotPath, current: after, max };
     }
     catch (e) {

package/dist/drivers.js

@@ -18,6 +18,7 @@ export const CLAUDE_SESSION_LIMIT = /^\s*you['’]ve hit your session limit\s*·
 export function isClaudeSessionLimit(text) {
     return CLAUDE_SESSION_LIMIT.test(text);
 }
+const TRANSIENT_FAILURE_RE = /\b429\b|\b(?:http(?:\/\d(?:\.\d)?)?|status|statuscode|status_code|code|error)\b[\s:=#-]*5\d{2}\b|quota|rate.?limit|timeout|ECONNRESET|ETIMEDOUT|ECONNREFUSED|too many requests|service unavailable|server error|overloaded/i;
 export function claudeMessageText(message) {
     if (message?.type === "assistant") {
         const content = message.message?.content;
@@ -167,7 +168,9 @@ function isElicitationMethod(method) {
 // Shape the `result` payload for an elicitation reply. When the RPC offered a
 // discrete option set, select only an exact case-insensitive label match and
 // echo its identifier; otherwise pass the answer through as text.
-function buildElicitationResult(options, answer) {
+function buildElicitationResult(options, answer, action = "answer") {
+    if (action === "decline")
+        return { action: "decline" };
     if (options && options.length > 0) {
         const norm = answer.trim().toLowerCase();
         const chosen = options.find((opt) => {
@@ -751,7 +754,8 @@ export class CodexAppServerDriver {
         else if (isJsonRpcId(message.id) &&
             typeof message.method === "string" &&
             isElicitationMethod(message.method)) {
-            void this.replyJsonRpc(message.id, buildElicitationResult(undefined, ""));
+            console.error(`[codex app-server driver] declining unhandled elicitation method: ${message.method}`);
+            void this.replyJsonRpc(message.id, buildElicitationResult(undefined, "", "decline"));
         }
         if (message.method === "turn/started" && message.params && typeof message.params === "object") {
             const turn = (message.params.turn ?? {});
@@ -819,7 +823,7 @@ export class CodexAppServerDriver {
     }
     fail(error) {
         const msg = error.message;
-        const transient = /\b429\b|\b5\d{2}\b|quota|rate.?limit|timeout|ECONNRESET|ETIMEDOUT|ECONNREFUSED|too many requests|service unavailable|server error|overloaded/i.test(msg);
+        const transient = TRANSIENT_FAILURE_RE.test(msg);
         this._definitelyStartedReject(transient ? new ProviderTransientError(msg) : error);
         this.process.fail(error);
         this.rejectPending(error);
@@ -1028,7 +1032,7 @@ export class ClaudeSdkDriver {
         catch (error) {
             if (!this.process.killed) {
                 const msg = error instanceof Error ? error.message : String(error);
-                const transient = /\b429\b|\b5\d{2}\b|quota|rate.?limit|timeout|ECONNRESET|ETIMEDOUT|ECONNREFUSED|too many requests|service unavailable|server error|overloaded/i.test(msg);
+                const transient = TRANSIENT_FAILURE_RE.test(msg);
                 this._definitelyStartedReject(transient ? new ProviderTransientError(msg) : new Error(msg));
                 this.closedFlag = true;
                 this.process.stderr.write(msg);
@@ -1038,8 +1042,11 @@ export class ClaudeSdkDriver {
     }
 }
 export async function createProviderDriver(options) {
-    if ((options.provider === "claude" && process.env.SUBAGENT_MOCK_CLAUDE_DRIVER === "jsonl") ||
-        (options.provider === "codex" && process.env.SUBAGENT_MOCK_CODEX_DRIVER === "jsonl")) {
+    const testSeamsEnabled = process.env.NODE_ENV === "test" || process.env.SUBAGENT_MCP_ENABLE_TEST_SEAMS === "1";
+    if (testSeamsEnabled &&
+        ((options.provider === "claude" && process.env.SUBAGENT_MOCK_CLAUDE_DRIVER === "jsonl") ||
+            (options.provider === "codex" && process.env.SUBAGENT_MOCK_CODEX_DRIVER === "jsonl"))) {
+        // Test seam: never honor mock-driver script env vars in production by default.
         const mockScript = process.env.SUBAGENT_MOCK_DRIVER_SCRIPT;
         const child = mockScript
             ? spawn(process.execPath, [mockScript, options.provider], {

package/dist/effort.js

@@ -6,9 +6,13 @@ export function mapModel(provider, model) {
     if (provider === "claude") {
         if (model === "opus" || model === "opus-4-8")
             return "claude-opus-4-8";
+        if (model === "sonnet")
+            return "claude-sonnet-4-6";
+        if (model === "haiku")
+            return "claude-haiku-4-5";
         if (model === "fable")
             return "claude-fable-5";
-        return model; // haiku, sonnet as-is
+        return model;
     }
     else {
         return model; // gpt-5.5
@@ -60,10 +64,8 @@ export function buildCommand(provider, model, effort, cwd, agentId) {
             const ucSettingsPath = join(ucSettingsDir, "settings.json");
             writeFileSync(ucSettingsPath, '{"ultracode":true}', { mode: 0o600 });
             args.push("--settings", ucSettingsPath);
-            args.push("--permission-mode", "bypassPermissions", "--tools", "default", "--max-turns", "50");
             return { args, ucSettingsPath, ucSettingsDir };
         }
-        args.push("--permission-mode", "bypassPermissions", "--tools", "default", "--max-turns", "50");
         return { args };
     }
     else {

package/dist/hooks/orchestration-claude.js

@@ -1,6 +1,6 @@
-import { realpathSync } from "node:fs";
+import { closeSync, openSync, readFileSync, readSync, realpathSync, statSync, } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { countJsonlType, runHook, } from "../orchestration/hook-core.js";
+import { countJsonlType, runHook, TRANSCRIPT_READ_CAP, } from "../orchestration/hook-core.js";
 import { hasParentMarker } from "../launch-prompt.js";
 /**
  * Claude Code UserPromptSubmit hook entry. Reads the JSON payload from stdin,
@@ -22,6 +22,87 @@ const SUBAGENT_ENTRYPOINTS = new Set([
     "sdk-ts",
     "sdk-py",
 ]);
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function readTranscriptTail(transcriptPath) {
+    if (!transcriptPath)
+        return null;
+    let fd;
+    try {
+        const size = statSync(transcriptPath).size;
+        if (size <= TRANSCRIPT_READ_CAP) {
+            return readFileSync(transcriptPath, "utf8");
+        }
+        const start = size - TRANSCRIPT_READ_CAP;
+        const buf = Buffer.allocUnsafe(TRANSCRIPT_READ_CAP);
+        fd = openSync(transcriptPath, "r");
+        let offset = 0;
+        let pos = start;
+        while (offset < TRANSCRIPT_READ_CAP) {
+            const bytes = readSync(fd, buf, offset, TRANSCRIPT_READ_CAP - offset, pos);
+            if (bytes <= 0)
+                break;
+            offset += bytes;
+            pos += bytes;
+        }
+        const raw = buf.toString("utf8", 0, offset);
+        const firstNewline = raw.indexOf("\n");
+        return firstNewline === -1 ? "" : raw.slice(firstNewline + 1);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Ignore close failures. The hook must never fail the host turn.
+            }
+        }
+    }
+}
+function liftClaudeUsageFromTranscript(transcriptPath) {
+    const raw = readTranscriptTail(transcriptPath);
+    if (raw === null || !transcriptPath)
+        return null;
+    const lines = raw.split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const trimmed = lines[i].trim();
+        if (!trimmed)
+            continue;
+        try {
+            const msg = JSON.parse(trimmed);
+            if (msg.type !== "assistant" || !msg.message?.usage)
+                continue;
+            if (typeof msg.message.model !== "string")
+                return null;
+            const usage = msg.message.usage;
+            return {
+                harness: "claude",
+                model: msg.message.model,
+                source_ref: transcriptPath,
+                usage: {
+                    input: finiteNumber(usage.input_tokens) ? usage.input_tokens : 0,
+                    output: finiteNumber(usage.output_tokens) ? usage.output_tokens : 0,
+                    cache_creation: finiteNumber(usage.cache_creation_input_tokens)
+                        ? usage.cache_creation_input_tokens
+                        : 0,
+                    cache_read: finiteNumber(usage.cache_read_input_tokens)
+                        ? usage.cache_read_input_tokens
+                        : 0,
+                },
+                harnessPercentage: null,
+            };
+        }
+        catch {
+            // Skip malformed transcript lines and keep scanning older completed turns.
+        }
+    }
+    return null;
+}
 export const claudeAdapter = {
     isSubagent(payload, env) {
         // subagent-mcp-spawned children inherit this guard and must not claim/nag.
@@ -45,6 +126,9 @@ export const claudeAdapter = {
     currentTurn(transcriptPath) {
         return countJsonlType(transcriptPath, "user");
     },
+    liftUsage(_payload, _env, transcriptPath) {
+        return liftClaudeUsageFromTranscript(transcriptPath);
+    },
     anonScope: "claude",
     fullDirectiveFile: "orchestration-claude.md",
     shortOnFile: "short-on.md",