@desplega.ai/agent-swarm 1.166.0 → 1.168.0

package/src/hooks/hook.ts

@@ -168,12 +168,25 @@ export async function postHookProfileUpdate({
 }
 
 /**
- * Hook response for blocking actions
+ * Hook JSON responses. Claude Code parses stdout as JSON only when the whole
+ * stdout is one JSON object, so these must be the only stdout of the event.
  * See: https://code.claude.com/docs/en/hooks
  */
-interface HookBlockResponse {
-  decision: "block";
-  reason: string;
+type HookBlockResponse =
+  | {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse";
+        permissionDecision: "deny";
+        permissionDecisionReason: string;
+      };
+    }
+  | { decision: "block"; reason: string };
+
+interface HookContextResponse {
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse" | "PostToolUse";
+    additionalContext: string;
+  };
 }
 
 /**
@@ -850,12 +863,33 @@ export async function handleHook(): Promise<void> {
 
   /**
    * Output a blocking response to stop Claude from continuing.
-   * This is used when a task has been cancelled.
+   * Must be the only stdout of the event: any plain line before it makes
+   * Claude Code read the whole stdout as text and run the tool anyway.
    */
   const outputBlockResponse = (reason: string): void => {
-    const response: HookBlockResponse = {
-      decision: "block",
-      reason,
+    const response: HookBlockResponse =
+      msg.hook_event_name === "PreToolUse"
+        ? {
+            hookSpecificOutput: {
+              hookEventName: "PreToolUse",
+              permissionDecision: "deny",
+              permissionDecisionReason: reason,
+            },
+          }
+        : { decision: "block", reason };
+    console.log(JSON.stringify(response));
+  };
+
+  /**
+   * Output context for the model on a tool event. Plain stdout on PreToolUse
+   * and PostToolUse never reaches the model; additionalContext does.
+   */
+  const outputToolContext = (
+    hookEventName: "PreToolUse" | "PostToolUse",
+    additionalContext: string,
+  ): void => {
+    const response: HookContextResponse = {
+      hookSpecificOutput: { hookEventName, additionalContext },
     };
     console.log(JSON.stringify(response));
   };
@@ -988,8 +1022,23 @@ export async function handleHook(): Promise<void> {
   // Get current agent info
   const agentInfo = await getAgentInfo();
 
-  // Always output agent status with system tray
-  if (agentInfo) {
+  // A block must be the only stdout of the event, so a cancelled task is
+  // checked before the status line goes out.
+  if (
+    msg.hook_event_name === "UserPromptSubmit" &&
+    agentInfo &&
+    !agentInfo.isLead &&
+    agentInfo.status === "busy"
+  ) {
+    if (await checkAndBlockIfCancelled(true)) {
+      return;
+    }
+  }
+
+  // Output agent status with system tray. Skipped on tool events: their plain
+  // stdout never reaches the model and would break a JSON decision.
+  const isToolEvent = msg.hook_event_name === "PreToolUse" || msg.hook_event_name === "PostToolUse";
+  if (agentInfo && !isToolEvent) {
     // Base status line
     console.log(
       `You are registered as ${agentInfo.isLead ? "lead" : "worker"} agent "${agentInfo.name}" (ID: ${agentInfo.id}, status: ${agentInfo.status}).`,
@@ -1004,7 +1053,7 @@ export async function handleHook(): Promise<void> {
     }
   } else if (
     shouldShowRegistrationNudge({
-      agentInfoPresent: false,
+      agentInfoPresent: Boolean(agentInfo),
       eventType: msg.hook_event_name,
       hasAgentIdHeader: hasAgentIdHeader(),
     })
@@ -1131,8 +1180,7 @@ export async function handleHook(): Promise<void> {
       }
 
       // Block `gh pr create|edit` when the body for a public repo leaks internal
-      // identifiers. Exit code 2 blocks the call even though the status line
-      // above already went to stdout, and stderr reaches the model.
+      // identifiers. Exit code 2 blocks the call and stderr reaches the model.
       if (msg.tool_name === "Bash") {
         const prBodyBlock = await guardGhPrBody(msg.tool_input, msg.cwd ?? process.cwd());
         if (prBodyBlock) {
@@ -1142,6 +1190,9 @@ export async function handleHook(): Promise<void> {
         }
       }
 
+      // Emitted last, so a later block stays the only stdout of the event.
+      let loopWarning: string | undefined;
+
       // Tool loop detection (workers only, when processing a task)
       if (agentInfo && !agentInfo.isLead && agentInfo.status === "busy") {
         const loopTaskFile = await readTaskFile();
@@ -1162,7 +1213,7 @@ export async function handleHook(): Promise<void> {
           }
 
           if (loopResult.severity === "warning" && loopResult.reason) {
-            console.log(`Warning: ${loopResult.reason}`);
+            loopWarning = `Warning: ${loopResult.reason}`;
           }
         }
       }
@@ -1179,6 +1230,9 @@ export async function handleHook(): Promise<void> {
         }
       }
 
+      if (loopWarning) {
+        outputToolContext("PreToolUse", loopWarning);
+      }
       break;
     }
 
@@ -1200,7 +1254,8 @@ export async function handleHook(): Promise<void> {
           method: "PUT",
           headers: mcpConfig!.headers,
         }).catch((e) => {
-          console.debug("Failed to update agent activity timestamp:", e);
+          // stderr: stdout on this event is reserved for one JSON object.
+          console.error("Failed to update agent activity timestamp:", e);
         });
       }
 
@@ -1270,7 +1325,8 @@ export async function handleHook(): Promise<void> {
           if (msg.tool_name?.endsWith("send-task")) {
             const maybeTaskId = (msg.tool_response as { task?: { id?: string } })?.task?.id;
 
-            console.log(
+            outputToolContext(
+              "PostToolUse",
               `Task sent successfully.${maybeTaskId ? ` Task ID: ${maybeTaskId}.` : ""} Monitor progress using the get-task-details tool periodically.`,
             );
           }
@@ -1278,17 +1334,6 @@ export async function handleHook(): Promise<void> {
       }
       break;
 
-    case "UserPromptSubmit": {
-      // For worker agents, check if their task has been cancelled
-      // This catches cancellations at the start of a new iteration
-      if (agentInfo && !agentInfo.isLead && agentInfo.status === "busy") {
-        if (await checkAndBlockIfCancelled(true)) {
-          return; // Exit early
-        }
-      }
-      break;
-    }
-
     case "Stop":
       // Clean up any artifact tunnels managed by PM2
       try {

package/src/http/mcp.ts

@@ -244,6 +244,11 @@ export async function handleMcp(
       }
       const server = await createServer({
         preloadedTools,
+        // Agent row, then global row, then deployment env. A blank agent row
+        // resolves to "unset" for that agent.
+        enabledTools:
+          configs.find((config) => config.key === "SWARM_ENABLED_TOOLS")?.value ??
+          process.env.SWARM_ENABLED_TOOLS,
         scriptsOnly: resolveScriptsOnlyMode({
           env: process.env.SCRIPTS_ONLY_MCP,
           configValue,

package/src/http/onboarding.ts

@@ -21,6 +21,7 @@ import {
 } from "../be/onboarding";
 import { assertUrlSafe, publicEndpointSsrfOptions } from "../oauth/mcp-wrapper";
 import { ProviderNameSchema } from "../types";
+import { getOpenRouterAttributionHeaders } from "../utils/openrouter-base-url";
 import { ensureConfigAdmin } from "./config";
 import { scheduleIntegrationsReload } from "./core";
 import { route } from "./route-def";
@@ -255,6 +256,7 @@ async function handleMemoryProbe(body: OnboardingMemoryRequest): Promise<Onboard
     const client = new OpenAI({
       baseURL: endpoint.toString(),
       apiKey,
+      defaultHeaders: getOpenRouterAttributionHeaders(endpoint.toString()),
       timeout: 15_000,
       maxRetries: 0,
       fetchOptions: { redirect: "manual" },

package/src/http/script-connections.ts

@@ -26,6 +26,7 @@ import {
   type ConnectionAuthSummary,
   connectionAuthInputFromFlat,
   connectionAuthSummary,
+  deleteScriptConnection,
   findCredentialBindingByIdentity,
   getCredentialBindingById,
   getScriptConnectionById,
@@ -554,6 +555,27 @@ const setConnectionEnabledRoute = route({
   rbac: { permission: "script-connection.manage" },
 });
 
+const deleteConnectionRoute = route({
+  method: "delete",
+  path: "/api/script-connections/{id}",
+  pattern: ["api", "script-connections", null],
+  operationId: "script_connections_delete",
+  summary: "Delete a script connection",
+  description:
+    "Hard-deletes the connection, its auto-managed credential binding, and any derived inline secret it owns.",
+  tags: ["Script Connections"],
+  params: idParamsSchema,
+  responses: {
+    200: {
+      description: "Script connection deleted",
+      schema: z.object({ deleted: z.literal(true), id: z.string() }),
+    },
+    403: { description: "Only the lead agent can manage script connections" },
+    404: { description: "Script connection not found" },
+  },
+  rbac: { permission: "script-connection.manage" },
+});
+
 const listCredentialBindingsRoute = route({
   method: "get",
   path: "/api/credential-bindings",
@@ -2111,6 +2133,19 @@ export async function handleScriptConnections(
     return true;
   }
 
+  if (deleteConnectionRoute.match(req.method, pathSegments)) {
+    const parsed = await deleteConnectionRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureConnectionAdmin(req, res, agentId))) return true;
+    const deleted = await deleteScriptConnection(parsed.params.id);
+    if (!deleted) {
+      jsonError(res, "Script connection not found.", 404);
+      return true;
+    }
+    deleteConnectionRoute.respond(res, 200, { deleted: true, id: deleted.id });
+    return true;
+  }
+
   if (listCredentialBindingsRoute.match(req.method, pathSegments)) {
     const includeManaged = queryParams.get("includeManaged") === "true";
     listCredentialBindingsRoute.respond(res, 200, {

package/src/providers/acp-targets.ts

@@ -2,6 +2,7 @@ import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { normalizeGrokModel } from "@desplega/model-catalog";
+import type { Config } from "@opencode-ai/sdk";
 import { clampContextPercent, getContextWindowSize } from "../utils/context-window";
 import {
   ACP_TARGET_IDS,
@@ -9,6 +10,7 @@ import {
   getAcpTargetCatalogEntry,
   isAcpTarget,
 } from "./acp-target-catalog";
+import { applyOpenRouterBaseUrlOverride } from "./opencode-adapter";
 import { applyReasoningEffort } from "./reasoning-effort";
 import type { CostData, CostModelUsage, ProviderEvent, ProviderSessionConfig } from "./types";
 
@@ -124,8 +126,8 @@ function configuredOptions(config: ProviderSessionConfig): Record<string, string
   return options;
 }
 
-function withModelInJsonEnv(env: Record<string, string>, key: string, model: string): void {
-  if (!model.trim()) return;
+function withOpencodeConfig(env: Record<string, string>, model: string): void {
+  const key = "OPENCODE_CONFIG_CONTENT";
   let value: Record<string, unknown> = {};
   const existing = env[key];
   if (existing) {
@@ -138,7 +140,9 @@ function withModelInJsonEnv(env: Record<string, string>, key: string, model: str
       console.warn(`\x1b[33m[acp]\x1b[0m Replacing invalid ${key} JSON for model fallback`);
     }
   }
-  env[key] = JSON.stringify({ ...value, model: model.trim() });
+  if (model.trim()) value.model = model.trim();
+  applyOpenRouterBaseUrlOverride(value as Config, env);
+  env[key] = JSON.stringify(value);
 }
 
 function parseCommand(command: string, args: string | undefined): string[] {
@@ -203,7 +207,8 @@ const opencodeTargetProfile: AcpTargetProfile = {
     const env = baseTargetEnv(config);
     const entry = getAcpTargetCatalogEntry("opencode");
     copyEnvKeys(config, env, entry.envKeys);
-    withModelInJsonEnv(env, "OPENCODE_CONFIG_CONTENT", config.model);
+    copyEnvKeys(config, env, ["OPENROUTER_APP_ATTRIBUTION"]);
+    withOpencodeConfig(env, config.model);
     return env;
   },
   configuredOptions,
@@ -248,7 +253,7 @@ const geminiTargetProfile: AcpTargetProfile = {
 /**
  * Copilot CLI has no system-prompt flag. Under `--acp` it reads custom
  * instructions from the git root, the cwd, and every directory listed in
- * COPILOT_CUSTOM_INSTRUCTIONS_DIRS. Verified against 1.0.93: from those extra
+ * COPILOT_CUSTOM_INSTRUCTIONS_DIRS. Verified against 1.0.94: from those extra
  * directories it loads `.github/instructions/*.instructions.md`, but not
  * `AGENTS.md`. So the swarm prompt goes into a per-task directory outside the
  * repo, and the repo's own AGENTS.md is never touched.

package/src/providers/amp-adapter.ts

@@ -44,7 +44,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1791403257-g05ffa9";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1791547250-gb79b2a";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/providers/claude-adapter.ts

@@ -34,12 +34,14 @@ import {
 import { withFileLock } from "../utils/file-lock";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import { swarmRuntimeInstanceId } from "../utils/multi-runtime";
+import { getOpenRouterAttributionHeaders } from "../utils/openrouter-base-url";
 import {
   detachedProcessGroup,
   registerProcessGroup,
   terminateProcessGroup,
 } from "../utils/process-group";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { ClaudeBackgroundKeepalive } from "./claude-background-keepalive";
 import { normalizeClaudeMessage } from "./claude-session-events";
 import { resolveSlashSkillPrompt } from "./codex-skill-resolver";
 import { CTX_MODE_NUDGE_EVERY } from "./ctx-mode-env";
@@ -738,6 +740,30 @@ export function buildClaudeCodeRuntimeEnv(
   };
 }
 
+/**
+ * `ANTHROPIC_CUSTOM_HEADERS` ("Name: value" per line) with OpenRouter app
+ * attribution appended, when `ANTHROPIC_BASE_URL` points at openrouter.ai.
+ * The operator's lines are kept in order (they may carry gateway
+ * credentials); only lines naming one of our headers are replaced. Returns
+ * `{}` when nothing changes, so the inherited value stays byte-identical.
+ *
+ * Exported for unit testing.
+ */
+export function claudeOpenRouterAttributionEnv(env: Record<string, string | undefined>): {
+  ANTHROPIC_CUSTOM_HEADERS?: string;
+} {
+  const headers = getOpenRouterAttributionHeaders(env.ANTHROPIC_BASE_URL ?? "", env);
+  const names = new Set(Object.keys(headers).map((name) => name.toLowerCase()));
+  if (names.size === 0) return {};
+  const kept = (env.ANTHROPIC_CUSTOM_HEADERS ?? "").split("\n").filter((line) => {
+    const colon = line.indexOf(":");
+    const name = colon === -1 ? "" : line.slice(0, colon).trim().toLowerCase();
+    return line.trim() !== "" && !names.has(name);
+  });
+  const ours = Object.entries(headers).map(([name, value]) => `${name}: ${value}`);
+  return { ANTHROPIC_CUSTOM_HEADERS: [...kept, ...ours].join("\n") };
+}
+
 export function buildClaudeSessionEnvironment(
   config: ProviderSessionConfig,
   model: string,
@@ -751,6 +777,7 @@ export function buildClaudeSessionEnvironment(
     env: {
       ENABLE_PROMPT_CACHING_1H: "1",
       ...sourceEnv,
+      ...claudeOpenRouterAttributionEnv(sourceEnv),
       ...buildClaudeCodeRuntimeEnv(sourceEnv),
       ...buildClaudeCodeOtelEnv(sourceEnv),
       ...(reasoningApplication.kind === "claude-env" ? reasoningApplication.env : {}),
@@ -878,6 +905,8 @@ class ClaudeSession implements ProviderSession {
   private lastAssistantText = "";
   /** Per-session stream-json transcript used by the parent-owned session summarizer. */
   private transcript: string[];
+  /** Keeps the session heartbeat fresh while Claude idles on background tasks. */
+  private backgroundKeepalive: ClaudeBackgroundKeepalive;
   readonly deliverSteering?: (delivery: SteerDelivery) => Promise<SteerDeliveryResult>;
 
   constructor(
@@ -899,6 +928,7 @@ class ClaudeSession implements ProviderSession {
     this.contextWindowSize = getContextWindowSize(model);
     this.systemPromptFile = systemPromptFile;
     this.transcript = [`User: ${scrubSecrets(config.prompt)}`];
+    this.backgroundKeepalive = new ClaudeBackgroundKeepalive(config);
     const cmd = this.buildCommand();
 
     console.log(
@@ -1132,6 +1162,7 @@ class ClaudeSession implements ProviderSession {
     try {
       await Promise.all([stdoutPromise, stderrPromise]);
     } finally {
+      this.backgroundKeepalive.stop();
       this.closeStdin();
     }
     await logFileHandle.end();
@@ -1200,6 +1231,7 @@ class ClaudeSession implements ProviderSession {
       if (json.type === "result") {
         this.closeStdin();
       }
+      this.backgroundKeepalive.observe(json);
 
       const normalized = normalizeClaudeMessage(json, {
         taskId: this.config.taskId,

package/src/providers/claude-background-keepalive.ts

@@ -0,0 +1,100 @@
+/**
+ * Keeps a Claude session's heartbeat fresh while it waits on background work.
+ *
+ * A Claude session that starts a `run_in_background` Bash job (or backgrounds a
+ * subagent) can end its turn and sit idle until the job's task_notification
+ * wakes it. During that wait it makes no tool calls and streams no output, so
+ * neither liveness input (the PostToolUse heartbeat and session-log ingestion)
+ * moves `active_sessions.lastHeartbeatAt`, and the stalled-task sweep classifies
+ * the live session as stale after `HEARTBEAT_STALL_STALE_HB_MIN`.
+ *
+ * Claude Code emits `system/background_tasks_changed` with the full set of live
+ * background tasks on every membership change (REPLACE semantics). While that
+ * set holds at least one non-ambient task, this pings the session heartbeat on
+ * an interval. With no background work the timer never runs, so a hung session
+ * still goes stale. A background job that never settles is bounded too: the
+ * keepalive stops once the session has emitted nothing for
+ * `BACKGROUND_KEEPALIVE_MAX_IDLE_MS`.
+ */
+
+/** Ping interval; well inside the 15-minute stale-session threshold. */
+export const BACKGROUND_KEEPALIVE_INTERVAL_MS = 60_000;
+/** Longest silent wait on background work that the keepalive will cover. */
+export const BACKGROUND_KEEPALIVE_MAX_IDLE_MS = 2 * 60 * 60_000;
+
+type BackgroundTaskEntry = { task_id?: unknown; ambient?: unknown };
+
+export interface ClaudeBackgroundKeepaliveOptions {
+  apiUrl: string;
+  apiKey: string;
+  agentId: string;
+  taskId: string;
+  intervalMs?: number;
+  maxIdleMs?: number;
+}
+
+export class ClaudeBackgroundKeepalive {
+  private liveTaskIds: string[] = [];
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private lastMessageAt = Date.now();
+  private stopped = false;
+  private readonly intervalMs: number;
+  private readonly maxIdleMs: number;
+
+  constructor(private readonly options: ClaudeBackgroundKeepaliveOptions) {
+    this.intervalMs = options.intervalMs ?? BACKGROUND_KEEPALIVE_INTERVAL_MS;
+    this.maxIdleMs = options.maxIdleMs ?? BACKGROUND_KEEPALIVE_MAX_IDLE_MS;
+  }
+
+  /** Feed every protocol message the Claude process emits. */
+  observe(message: { type?: string; subtype?: string; tasks?: unknown }): void {
+    if (this.stopped) return;
+    this.lastMessageAt = Date.now();
+    if (message.type === "system" && message.subtype === "background_tasks_changed") {
+      const tasks = Array.isArray(message.tasks) ? (message.tasks as BackgroundTaskEntry[]) : [];
+      // Ambient tasks (live-update watchers, skip_transcript tasks) are not
+      // activity; Claude Code asks hosts to leave them out of activity signals.
+      this.liveTaskIds = tasks
+        .filter((task) => task && task.ambient !== true && typeof task.task_id === "string")
+        .map((task) => task.task_id as string);
+    }
+    // Any message restarts a keepalive the idle cap stopped, while work is live.
+    if (this.liveTaskIds.length > 0) this.start();
+    else this.clearTimer();
+  }
+
+  /** Stop pinging for good; call when the session ends. */
+  stop(): void {
+    this.stopped = true;
+    this.liveTaskIds = [];
+    this.clearTimer();
+  }
+
+  private start(): void {
+    if (this.timer !== undefined) return;
+    if (!this.options.apiUrl || !this.options.taskId) return;
+    this.timer = setInterval(() => this.tick(), this.intervalMs);
+  }
+
+  private tick(): void {
+    if (Date.now() - this.lastMessageAt > this.maxIdleMs) {
+      this.clearTimer();
+      return;
+    }
+    const { apiUrl, apiKey, agentId, taskId } = this.options;
+    void fetch(`${apiUrl}/api/active-sessions/heartbeat/${encodeURIComponent(taskId)}`, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        "X-Agent-ID": agentId,
+      },
+    }).catch(() => {});
+  }
+
+  private clearTimer(): void {
+    if (this.timer === undefined) return;
+    clearInterval(this.timer);
+    this.timer = undefined;
+  }
+}

package/src/providers/claude-sdk-session.ts

@@ -29,6 +29,7 @@ import {
   cleanupTaskFile,
   runClaudeSessionSummary,
 } from "./claude-adapter";
+import { ClaudeBackgroundKeepalive } from "./claude-background-keepalive";
 import type { ClaudeProtocolMessage } from "./claude-session-events";
 import { normalizeClaudeMessage } from "./claude-session-events";
 import type {
@@ -317,8 +318,11 @@ class ClaudeSdkSession implements ProviderSession {
   private acceptingInput = true;
   private errorTracker = new SessionErrorTracker();
   private shutdownPromise: Promise<void> | undefined;
+  /** Keeps the session heartbeat fresh while Claude idles on background tasks. */
+  private backgroundKeepalive: ClaudeBackgroundKeepalive;
 
   constructor(private options: CreateClaudeSdkSessionOptions) {
+    this.backgroundKeepalive = new ClaudeBackgroundKeepalive(options.config);
     this.model = options.model;
     this.contextWindowSize = getContextWindowSize(options.model);
     this.transcript = [`User: ${scrubSecrets(options.config.prompt)}`];
@@ -406,6 +410,7 @@ class ClaudeSdkSession implements ProviderSession {
 
   private handleMessage(message: SDKMessage): boolean {
     const json = message as unknown as ClaudeProtocolMessage;
+    this.backgroundKeepalive.observe(json);
     const normalized = normalizeClaudeMessage(json, {
       taskId: this.options.config.taskId,
       agentId: this.options.config.agentId,
@@ -514,6 +519,7 @@ class ClaudeSdkSession implements ProviderSession {
         this.emit({ type: "error", message, category: "sdk_transport" });
       }
     } finally {
+      this.backgroundKeepalive.stop();
       this.acceptingInput = false;
       this.input.close();
       if (this.aborted) {

package/src/providers/codex-adapter.ts

@@ -147,6 +147,8 @@ export type ThreadEvent =
       usage?: Usage;
     }
   | { type: "turn.interrupted"; usage?: Usage }
+  /** Latest single-request usage: a context-window snapshot, not billable usage. */
+  | { type: "context.updated"; usage: Usage; contextWindow?: number }
   | { type: "error"; message: string; codexErrorInfo?: string | null; willRetry?: boolean };
 
 interface CodexThread {
@@ -833,8 +835,25 @@ class AppServerCodexThread implements CodexThread {
         }
         break;
       case "thread/tokenUsage/updated": {
-        const tokenUsage = params.tokenUsage as { total?: unknown } | undefined;
+        const tokenUsage = params.tokenUsage as
+          | { total?: unknown; last?: unknown; modelContextWindow?: unknown }
+          | undefined;
+        // `total` is cumulative for the thread and drives cost accounting at
+        // turn end. `last` is the most recent model request, which is the
+        // only figure that reflects what currently sits in the context window.
         this.latestTotalUsage = normalizeUsage(tokenUsage?.total);
+        const last = normalizeUsage(tokenUsage?.last);
+        if (last) {
+          push({
+            type: "context.updated",
+            usage: last,
+            contextWindow:
+              typeof tokenUsage?.modelContextWindow === "number" &&
+              tokenUsage.modelContextWindow > 0
+                ? tokenUsage.modelContextWindow
+                : undefined,
+          });
+        }
         break;
       }
       case "error": {
@@ -1394,6 +1413,9 @@ export class CodexSession implements ProviderSession {
       case "turn.interrupted":
         this.accountUsage(event.usage);
         break;
+      case "context.updated":
+        this.emitContextUsage(event.usage, event.contextWindow ?? this.contextWindow);
+        break;
       case "error": {
         const { message } = this.formatTerminalError(event.message, event.codexErrorInfo);
         if (event.willRetry === true) {
@@ -1420,7 +1442,12 @@ export class CodexSession implements ProviderSession {
             this.accumulatedUsage.reasoning_output_tokens + usage.reasoning_output_tokens,
         }
       : usage;
+    // No context_usage here: a turn's usage sums every model request in the
+    // turn, so it measures consumption, not window occupancy. Context comes
+    // from the per-request `context.updated` snapshots instead.
+  }
 
+  private emitContextUsage(usage: Usage, contextWindow: number): void {
     // Codex input tokens already include the cached read and write subsets.
     // Passing either subset again would inflate context usage.
     const contextUsed = computeContextUsedUnified({
@@ -1432,8 +1459,8 @@ export class CodexSession implements ProviderSession {
     this.emit({
       type: "context_usage",
       contextUsedTokens: contextUsed,
-      contextTotalTokens: this.contextWindow,
-      contextPercent: clampContextPercent(contextUsed, this.contextWindow) ?? 0,
+      contextTotalTokens: contextWindow,
+      contextPercent: clampContextPercent(contextUsed, contextWindow) ?? 0,
       outputTokens: usage.output_tokens,
       contextFormula: CONTEXT_FORMULA,
     });