@heretyc/subagent-mcp 2.12.11 → 2.12.13

package/dist/orchestration/handoff.js

@@ -0,0 +1,142 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { atomicWriteJson } from "./atomic-write.js";
+import { cwdHash, stateDir } from "./marker.js";
+export const HANDOFF_THRESHOLD_PCT = 50;
+export const HANDOFF_CONTENT_LIMIT = 4000;
+export const HANDOFF_OVERFLOW_LIMIT = 8000;
+export const UNAVAILABLE_NO_METERING = "handoff-write is not available due to missing context size data. It will become available once context usage can be measured for this session.";
+export const UNAVAILABLE_BELOW_50 = "handoff-write is not available until this session reaches 50% context utilization (currently below threshold).";
+export const OVERSIZE_CONTENT = "handoff content exceeds the 4000-character limit; shorten it, or move the excess (up to 8000 additional characters) into a separate file and reference its full path inside the 4000-character content.";
+export const OVERSIZE_OVERFLOW = "handoff overflow content exceeds the 8000-character limit; shorten the overflow file content and retry.";
+export const NO_HANDOFF_FOUND = "No handoff found for this directory. Resume the previous session and ask it to write one via handoff-write.";
+export const HANDOFF_WRITE_SUCCESS = "We are ready to start a new session, to avoid wasting tokens, use the structured question tool to confirm that the user is ready to use the `handoff-resume skill` in the next new session to resume work and has cleared the current /goal (if present) - or you will be compelled to keep working on a potential /goal that needs to be halted for a new session.";
+export function handoffPath(cwd) {
+    return join(stateDir, "handoff-" + cwdHash(cwd) + ".json");
+}
+export function handoffOverflowPath(cwd, now = Date.now()) {
+    return join(stateDir, "handoff-overflow-" + cwdHash(cwd) + "-" + now + ".md");
+}
+export function checkHandoffWriteAvailable(metering) {
+    const used = metering?.used_percentage;
+    if (typeof used !== "number" || !Number.isFinite(used)) {
+        return { ok: false, error: UNAVAILABLE_NO_METERING };
+    }
+    if (used < HANDOFF_THRESHOLD_PCT) {
+        return { ok: false, error: UNAVAILABLE_BELOW_50 };
+    }
+    return { ok: true };
+}
+export function readHandoff(cwd) {
+    try {
+        const raw = readFileSync(handoffPath(cwd), "utf8");
+        return validateHandoffRecord(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeHandoff(cwd, input) {
+    if (input.content.length > HANDOFF_CONTENT_LIMIT) {
+        return { ok: false, error: OVERSIZE_CONTENT };
+    }
+    const overflowContent = input.overflowContent ?? "";
+    if (overflowContent.length > HANDOFF_OVERFLOW_LIMIT) {
+        return { ok: false, error: OVERSIZE_OVERFLOW };
+    }
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const overflowPath = overflowContent.length > 0 ? handoffOverflowPath(cwd) : null;
+    if (overflowPath !== null) {
+        writeFileSync(overflowPath, overflowContent, { encoding: "utf8", mode: 0o600 });
+    }
+    const record = {
+        content: input.content,
+        overflow_path: overflowPath,
+        created_at: Date.now(),
+        created_by_session: input.createdBySession,
+        read_by_session: null,
+        read_at: null,
+    };
+    atomicWriteJson(handoffPath(cwd), record, { encoding: "utf8", mode: 0o600 });
+    return { ok: true, record };
+}
+export function writeHandoffIfAvailable(cwd, input, metering) {
+    const gate = checkHandoffWriteAvailable(metering);
+    if (!gate.ok)
+        return gate;
+    return writeHandoff(cwd, input);
+}
+export function markRead(cwd, sessionKey) {
+    const record = readHandoff(cwd);
+    if (record === null)
+        return null;
+    const next = {
+        ...record,
+        read_by_session: sessionKey,
+        read_at: Date.now(),
+    };
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        atomicWriteJson(handoffPath(cwd), next, { encoding: "utf8", mode: 0o600 });
+        return next;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearHandoff(cwd) {
+    const record = readHandoff(cwd);
+    unlinkIfPresent(handoffPath(cwd));
+    if (record?.overflow_path) {
+        unlinkIfPresent(record.overflow_path);
+    }
+}
+function unlinkIfPresent(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT") {
+            throw e;
+        }
+    }
+}
+function validateHandoffRecord(value) {
+    if (value === null || typeof value !== "object")
+        return null;
+    const record = value;
+    const content = record.content;
+    const overflowPath = record.overflow_path;
+    const createdAt = record.created_at;
+    const createdBySession = record.created_by_session;
+    const readBySession = record.read_by_session;
+    const readAt = record.read_at;
+    if (typeof content !== "string")
+        return null;
+    if (content.length > HANDOFF_CONTENT_LIMIT)
+        return null;
+    if (!isValidOverflowPath(overflowPath))
+        return null;
+    if (!isFiniteNumber(createdAt))
+        return null;
+    if (typeof createdBySession !== "string")
+        return null;
+    if (readBySession !== null && typeof readBySession !== "string")
+        return null;
+    if (readAt !== null && !isFiniteNumber(readAt))
+        return null;
+    return {
+        content,
+        overflow_path: overflowPath,
+        created_at: createdAt,
+        created_by_session: createdBySession,
+        read_by_session: readBySession,
+        read_at: readAt,
+    };
+}
+function isValidOverflowPath(path) {
+    return path === null || (typeof path === "string" && isAbsolute(path));
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}

package/dist/orchestration/hook-core.js

@@ -3,6 +3,10 @@ import { fileURLToPath } from "node:url";
 import { dirname, isAbsolute, join } from "node:path";
 import * as marker from "./marker.js";
 import * as reminder from "./reminder.js";
+import * as handoff from "./handoff.js";
+import * as latch from "./latch.js";
+import * as metering from "./metering.js";
+import * as template from "./template.js";
 import { cullStaleSlots, slotDir, ZOMBIE_FORCE_GRACE_MS, } from "../concurrency.js";
 import { appendUpdateNotice, readInstalledPackageInfo, } from "./update-check.js";
 /**
@@ -226,9 +230,119 @@ function claimOwner(m, owner, turn, now) {
  * rule carrier on every prompt and never refresh the LONG block.
  */
 function cadenceEmit(env, adapter, longFile, shortFile, count, persisted) {
-    return !persisted || count % REMINDER_PERIOD === 0
-        ? readDirective(env, longFile)
-        : readDirective(env, shortFile);
+    const isLong = !persisted || count % REMINDER_PERIOD === 0;
+    return {
+        body: bodyFromDirective(readDirective(env, isLong ? longFile : shortFile)),
+        kind: isLong ? "reminder" : "carrier",
+        isLong,
+    };
+}
+function bodyFromDirective(raw) {
+    return raw
+        .replace(/<subagent-mcp\b[^>]*>/g, "")
+        .replace(/<\/subagent-mcp>/g, "")
+        .trim();
+}
+function appendReadHandoffForLong(body, cwd, current, isLong) {
+    if (!isLong)
+        return body;
+    const record = handoff.readHandoff(cwd);
+    if (record?.read_by_session !== current)
+        return body;
+    const overflowLine = record.overflow_path
+        ? `\nOverflow path: ${record.overflow_path}`
+        : "";
+    return `${body}\n${record.content}${overflowLine}`;
+}
+function composeInjection(emission, effectiveActive, phase, usedPercentage) {
+    // Fail-safe: an unreadable/empty directive body injects NOTHING rather than a
+    // hollow tag (preserves the pre-template missing-directive contract).
+    if (emission.body.trim() === "")
+        return null;
+    const tag = template.composeTag({
+        state: effectiveActive ? "on" : "off",
+        kind: emission.kind,
+        phase,
+        utilization: usedPercentage === null ? "unknown" : `${Math.round(usedPercentage)}%`,
+    });
+    const footer = template.composeFooter(usedPercentage === null ? null : Math.round(100 - usedPercentage));
+    return `${tag}\n${emission.body}\n</subagent-mcp>${footer ? `\n${footer}` : ""}`;
+}
+function composeHookUpdateNotice(env, updateNoticeSessionId, emission, effectiveActive, phase, usedPercentage) {
+    const injected = composeInjection(emission, effectiveActive, phase, usedPercentage);
+    if (injected === null)
+        return "";
+    return appendHookUpdateNotice(injected, updateNoticeSessionId, env);
+}
+function readMeteringState(current) {
+    const record = metering.readMetering(current);
+    const usedPercentage = record?.used_percentage ?? null;
+    return {
+        usedPercentage,
+        phase: metering.phaseFor(usedPercentage),
+    };
+}
+/**
+ * Lift this turn's usage, persist the metering record, and report whether
+ * metering is undetectable (fail-safe ON) for THIS turn.
+ *
+ * One-turn lag (accepted by design, see context-metering.md): the transcript
+ * only carries the PRIOR assistant turn's usage, so the metering data reflects
+ * the last COMPLETED turn, not the in-flight one. Thresholds therefore trip one
+ * turn late, which is harmless. Turn <= 1 has no completed turn yet, so it is a
+ * grace window: no metering is expected and the session is NOT fail-safed.
+ */
+function updateMeteringForTurn(payload, env, adapter, current, turnIndex) {
+    if (turnIndex <= 1)
+        return false;
+    const lifted = adapter.liftUsage(payload, env, payload.transcript_path);
+    if (lifted === null)
+        return true;
+    // A valid harness-reported percentage stands on its own: it does not require
+    // the static model->window map, so an unknown model is NOT undetectable when a
+    // percentage was supplied. Only fall back to requiring window resolution when
+    // no harness percentage is available.
+    const hasHarnessPercentage = typeof lifted.harnessPercentage === "number" &&
+        Number.isFinite(lifted.harnessPercentage);
+    if (!hasHarnessPercentage &&
+        metering.resolveContextWindow(lifted.harness, lifted.model) === null) {
+        return true;
+    }
+    const record = metering.buildMeteringRecord({
+        session_id: current,
+        harness: lifted.harness,
+        model: lifted.model,
+        source_ref: lifted.source_ref,
+        usage: lifted.usage,
+        event: typeof payload.hook_event_name === "string"
+            ? payload.hook_event_name
+            : "UserPromptSubmit",
+        harnessPercentage: lifted.harnessPercentage,
+    });
+    metering.writeMetering(current, record);
+    return false;
+}
+function providerDirectiveFile(adapter, prefix) {
+    return `${prefix}-${adapter.anonScope}.md`;
+}
+/**
+ * Single source of truth for the effective ON/OFF decision. Shared by runHook,
+ * the Codex SessionStart dispatcher, and the orchestration-mode MCP tool so all
+ * three agree on the same turn (no drift between the hook tag and the tool).
+ *
+ * An explicit session disable always wins (2h TTL, user-only). Otherwise the
+ * session is ON when the marker is active, the 15% latch has tripped, or
+ * metering is undetectable (fail-safe ON). `meteringUndetectableFailSafe` is
+ * supplied by the caller because only the caller knows its own turn context: the
+ * hook honors the turn-1 grace window (no completed turn yet, so early turns are
+ * NOT fail-safed), and the tool derives it from the persisted metering record.
+ */
+export function computeEffectiveActive(cwd, current, now, meteringUndetectableFailSafe) {
+    if (current !== undefined && marker.isSessionDisabled(current, now)) {
+        return false;
+    }
+    const latched = current !== undefined && latch.isLatchActive(current, now);
+    return marker.isActive(cwd, current) || latched || meteringUndetectableFailSafe;
 }
 /**
  * Claim (or re-claim) an active marker for the current session and emit the
@@ -240,7 +354,7 @@ function cadenceEmit(env, adapter, longFile, shortFile, count, persisted) {
  * claim branch and the Codex SessionStart dispatcher (one copy of the claim
  * semantics, no drift).
  */
-export function claimAndEmit(cwd, current, turn, m, kind, env, adapter) {
+export function claimAndEmit(cwd, current, turn, m, kind, env, adapter, effectiveActive = true, phase = "normal", usedPercentage = null, updateNoticeSessionId, fullBodyFile) {
     const firstCarryover = kind === "carryover" && !m.carryover_ack;
     claimOwner(m, current, turn, Date.now());
     if (kind === "carryover") {
@@ -249,11 +363,29 @@ export function claimAndEmit(cwd, current, turn, m, kind, env, adapter) {
     }
     marker.writeMarker(cwd, m);
     reminder.rebase(cwd, current, 0);
-    const full = readDirective(env, adapter.fullDirectiveFile) +
-        readDirective(env, adapter.reminderOnFile);
-    return firstCarryover
-        ? readDirective(env, adapter.carryoverDirectiveFile) + full
-        : full;
+    const full = fullBodyFile
+        ? bodyFromDirective(readDirective(env, fullBodyFile))
+        : bodyFromDirective(readDirective(env, adapter.fullDirectiveFile)) +
+            "\n" +
+            bodyFromDirective(readDirective(env, adapter.reminderOnFile));
+    const handoffBody = phase === "handoff"
+        ? "\n" +
+            bodyFromDirective(readDirective(env, providerDirectiveFile(adapter, "handoff")))
+        : "";
+    // The CARRYOVER notice must be emitted on the SAME turn that burns
+    // carryover_ack (set above), even when a FULL-body override (e.g. the
+    // just-tripped latch coaching) also fires this turn. Prepend it ahead of that
+    // body rather than dropping it, or the once-per-marker notice is lost.
+    const emission = {
+        body: (firstCarryover
+            ? bodyFromDirective(readDirective(env, adapter.carryoverDirectiveFile)) +
+                "\n" +
+                full
+            : full) + handoffBody,
+        kind: firstCarryover ? "carryover" : "directive",
+        isLong: true,
+    };
+    return composeHookUpdateNotice(env, updateNoticeSessionId, emission, effectiveActive, phase, usedPercentage);
 }
 function hookCullDeps(env = process.env) {
     return {
@@ -309,20 +441,56 @@ export function runHook(payload, env, adapter) {
         const current = ownerKey(payload, cwd, adapter);
         const updateNoticeSessionId = typeof payload.session_id === "string" ? payload.session_id : undefined;
         marker.writeCurrentSession(cwd, current);
-        if (!marker.isActive(cwd, current)) {
-            // OFF: no claim machinery — just the per-prompt reminder cadence.
+        const now = Date.now();
+        const turnIndex = adapter.currentTurn(payload.transcript_path);
+        const meteringUndetectableFailSafe = updateMeteringForTurn(payload, env, adapter, current, turnIndex);
+        const meteringState = readMeteringState(current);
+        const wasLatched = latch.isLatchActive(current, now);
+        if (meteringState.phase !== "normal" || wasLatched) {
+            latch.tripLatch(current, now);
+        }
+        const isLatched = latch.isLatchActive(current, now);
+        const justTrippedLatch = !wasLatched && isLatched;
+        const effectiveActive = computeEffectiveActive(cwd, current, now, meteringUndetectableFailSafe);
+        if (!effectiveActive) {
             const r = reminder.advance(cwd, current);
-            return appendHookUpdateNotice(cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted), updateNoticeSessionId, env);
+            // A session that has already read a handoff re-appends the saved content
+            // to EVERY LONG reminder (spec), regardless of ON/OFF cadence.
+            const offEmission = cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted);
+            return composeHookUpdateNotice(env, updateNoticeSessionId, {
+                ...offEmission,
+                body: appendReadHandoffForLong(offEmission.body, cwd, current, offEmission.isLong),
+            }, effectiveActive, meteringState.phase, meteringState.usedPercentage);
         }
         const m = marker.readMarker(cwd);
         const kind = classifyOwnerClaim(m, current);
         if (kind === "fresh" || kind === "carryover") {
-            const turn = adapter.currentTurn(payload.transcript_path);
-            return appendHookUpdateNotice(claimAndEmit(cwd, current, turn, m, kind, env, adapter), updateNoticeSessionId, env);
+            return claimAndEmit(cwd, current, turnIndex, m, kind, env, adapter, effectiveActive, meteringState.phase, meteringState.usedPercentage, updateNoticeSessionId, meteringState.phase === "plan" && justTrippedLatch
+                ? providerDirectiveFile(adapter, "latch")
+                : undefined);
         }
-        // SAME-SESSION: per-prompt reminder cadence, ON variant.
         const r = reminder.advance(cwd, current);
-        return appendHookUpdateNotice(cadenceEmit(env, adapter, adapter.reminderOnFile, adapter.shortOnFile, r.count, r.persisted), updateNoticeSessionId, env);
+        let emission = cadenceEmit(env, adapter, adapter.reminderOnFile, adapter.shortOnFile, r.count, r.persisted);
+        emission = {
+            ...emission,
+            body: appendReadHandoffForLong(emission.body, cwd, current, emission.isLong),
+        };
+        if (meteringState.phase === "plan" && justTrippedLatch) {
+            emission = {
+                body: bodyFromDirective(readDirective(env, providerDirectiveFile(adapter, "latch"))),
+                kind: "directive",
+                isLong: true,
+            };
+        }
+        if (meteringState.phase === "handoff") {
+            emission = {
+                ...emission,
+                body: emission.body +
+                    "\n" +
+                    bodyFromDirective(readDirective(env, providerDirectiveFile(adapter, "handoff"))),
+            };
+        }
+        return composeHookUpdateNotice(env, updateNoticeSessionId, emission, effectiveActive, meteringState.phase, meteringState.usedPercentage);
     }
     catch {
         // Any failure -> inject nothing. Never crash or stall the host turn.

package/dist/orchestration/latch.js

@@ -0,0 +1,47 @@
+import { mkdirSync, readFileSync, unlinkSync, } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteJson } from "./atomic-write.js";
+import { hashKey, stateDir } from "./marker.js";
+export function latchPath(sessionKey) {
+    return join(stateDir, `latch-${hashKey(sessionKey)}.json`);
+}
+export function isLatchActive(sessionKey, now) {
+    void now;
+    try {
+        const raw = readFileSync(latchPath(sessionKey), "utf8");
+        const parsed = JSON.parse(raw);
+        return (parsed.latched === true &&
+            typeof parsed.latched_at === "number" &&
+            Number.isFinite(parsed.latched_at) &&
+            typeof parsed.session_id === "string");
+    }
+    catch {
+        return false;
+    }
+}
+export function tripLatch(sessionKey, now) {
+    if (isLatchActive(sessionKey, now))
+        return;
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        atomicWriteJson(latchPath(sessionKey), {
+            latched: true,
+            latched_at: now,
+            session_id: sessionKey,
+        }, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Fail-safe: latch write failures must not crash hook execution.
+    }
+}
+export function clearLatch(sessionKey) {
+    try {
+        unlinkSync(latchPath(sessionKey));
+    }
+    catch {
+        // Fail-safe: callers use this for teardown/admin reset only.
+    }
+}

package/dist/orchestration/marker.js

@@ -57,6 +57,9 @@ export function markerPath(cwd) {
 export function disablePath(sessionKey) {
     return join(stateDir, `orch-disable-${hashKey(sessionKey)}.json`);
 }
+export function enablePath(sessionKey) {
+    return join(stateDir, `orch-enable-${hashKey(sessionKey)}.json`);
+}
 function cwdDisablePath(cwd) {
     return join(stateDir, `orch-disable-${cwdHash(cwd)}.json`);
 }
@@ -123,6 +126,28 @@ export function removeDisable(sessionKey) {
         // Fail-safe: never throw to the caller.
     }
 }
+export function writeEnable(sessionKey) {
+    if (!isSessionScopedKey(sessionKey))
+        return;
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        atomicWriteJson(enablePath(sessionKey), { enabled_at: Date.now() }, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Fail-safe: never throw to the caller.
+    }
+}
+export function removeEnable(sessionKey) {
+    try {
+        unlinkSync(enablePath(sessionKey));
+    }
+    catch {
+        // Fail-safe: never throw to the caller.
+    }
+}
 export function writeCurrentSession(cwd, sessionKey, serverKey = process.ppid) {
     try {
         mkdirSync(stateDir, { recursive: true, mode: 0o700 });
@@ -176,11 +201,40 @@ function isDisableActive(path, now) {
     unlinkSync(path);
     return false;
 }
+function isEnableActive(path, now) {
+    if (!existsSync(path)) {
+        return false;
+    }
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.enabled_at !== "number") {
+        return false;
+    }
+    if (now - parsed.enabled_at <= ORCH_DISABLE_TTL_MS) {
+        return true;
+    }
+    // Lazy GC side-effect: the enable has expired, so remove it.
+    unlinkSync(path);
+    return false;
+}
+export function isSessionDisabled(sessionKey, now = Date.now()) {
+    try {
+        if (!isSessionScopedKey(sessionKey))
+            return false;
+        return isDisableActive(disablePath(sessionKey), now);
+    }
+    catch {
+        return false;
+    }
+}
 export function isActive(cwd, sessionKey) {
     try {
         if (sessionKey === undefined || !isSessionScopedKey(sessionKey))
             return true;
-        return !isDisableActive(disablePath(sessionKey), Date.now());
+        const now = Date.now();
+        if (isDisableActive(disablePath(sessionKey), now))
+            return false;
+        return isEnableActive(enablePath(sessionKey), now);
     }
     catch {
         return true;

package/dist/orchestration/metering.js

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteJson } from "./atomic-write.js";
+import { hashKey, ORCH_DISABLE_TTL_MS, stateDir, } from "./marker.js";
+export const PLAN_LATCH_THRESHOLD_PCT = 15;
+export const HANDOFF_UNLOCK_THRESHOLD_PCT = 50;
+export const DEFAULT_CONTEXT_WINDOW = 200000;
+export const LONG_CONTEXT_WINDOW = 1000000;
+export const CODEX_KNOWN_MODEL_IDS = [
+    "gpt-5",
+    "gpt-5-codex",
+    "gpt-5.5",
+    "o3",
+    "o3-mini",
+    "o4-mini",
+];
+export const CODEX_CONTEXT_WINDOW_BY_MODEL_ID = {
+    "gpt-5": DEFAULT_CONTEXT_WINDOW,
+    "gpt-5-codex": DEFAULT_CONTEXT_WINDOW,
+    "gpt-5.5": DEFAULT_CONTEXT_WINDOW,
+    o3: DEFAULT_CONTEXT_WINDOW,
+    "o3-mini": DEFAULT_CONTEXT_WINDOW,
+    "o4-mini": DEFAULT_CONTEXT_WINDOW,
+};
+export const CLAUDE_CONTEXT_WINDOW_BY_KIND = {
+    default: DEFAULT_CONTEXT_WINDOW,
+    long: LONG_CONTEXT_WINDOW,
+};
+const EMPTY_USAGE = {
+    input: 0,
+    output: 0,
+    cache_creation: 0,
+    cache_read: 0,
+};
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function normalizeUsage(usage) {
+    if (usage === null || usage === undefined) {
+        return { usage: { ...EMPTY_USAGE }, used_tokens: null };
+    }
+    const normalized = {
+        input: finiteNumber(usage.input) ? usage.input : 0,
+        output: finiteNumber(usage.output) ? usage.output : 0,
+        cache_creation: finiteNumber(usage.cache_creation) ? usage.cache_creation : 0,
+        cache_read: finiteNumber(usage.cache_read) ? usage.cache_read : 0,
+    };
+    return {
+        usage: normalized,
+        used_tokens: normalized.input +
+            normalized.output +
+            normalized.cache_creation +
+            normalized.cache_read,
+    };
+}
+export function resolveContextWindow(harness, modelId) {
+    if (!modelId)
+        return null;
+    if (harness === "claude") {
+        if (!/^claude-/i.test(modelId))
+            return null;
+        if (/\[1m\]/i.test(modelId))
+            return LONG_CONTEXT_WINDOW;
+        return DEFAULT_CONTEXT_WINDOW;
+    }
+    if (harness === "codex") {
+        if (!CODEX_KNOWN_MODEL_IDS.includes(modelId)) {
+            return null;
+        }
+        if (/-1m\b|\[1m\]/i.test(modelId))
+            return LONG_CONTEXT_WINDOW;
+        return CODEX_CONTEXT_WINDOW_BY_MODEL_ID[modelId];
+    }
+    return null;
+}
+export function meteringPath(sessionKey, stateDirOverride = stateDir) {
+    return join(stateDirOverride, "ctx-" + hashKey(sessionKey) + ".json");
+}
+export function computeUsedPercentage(record) {
+    if (finiteNumber(record.harnessPercentage)) {
+        // Clamp to [0,100] like the computed path: a harness could report a
+        // transiently out-of-range percentage, and phase/footer math assumes 0-100.
+        return Math.min(100, Math.max(0, record.harnessPercentage));
+    }
+    if (record.used_tokens === null || record.context_window_size === null) {
+        return null;
+    }
+    return Math.min(100, (record.used_tokens / record.context_window_size) * 100);
+}
+export function phaseFor(usedPercentage) {
+    return usedPercentage === null
+        ? "normal"
+        : usedPercentage >= HANDOFF_UNLOCK_THRESHOLD_PCT
+            ? "handoff"
+            : usedPercentage >= PLAN_LATCH_THRESHOLD_PCT
+                ? "plan"
+                : "normal";
+}
+export function buildMeteringRecord(input) {
+    const context_window_size = resolveContextWindow(input.harness, input.model);
+    const normalized = normalizeUsage(input.usage);
+    const used_percentage = computeUsedPercentage({
+        context_window_size,
+        used_tokens: normalized.used_tokens,
+        harnessPercentage: input.harnessPercentage,
+    });
+    return {
+        session_id: input.session_id,
+        harness: input.harness,
+        model: input.model,
+        source_ref: input.source_ref,
+        context_window_size,
+        usage: normalized.usage,
+        used_tokens: normalized.used_tokens,
+        used_percentage,
+        near_limit: used_percentage !== null &&
+            used_percentage >= HANDOFF_UNLOCK_THRESHOLD_PCT,
+        event: input.event,
+        updated_at: Date.now(),
+    };
+}
+function isMeteringRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return typeof record.updated_at === "number";
+}
+export function readMetering(sessionKey, stateDirOverride = stateDir) {
+    try {
+        const path = meteringPath(sessionKey, stateDirOverride);
+        if (!existsSync(path))
+            return null;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!isMeteringRecord(parsed))
+            return null;
+        if (Date.now() - parsed.updated_at > ORCH_DISABLE_TTL_MS) {
+            unlinkSync(path);
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeMetering(sessionKey, record, stateDirOverride = stateDir) {
+    try {
+        mkdirSync(stateDirOverride, { recursive: true, mode: 0o700 });
+        atomicWriteJson(meteringPath(sessionKey, stateDirOverride), record, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/orchestration/pretool.js

@@ -16,9 +16,9 @@ function decision(permissionDecision, permissionDecisionReason, additionalContex
  * deny harness-native Task/Agent/Explore while subagent-mcp is alive so all
  * sub-agent launches route through launch_agent. There is NO inline tool-call
  * counter — the old inline tool-call-count injection is gone (D11/D24).
- * Long-horizon
- * upgrades are now agent-self-driven via the OFF-mode cumulative footprint
- * check (no hook-side counting).
+ * Long-horizon upgrades are now driven by provider-metered context tracking
+ * (see docs/spec/dev-loop/orchestration-directive-architecture/context-metering.md),
+ * not any hook-side footprint counting.
  */
 export function runClaudePreTool(payload, env, now = Date.now()) {
     try {