@desplega.ai/agent-swarm 2.5.3 → 2.5.4

package/src/http/workflows.ts

@@ -5,6 +5,7 @@ import { resolveHttpAuditUserId } from "../be/audit-user";
 import {
   createWorkflow,
   deleteWorkflow,
+  getDbClient,
   getWorkflow,
   getWorkflowRun,
   getWorkflowRunStepsByRunId,
@@ -15,6 +16,13 @@ import {
   type updateWorkflow,
   withFavoriteFlags,
 } from "../be/db";
+import {
+  assertWorkflowIdempotencyKeyUnused,
+  IdempotencyKeyTakenError,
+  recordAcceptedWorkflowOperation,
+  type WorkflowIdempotencyClaim,
+  workflowRequestFingerprint,
+} from "../be/db/workflow-idempotency";
 import { getWorkflowRunParent } from "../be/db/workflow-runs";
 import {
   AssetKeySchema,
@@ -46,6 +54,11 @@ import { cancelWorkflowRun, retryFailedRun } from "../workflows/resume";
 import { handleWebhookTrigger, WebhookError } from "../workflows/triggers";
 import { snapshotAndUpdateWorkflow } from "../workflows/version";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
+import {
+  idempotencyKeyHeader,
+  readIdempotencyKey,
+  replayAcceptedOperation,
+} from "./idempotency-key";
 import { route } from "./route-def";
 import { jsonError, parseBody, triggerSchemaErrorResponse } from "./utils";
 
@@ -142,6 +155,7 @@ const createWorkflowRoute = route({
   pattern: ["api", "workflows"],
   summary: "Create a new workflow",
   tags: ["Workflows"],
+  headers: idempotencyKeyHeader("creates one workflow"),
   body: z.object({
     name: z.string().min(1),
     key: AssetKeySchema.optional(),
@@ -159,7 +173,9 @@ const createWorkflowRoute = route({
   }),
   responses: {
     201: { description: "Workflow created", schema: WorkflowSaveResponseSchema },
-    400: { description: "Invalid definition" },
+    400: { description: "Invalid definition, or a malformed Idempotency-Key" },
+    409: { description: "Idempotency-Key was already used for a different request" },
+    410: { description: "The workflow created under this Idempotency-Key was deleted" },
   },
 });
 
@@ -272,16 +288,21 @@ const triggerWorkflowRoute = route({
   path: "/api/workflows/{id}/trigger",
   pattern: ["api", "workflows", null, "trigger"],
   summary: "Trigger a workflow execution",
+  description:
+    "With an `Idempotency-Key`, a retry returns the accepted run's `runId` and `skipped` without starting, resuming or waiting for anything, even after the workflow was disabled or edited and whatever state the run is in now.",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
+  headers: idempotencyKeyHeader("starts one run"),
   responses: {
     201: {
       description: "Workflow run started (or skipped if cooldown active)",
       schema: z.object({ runId: z.string(), skipped: z.boolean() }),
     },
-    400: { description: "Workflow is disabled" },
+    400: { description: "Workflow is disabled, or a malformed Idempotency-Key" },
     401: { description: "Unauthorized" },
     404: { description: "Workflow not found" },
+    409: { description: "Idempotency-Key was already used for a different request" },
+    410: { description: "The workflow triggered under this Idempotency-Key was deleted" },
   },
 });
 
@@ -574,8 +595,21 @@ export async function handleWorkflows(
   }
 
   if (createWorkflowRoute.match(req.method, pathSegments)) {
+    const idempotency = readIdempotencyKey(req, res, myAgentId);
+    if (idempotency === null) return true;
     const parsed = await createWorkflowRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    const claim: WorkflowIdempotencyClaim | undefined = idempotency && {
+      ...idempotency,
+      operation: "workflow.create",
+      targetId: "",
+      fingerprint: workflowRequestFingerprint("workflow.create", parsed.body),
+    };
+    const replayCreate = (body: unknown) =>
+      createWorkflowRoute.respond(res, 201, body as z.input<typeof WorkflowSaveResponseSchema>);
+    // Before validation: a retry gets the original result even if the same
+    // definition would no longer validate.
+    if (claim && (await replayAcceptedOperation(res, claim, replayCreate))) return true;
 
     // Validate definition structure
     const validation = validateDefinition(parsed.body.definition, getExecutorRegistry());
@@ -603,27 +637,55 @@ export async function handleWorkflows(
       throw error;
     }
 
-    const workflow = await createWorkflow(
-      {
-        key,
-        name: parsed.body.name,
-        description: parsed.body.description,
-        definition: parsed.body.definition,
-        triggers: parsed.body.triggers,
-        cooldown: parsed.body.cooldown,
-        input: parsed.body.input,
-        triggerSchema: parsed.body.triggerSchema,
-        params: parsed.body.params,
-        requiredParams: parsed.body.requiredParams,
-        requires: parsed.body.requires,
-        dir: parsed.body.dir,
-        vcsRepo: parsed.body.vcsRepo,
-        createdByAgentId: myAgentId ?? undefined,
-        createdBy: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
-      },
-      "api",
-    );
-    createWorkflowRoute.respond(res, 201, await withSaveWarnings(workflow));
+    const data: Parameters<typeof createWorkflow>[0] = {
+      key,
+      name: parsed.body.name,
+      description: parsed.body.description,
+      definition: parsed.body.definition,
+      triggers: parsed.body.triggers,
+      cooldown: parsed.body.cooldown,
+      input: parsed.body.input,
+      triggerSchema: parsed.body.triggerSchema,
+      params: parsed.body.params,
+      requiredParams: parsed.body.requiredParams,
+      requires: parsed.body.requires,
+      dir: parsed.body.dir,
+      vcsRepo: parsed.body.vcsRepo,
+      createdByAgentId: myAgentId ?? undefined,
+      createdBy: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+    };
+    if (!claim) {
+      const workflow = await createWorkflow(data, "api");
+      createWorkflowRoute.respond(res, 201, await withSaveWarnings(workflow));
+      return true;
+    }
+
+    // Warnings are computed before the transaction (a readiness check may
+    // call out) and stored with the workflow, so a retry gets this snapshot,
+    // not the workflow as it is by then.
+    const warnings = await workflowSaveWarnings(parsed.body.definition, getExecutorRegistry());
+    let saved: z.input<typeof WorkflowSaveResponseSchema>;
+    try {
+      saved = await getDbClient().transaction(async () => {
+        // Before the insert: a concurrent winner's workflow holds the same name.
+        await assertWorkflowIdempotencyKeyUnused(claim);
+        const workflow = await createWorkflow(data, "api");
+        const body = warnings.length > 0 ? { ...workflow, warnings } : workflow;
+        await recordAcceptedWorkflowOperation(claim, {
+          workflowId: workflow.id,
+          status: 201,
+          body,
+        });
+        return body;
+      });
+    } catch (err) {
+      // A concurrent request with this key committed first; nothing of this one did.
+      if (err instanceof IdempotencyKeyTakenError) {
+        if (await replayAcceptedOperation(res, claim, replayCreate)) return true;
+      }
+      throw err;
+    }
+    createWorkflowRoute.respond(res, 201, saved);
     return true;
   }
 
@@ -858,8 +920,26 @@ export async function handleWorkflows(
   }
 
   if (triggerWorkflowRoute.match(req.method, pathSegments)) {
+    const idempotency = readIdempotencyKey(req, res, myAgentId);
+    if (idempotency === null) return true;
     const parsed = await triggerWorkflowRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    let claim: WorkflowIdempotencyClaim | undefined;
+    let keyedBody: Record<string, unknown> | undefined;
+    const replayTrigger = (body: unknown) =>
+      triggerWorkflowRoute.respond(res, 201, body as { runId: string; skipped: boolean });
+    if (idempotency) {
+      keyedBody = await parseBody<Record<string, unknown>>(req);
+      claim = {
+        ...idempotency,
+        operation: "workflow.trigger",
+        targetId: parsed.params.id,
+        fingerprint: workflowRequestFingerprint("workflow.trigger", keyedBody),
+      };
+      // Before the enabled, cooldown, readiness and trigger-schema checks: an
+      // accepted trigger replays even after the workflow changed.
+      if (await replayAcceptedOperation(res, claim, replayTrigger)) return true;
+    }
     const workflow = await getWorkflow(parsed.params.id);
     if (!workflow) {
       res.writeHead(404);
@@ -870,20 +950,45 @@ export async function handleWorkflows(
       jsonError(res, "Workflow is disabled", 400);
       return true;
     }
-    const body = await parseBody<Record<string, unknown>>(req);
+    // Not `??`: a JSON `null` body is a parsed body too, and reading the
+    // already-ended stream again would wait forever.
+    const body = idempotency ? keyedBody : await parseBody<Record<string, unknown>>(req);
     let runId: string;
+    let accepted: { runId: string; skipped: boolean } | undefined;
     try {
       runId = await startWorkflowExecution(workflow, body, getExecutorRegistry(), {
         triggerType: "api",
         requestedByUserId: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+        // Recorded in the run's own transaction, before the walk starts.
+        accept: claim
+          ? async (run) => {
+              const response = { runId: run.runId, skipped: run.skipped };
+              await recordAcceptedWorkflowOperation(claim, {
+                workflowId: workflow.id,
+                runId: run.runId,
+                status: 201,
+                body: response,
+              });
+              accepted = response;
+            }
+          : undefined,
       });
     } catch (err) {
       if (err instanceof TriggerSchemaError) {
         triggerSchemaErrorResponse(res, err.message, err.validationErrors);
         return true;
       }
+      // A concurrent request with this key committed its run first; this one
+      // created none and walks nothing.
+      if (claim && err instanceof IdempotencyKeyTakenError) {
+        if (await replayAcceptedOperation(res, claim, replayTrigger)) return true;
+      }
       throw err;
     }
+    if (accepted) {
+      triggerWorkflowRoute.respond(res, 201, accepted);
+      return true;
+    }
 
     // Check if skipped due to cooldown
     const run = await getWorkflowRun(runId);

package/src/prompts/context-bound-note.ts

@@ -0,0 +1,48 @@
+// Worker-side hooks do not load base-prompt, which normally registers these
+// code-default templates.
+import "./session-templates.ts";
+import { resolveTemplateAsync, resolveTemplateFromCode } from "./resolver.ts";
+
+const CONTEXT_BOUND_NOTE_TEMPLATE = "system.agent.context.bound_note";
+
+/**
+ * `contextShare` for the note: " (21% of the 1,000,000-token window)", or ""
+ * when the model's window is unknown. Never a percent of the 200k fallback.
+ */
+function contextShare(contextTokens: number, model: string | undefined): string {
+  if (!model) return "";
+  try {
+    // Lazy and synchronous: the catalog snapshot is large and the Claude hook
+    // process loads this module on every tool call, but renders the note at
+    // most once. Sync so in-process sessions render no later than before.
+    const { clampContextPercent, getKnownContextWindowSize } =
+      require("../utils/context-window.ts") as typeof import("../utils/context-window.ts");
+    const window = getKnownContextWindowSize(model);
+    const percent = clampContextPercent(contextTokens, window);
+    if (!window || percent === null) return "";
+    return ` (${Math.round(percent)}% of the ${window.toLocaleString("en-US")}-token window)`;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Render the one-time context-bound note. `model` is the session's model, for
+ * the window share. Returns "" when an operator disabled the template; falls
+ * back to the code default if resolution fails.
+ */
+export async function renderContextBoundNote(
+  contextTokens: number,
+  model?: string,
+): Promise<string> {
+  const variables = {
+    contextTokens: Math.round(contextTokens).toLocaleString("en-US"),
+    contextShare: contextShare(contextTokens, model),
+  };
+  try {
+    const result = await resolveTemplateAsync(CONTEXT_BOUND_NOTE_TEMPLATE, variables);
+    return result.skipped ? "" : result.text;
+  } catch {
+    return resolveTemplateFromCode(CONTEXT_BOUND_NOTE_TEMPLATE, variables).text;
+  }
+}

package/src/prompts/session-templates.ts

@@ -202,7 +202,7 @@ agent-fs is the shared drive between agents and people. Documents (reports, dige
 Pages: only for polished artifacts shared with a wider audience or explicitly requested; see \`pages\` skill.
 A tool a person will use, with data and actions: build an app. See the \`apps\` skill.
 Link env: \`APP_URL\` for pages, \`MCP_BASE_URL\` for the API, \`AGENT_FS_LIVE_URL\` for files. Report missing variables.
-For a file anyone outside the swarm opens, use an \`agent-fs share-create\` link; \`AGENT_FS_LIVE_URL\` links are for signed-in teammates.
+Give people the live app link \`\${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>\`. Make an \`agent-fs share-create\` link only when the requester asks for one or the reader has no agent-fs login.
 `,
   variables: [],
   category: "system",
@@ -353,6 +353,30 @@ Task: {{task}}{{progressLine}}
   category: "system",
 });
 
+/**
+ * One-time note injected into a worker session once its latest main-thread
+ * request crosses CONTEXT_BOUND_NOTE_TOKENS (`renderContextBoundNote`, via
+ * `src/hooks/context-bound-note.ts`).
+ */
+registerTemplate({
+  eventType: "system.agent.context.bound_note",
+  header: "",
+  defaultBody:
+    "Context is {{contextTokens}} tokens{{contextShare}}. Keep this task bounded: finish the current step, store-progress, and complete or defer instead of starting new exploration.",
+  variables: [
+    {
+      name: "contextTokens",
+      description: "Prompt size of the latest request (input + cache read + cache write tokens)",
+    },
+    {
+      name: "contextShare",
+      description:
+        'How full the model\'s context window is, e.g. " (21% of the 1,000,000-token window)". Empty when the window is unknown',
+    },
+  ],
+  category: "system",
+});
+
 /**
  * First message of a cursor session on the first-message path. Cursor keeps
  * its own system prompt there, so the swarm's rides on top of the task prompt.

package/src/providers/amp-adapter.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "nod
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { contextBoundNoteThreshold, createContextBoundNote } from "../hooks/context-bound-note";
 import {
   type AmpMode,
   type AmpModelSelection,
@@ -44,7 +45,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.1792756861-g6187a2";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1792844927-g360c96";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";
@@ -442,6 +443,8 @@ interface QueuedSteer {
    * answer from the model that received it settles the steer.
    */
   receiver?: string | null;
+  /** The swarm's own note: rides a tool result or is dropped, never replayed as a new turn. */
+  internal?: boolean;
   resolve: (result: SteerDeliveryResult) => void;
 }
 
@@ -486,6 +489,8 @@ class AmpSession implements ProviderSession {
   private steeringSeq = 0;
   /** Accepted steering not yet consumed, by inbox file name. Each settles exactly once. */
   private steers = new Map<string, QueuedSteer>();
+  /** Fed each top-level request's prompt size; queues the one-time context-bound note. */
+  private readonly observeContextBound: (contextTokens: number | undefined) => Promise<void>;
 
   constructor(
     private proc: Bun.Subprocess<"pipe", "pipe", "pipe">,
@@ -523,6 +528,15 @@ class AmpSession implements ProviderSession {
         });
       }
     };
+    // The plugin's `tool.result` hook carries queued steering mid-turn; a note
+    // no tool result took is dropped at turn end (`onTurnEnd`).
+    this.observeContextBound = createContextBoundNote({
+      threshold: contextBoundNoteThreshold(run.env),
+      // A mode names no model in advance, so only a pinned model gets a window share.
+      model: () => run.selection.pin,
+      canDeliver: () => !this.inputClosed && !this.aborted,
+      inject: (note) => this.queueSteering(note, true),
+    });
     this.completion = this.runSession(prompt);
   }
 
@@ -553,13 +567,13 @@ class AmpSession implements ProviderSession {
    * check and the rename, no turn end can drain the inbox and close input, so
    * a message is either visible to the next drain or refused.
    */
-  private queueSteering(text: string): Promise<SteerDeliveryResult> {
+  private queueSteering(text: string, internal = false): Promise<SteerDeliveryResult> {
     const name = `${String(++this.steeringSeq).padStart(6, "0")}.json`;
     const temp = join(this.run.steeringInbox, `.${name}.tmp`);
     writeFileSync(temp, JSON.stringify(text), { mode: 0o600 });
     renameSync(temp, join(this.run.steeringInbox, name));
     return new Promise((resolve) => {
-      this.steers.set(name, { text, via: "inbox", resolve });
+      this.steers.set(name, { text, via: "inbox", internal, resolve });
     });
   }
 
@@ -631,8 +645,8 @@ class AmpSession implements ProviderSession {
    * Claim the messages no tool result carried, with the plugin's rename
    * protocol (`.json -> .stdin`). They stay open until Amp echoes them.
    */
-  private takeSteering(): { name: string; text: string }[] {
-    const taken: { name: string; text: string }[] = [];
+  private takeSteering(): { name: string; text: string; internal?: boolean }[] {
+    const taken: { name: string; text: string; internal?: boolean }[] = [];
     for (const [name, steer] of [...this.steers].sort(([a], [b]) => a.localeCompare(b))) {
       if (steer.via !== "inbox") continue;
       try {
@@ -641,7 +655,7 @@ class AmpSession implements ProviderSession {
         continue; // The plugin took it.
       }
       steer.via = "stdin";
-      taken.push({ name, text: steer.text });
+      taken.push({ name, text: steer.text, internal: steer.internal });
     }
     return taken;
   }
@@ -704,11 +718,16 @@ class AmpSession implements ProviderSession {
   /**
    * A top-level assistant message with no tool call ends the turn. Steering
    * that arrived after the last tool result reached no hook, so it goes in as
-   * the next user message and starts another turn.
+   * the next user message and starts another turn. The swarm's own note is
+   * withdrawn instead: it must not start a turn.
    */
   private onTurnEnd(): void {
     if (this.inputClosed) return;
-    for (const { name, text } of this.takeSteering()) {
+    for (const { name, text, internal } of this.takeSteering()) {
+      if (internal) {
+        this.settleSteer(name, { delivered: false, reason: "no tool result carried the note" });
+        continue;
+      }
       this.writeInput(text).catch((error) => {
         this.settleSteer(name, {
           delivered: false,
@@ -817,6 +836,9 @@ class AmpSession implements ProviderSession {
       });
       // The window is not in the stream; the final snapshot after the export carries it.
       if (used > 0) this.emitContext(used, output, null);
+      // Only when a tool result follows to carry the note; the turn end drops
+      // a note no tool result carried.
+      if (topLevel && calledTool) void this.observeContextBound(input + cacheRead + cacheCreation);
     }
     if (topLevel && !calledTool && message.stop_reason !== "tool_use") this.onTurnEnd();
   }

package/src/providers/claude-adapter.ts

@@ -17,6 +17,11 @@ import { dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { deriveDefaultRoute, routeCredentialStatus, routeUnsetEnv } from "@desplega/model-routing";
 import { type Span, trace } from "@opentelemetry/api";
+import {
+  contextBoundNoteMarkerPath,
+  contextStatePath,
+  recordContextState,
+} from "../hooks/context-bound-note";
 import {
   type RunStopHookSessionSummaryOpts,
   runStopHookSessionSummarySubprocess,
@@ -130,10 +135,17 @@ async function writeTaskFile(key: string | number, data: TaskFileData): Promise<
 }
 
 export async function cleanupTaskFile(key: string | number): Promise<void> {
-  try {
-    await unlink(getTaskFilePath(key));
-  } catch {
-    // File might already be deleted or never created
+  const taskFilePath = getTaskFilePath(key);
+  for (const path of [
+    taskFilePath,
+    contextStatePath(taskFilePath),
+    contextBoundNoteMarkerPath(taskFilePath),
+  ]) {
+    try {
+      await unlink(path);
+    } catch {
+      // File might already be deleted or never created
+    }
   }
 }
 
@@ -909,6 +921,8 @@ class ClaudeSession implements ProviderSession {
   private appliedReasoningEffort: ReasoningEffort | null;
   /** Last non-empty assistant text seen; surfaced as ProviderResult.output — same pattern as pi-mono/claude-managed. */
   private lastAssistantText = "";
+  /** Last value written to the context state file read by the context-bound note hook. */
+  private lastContextTokens: number | undefined;
   /** 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. */
@@ -1263,6 +1277,17 @@ class ClaudeSession implements ProviderSession {
       if (normalized.contextWindowSize) this.contextWindowSize = normalized.contextWindowSize;
       if (normalized.cost) setCost(normalized.cost);
       if (normalized.assistantText) this.lastAssistantText = normalized.assistantText;
+      if (
+        normalized.requestContextTokens !== undefined &&
+        normalized.requestContextTokens !== this.lastContextTokens
+      ) {
+        this.lastContextTokens = normalized.requestContextTokens;
+        recordContextState(
+          getTaskFilePath(this.taskFileKey),
+          normalized.requestContextTokens,
+          this.model,
+        );
+      }
       this.transcript.push(...normalized.transcriptEntries);
       for (const event of normalized.events) this.emit(event);
 

package/src/providers/claude-managed-adapter.ts

@@ -56,6 +56,7 @@ import type {
   BetaManagedAgentsSessionEvent as SessionEvent,
 } from "@anthropic-ai/sdk/resources/beta/sessions";
 
+import { contextBoundNoteThreshold, createContextBoundNote } from "../hooks/context-bound-note";
 import { checkToolLoop } from "../hooks/tool-loop-detection";
 import {
   CONTEXT_FORMULA,
@@ -268,6 +269,12 @@ class ClaudeManagedSession implements ProviderSession {
   private readonly taskId: string | null;
   private aborted = false;
   private settled = false;
+  /** Prompt size of the latest model request: input + cache read + cache write. */
+  private lastRequestContextTokens: number | undefined;
+  /** Fed the latest request's prompt size on each tool call; steers the one-time context-bound note. */
+  private readonly observeContextBound: (contextTokens: number | undefined) => Promise<void>;
+  /** Tool calls the stream started and has not returned a result for. */
+  private readonly openToolCalls = new Set<string>();
 
   constructor(
     client: ManagedAgentsClient,
@@ -286,6 +293,14 @@ class ClaudeManagedSession implements ProviderSession {
     this.completionPromise = new Promise<ProviderResult>((resolve) => {
       this.resolveCompletion = resolve;
     });
+    this.observeContextBound = createContextBoundNote({
+      threshold: contextBoundNoteThreshold(config.env ?? process.env),
+      model: () => this.cost.model,
+      // A message with no tool call left to return, or after idle or abort,
+      // would start another turn.
+      canDeliver: () => !this.settled && !this.aborted && this.openToolCalls.size > 0,
+      inject: (note) => this.deliverSteering({ mode: "steer", text: note }),
+    });
 
     // Phase 5: adapter-side swarm hooks. Lower-latency cancellation poll,
     // tool-loop detection (the handler also calls `checkToolLoop` on
@@ -497,6 +512,11 @@ class ClaudeManagedSession implements ProviderSession {
       case "agent.tool_use": {
         const tu = event as BetaManagedAgentsAgentToolUseEvent;
         this.runToolLoopCheck(tu.name, tu.input);
+        // Only on tool calls: a message after the final reply would start another
+        // turn. The stream can send the call before its request ends, so this may
+        // read the previous request: at most one request late.
+        this.openToolCalls.add(tu.id);
+        void this.observeContextBound(this.lastRequestContextTokens);
         this.emit({
           type: "tool_start",
           toolCallId: tu.id,
@@ -509,6 +529,8 @@ class ClaudeManagedSession implements ProviderSession {
         const tu = event as BetaManagedAgentsAgentMCPToolUseEvent;
         const fqToolName = `${tu.mcp_server_name}:${tu.name}`;
         this.runToolLoopCheck(fqToolName, tu.input);
+        this.openToolCalls.add(tu.id);
+        void this.observeContextBound(this.lastRequestContextTokens);
         this.emit({
           type: "tool_start",
           toolCallId: tu.id,
@@ -519,6 +541,7 @@ class ClaudeManagedSession implements ProviderSession {
       }
       case "agent.tool_result": {
         const tr = event as BetaManagedAgentsAgentToolResultEvent;
+        this.openToolCalls.delete(tr.tool_use_id);
         this.emit({
           type: "tool_end",
           toolCallId: tr.tool_use_id,
@@ -533,6 +556,7 @@ class ClaudeManagedSession implements ProviderSession {
       }
       case "agent.mcp_tool_result": {
         const tr = event as BetaManagedAgentsAgentMCPToolResultEvent;
+        this.openToolCalls.delete(tr.mcp_tool_use_id);
         this.emit({
           type: "tool_end",
           toolCallId: tr.mcp_tool_use_id,
@@ -571,6 +595,8 @@ class ClaudeManagedSession implements ProviderSession {
       case "span.model_request_end": {
         const sp = event as BetaManagedAgentsSpanModelRequestEndEvent;
         const usage = sp.model_usage;
+        this.lastRequestContextTokens =
+          usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
         this.cost.inputTokens = (this.cost.inputTokens ?? 0) + usage.input_tokens;
         this.cost.outputTokens = (this.cost.outputTokens ?? 0) + usage.output_tokens;
         this.cost.cacheReadTokens =

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

@@ -9,6 +9,7 @@ import {
   type SpawnedProcess,
   type SpawnOptions,
 } from "@anthropic-ai/claude-agent-sdk";
+import { recordContextState } from "../hooks/context-bound-note";
 import type { RunStopHookSessionSummaryOpts } from "../hooks/hook";
 import { getContextWindowSize } from "../utils/context-window";
 import {
@@ -316,6 +317,8 @@ class ClaudeSdkSession implements ProviderSession {
   private contextWindowSize: number;
   private transcript: string[];
   private lastAssistantText = "";
+  /** Last value written to the context state file read by the context-bound note hook. */
+  private lastContextTokens: number | undefined;
   private lastCost: CostData | undefined;
   private aborted = false;
   private abortReason = "cancelled";
@@ -434,6 +437,13 @@ class ClaudeSdkSession implements ProviderSession {
     if (normalized.contextWindowSize) this.contextWindowSize = normalized.contextWindowSize;
     if (normalized.cost) this.lastCost = normalized.cost;
     if (normalized.assistantText) this.lastAssistantText = normalized.assistantText;
+    if (
+      normalized.requestContextTokens !== undefined &&
+      normalized.requestContextTokens !== this.lastContextTokens
+    ) {
+      this.lastContextTokens = normalized.requestContextTokens;
+      recordContextState(this.options.taskFilePath, normalized.requestContextTokens, this.model);
+    }
     this.transcript.push(...normalized.transcriptEntries);
     for (const event of normalized.events) this.emit(event);
     trackErrorFromJson(json, this.errorTracker);

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

@@ -60,6 +60,11 @@ export type NormalizedClaudeMessage = {
   contextWindowSize?: number;
   cost?: CostData;
   assistantText?: string;
+  /**
+   * Prompt size of the latest main-thread request: input + cache read + cache
+   * write tokens. Unset for subagent messages and messages without usage.
+   */
+  requestContextTokens?: number;
   isResult: boolean;
 };
 
@@ -150,6 +155,7 @@ export function normalizeClaudeMessage(
   let model: string | undefined;
   let contextWindowSize: number | undefined;
   let assistantText: string | undefined;
+  let requestContextTokens: number | undefined;
 
   if (json.type === "system" && json.subtype === "init" && json.session_id) {
     sessionId = json.session_id;
@@ -227,6 +233,12 @@ export function normalizeClaudeMessage(
         outputTokens: usage.output_tokens ?? 0,
         contextFormula: CONTEXT_FORMULA,
       });
+      if (!json.parent_tool_use_id) {
+        requestContextTokens =
+          (usage.input_tokens ?? 0) +
+          (usage.cache_read_input_tokens ?? 0) +
+          (usage.cache_creation_input_tokens ?? 0);
+      }
     }
   }
 
@@ -247,6 +259,7 @@ export function normalizeClaudeMessage(
     contextWindowSize,
     cost,
     assistantText,
+    requestContextTokens,
     isResult: json.type === "result",
   };
 }