@heretyc/subagent-mcp 2.12.12 → 2.12.14

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 {

package/dist/orchestration/template.js

@@ -0,0 +1,31 @@
+export const TAG_TEMPLATE = '<subagent-mcp state="{{state}}" kind="{{kind}}" phase="{{phase}}" utilization="{{utilization}}">';
+export const FOOTER_TEMPLATE = "Remaining Context={{remaining}}%";
+const PLACEHOLDER = /\{\{([a-zA-Z0-9_]+)\}\}/g;
+const UNRESOLVED_PLACEHOLDER = /\{\{[a-zA-Z0-9_]+\}\}/;
+export function renderTemplate(template, vars) {
+    const rendered = template.replace(PLACEHOLDER, (token, name) => {
+        if (!Object.prototype.hasOwnProperty.call(vars, name)) {
+            throw new Error(`Missing template variable: ${name}`);
+        }
+        return vars[name] ?? "";
+    });
+    if (UNRESOLVED_PLACEHOLDER.test(rendered)) {
+        throw new Error("Rendered template contains unresolved placeholder");
+    }
+    return rendered;
+}
+export function composeTag(vars) {
+    // Test-only seam: SUBAGENT_MCP_TEST_TAG_TEMPLATE overrides the tag template so a malformed value forces a throw (mission item 5 fail-safe: any template error => inject nothing). Unset in production.
+    const template = process.env.SUBAGENT_MCP_TEST_TAG_TEMPLATE ?? TAG_TEMPLATE;
+    return renderTemplate(template, vars);
+}
+export function composeFooter(remainingPct) {
+    if (remainingPct === null)
+        return "";
+    if (!Number.isFinite(remainingPct)) {
+        throw new Error("Invalid remaining context percentage");
+    }
+    return renderTemplate(FOOTER_TEMPLATE, {
+        remaining: String(Math.round(remainingPct)),
+    });
+}

package/dist/pending-permissions.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 const PARK_TIMEOUT_MS = 5 * 60 * 1000;
 const PER_AGENT_FIFO_CAP = 16;
+const PENDING_PERMISSION_HISTORY_CAP = 200;
 function publicRecord(record) {
     // record may be a StoredPendingPermission at runtime, which carries a live
     // NodeJS.Timeout and a resolve closure. Both are non-serializable (the timer
@@ -57,7 +58,7 @@ export class PendingPermissionManager {
                 answer_reason: "pending-queue cap reached",
             };
             this.telemetry.cap_overflow_auto_denies += 1;
-            this.history.push(publicRecord(record));
+            this.remember(record);
             console.error(`[permissions] auto-deny ${record.request_id} for agent ${record.agent_id}: pending-queue cap reached`);
             void Promise.resolve(input.resolve({
                 request_id: record.request_id,
@@ -125,6 +126,7 @@ export class PendingPermissionManager {
             if (record)
                 closed.push(await this.finish(record, "deny", reason));
         }
+        this.askedCountByAgent.delete(agentId);
         return closed;
     }
     async autoDeny(requestId, reason) {
@@ -141,8 +143,10 @@ export class PendingPermissionManager {
         const queue = (this.pendingByAgent.get(record.agent_id) ?? []).filter((id) => id !== record.request_id);
         if (queue.length > 0)
             this.pendingByAgent.set(record.agent_id, queue);
-        else
+        else {
             this.pendingByAgent.delete(record.agent_id);
+            this.askedCountByAgent.delete(record.agent_id);
+        }
         record.state = autoRule ? "auto_answered" : "answered";
         record.auto_answer_rule = autoRule;
         record.answered_at = Date.now();
@@ -160,10 +164,16 @@ export class PendingPermissionManager {
             record.state = "errored";
             record.answer_reason = e instanceof Error ? e.message : String(e);
         }
-        this.history.push(publicRecord(record));
+        this.remember(record);
         this.emitQueue(record.agent_id);
         return publicRecord(record);
     }
+    remember(record) {
+        this.history.push(publicRecord(record));
+        if (this.history.length > PENDING_PERMISSION_HISTORY_CAP) {
+            this.history.splice(0, this.history.length - PENDING_PERMISSION_HISTORY_CAP);
+        }
+    }
     emitQueue(agentId) {
         const count = this.pendingCount(agentId);
         for (const listener of this.queueListeners)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.12.12",
+  "version": "2.12.14",
   "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
   "keywords": [
     "mcp",
@@ -39,7 +39,7 @@
     "postinstall": "node scripts/postinstall.mjs",
     "prepare": "npm run build",
     "prepublishOnly": "npm test",
-    "test": "npm run check:versions && npm run check:prose && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/global-concurrency-cap.test.mjs && node test/update-check.test.mjs && node test/atomic-write.test.mjs && node test/zombie.test.mjs && node test/zombie-reap-idle.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/no-per-provider-cap.test.mjs && node test/no-api-keys.test.mjs && node test/rag-pointers.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node test/index-guard.test.mjs && node test/drivers-guard.test.mjs && node test/audit-next13-lb3.test.mjs && node test/zombie-guard.test.mjs && node test/concurrency-guard.test.mjs && node test/hook-core-guard.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/config-bom.test.mjs && node test/permission-system.test.mjs && node test/lifecycle-matrix.test.mjs && node test/output-hook-registration.test.mjs && node test/mcp-compliance.test.mjs"
+    "test": "npm run check:versions && npm run check:prose && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/global-concurrency-cap.test.mjs && node test/update-check.test.mjs && node test/atomic-write.test.mjs && node test/zombie.test.mjs && node test/zombie-reap-idle.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-metering.test.mjs && node test/orchestration-latch.test.mjs && node test/orchestration-handoff.test.mjs && node test/orchestration-template.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/no-200-line-footprint.test.mjs && node test/no-per-provider-cap.test.mjs && node test/no-api-keys.test.mjs && node test/rag-pointers.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/handoff-resume-skill.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node test/index-guard.test.mjs && node test/drivers-guard.test.mjs && node test/audit-next13-lb3.test.mjs && node test/zombie-guard.test.mjs && node test/concurrency-guard.test.mjs && node test/hook-core-guard.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/config-bom.test.mjs && node test/permission-system.test.mjs && node test/lifecycle-matrix.test.mjs && node test/output-hook-registration.test.mjs && node test/mcp-compliance.test.mjs"
   },
   "author": "Lexi Blackburn",
   "license": "Apache-2.0",
@@ -57,8 +57,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=18"