@anthropic-ai/sdk 0.110.0 → 0.112.0

package/resources/beta/tunnels/tunnels.mjs

@@ -0,0 +1,176 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { APIResource } from "../../../core/resource.mjs";
+import * as CertificatesAPI from "./certificates.mjs";
+import { Certificates, } from "./certificates.mjs";
+import { PageCursor } from "../../../core/pagination.mjs";
+import { buildHeaders } from "../../../internal/headers.mjs";
+import { path } from "../../../internal/utils/path.mjs";
+export class Tunnels extends APIResource {
+    constructor() {
+        super(...arguments);
+        this.certificates = new CertificatesAPI.Certificates(this._client);
+    }
+    /**
+     * The Tunnels API is in research preview. It requires the
+     * `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
+     * deprecation period. It supersedes the Admin API endpoints at
+     * `/v1/organizations/tunnels`, which remain available during a migration window.
+     *
+     * Creates a tunnel. Creation allocates a fresh hostname and provisions the tunnel;
+     * it is not idempotent. The new tunnel rejects MCP traffic until at least one CA
+     * certificate is added.
+     *
+     * @example
+     * ```ts
+     * const betaTunnel = await client.beta.tunnels.create();
+     * ```
+     */
+    create(params, options) {
+        const { betas, ...body } = params;
+        return this._client.post('/v1/tunnels?beta=true', {
+            body,
+            ...options,
+            headers: buildHeaders([
+                { 'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString() },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * The Tunnels API is in research preview. It requires the
+     * `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
+     * deprecation period. It supersedes the Admin API endpoints at
+     * `/v1/organizations/tunnels`, which remain available during a migration window.
+     *
+     * Fetches a tunnel by ID.
+     *
+     * @example
+     * ```ts
+     * const betaTunnel = await client.beta.tunnels.retrieve(
+     *   'tunnel_id',
+     * );
+     * ```
+     */
+    retrieve(tunnelID, params = {}, options) {
+        const { betas } = params ?? {};
+        return this._client.get(path `/v1/tunnels/${tunnelID}?beta=true`, {
+            ...options,
+            headers: buildHeaders([
+                { 'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString() },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * The Tunnels API is in research preview. It requires the
+     * `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
+     * deprecation period. It supersedes the Admin API endpoints at
+     * `/v1/organizations/tunnels`, which remain available during a migration window.
+     *
+     * Lists tunnels. Results are ordered by creation time, newest first; archived
+     * tunnels are excluded unless include_archived is set.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const betaTunnel of client.beta.tunnels.list()) {
+     *   // ...
+     * }
+     * ```
+     */
+    list(params = {}, options) {
+        const { betas, ...query } = params ?? {};
+        return this._client.getAPIList('/v1/tunnels?beta=true', (PageCursor), {
+            query,
+            ...options,
+            headers: buildHeaders([
+                { 'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString() },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * The Tunnels API is in research preview. It requires the
+     * `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
+     * deprecation period. It supersedes the Admin API endpoints at
+     * `/v1/organizations/tunnels`, which remain available during a migration window.
+     *
+     * Archives a tunnel. Archival is irreversible: every non-archived certificate on
+     * the tunnel is archived in the same operation, the hostname is retired and never
+     * re-allocated, and the tunnel token is invalidated. Retrying against an
+     * already-archived tunnel returns the existing record unchanged.
+     *
+     * @example
+     * ```ts
+     * const betaTunnel = await client.beta.tunnels.archive(
+     *   'tunnel_id',
+     * );
+     * ```
+     */
+    archive(tunnelID, params = {}, options) {
+        const { betas } = params ?? {};
+        return this._client.post(path `/v1/tunnels/${tunnelID}/archive?beta=true`, {
+            ...options,
+            headers: buildHeaders([
+                { 'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString() },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * The Tunnels API is in research preview. It requires the
+     * `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
+     * deprecation period. It supersedes the Admin API endpoints at
+     * `/v1/organizations/tunnels`, which remain available during a migration window.
+     *
+     * Reveals a tunnel's connector token. The value is fetched live on each call;
+     * Anthropic does not store it. Repeated calls return the same value until the
+     * token is rotated. Exposed as POST so the token does not appear in intermediary
+     * access logs.
+     *
+     * @example
+     * ```ts
+     * const betaTunnelToken =
+     *   await client.beta.tunnels.revealToken('tunnel_id');
+     * ```
+     */
+    revealToken(tunnelID, params = {}, options) {
+        const { betas } = params ?? {};
+        return this._client.post(path `/v1/tunnels/${tunnelID}/reveal_token?beta=true`, {
+            ...options,
+            headers: buildHeaders([
+                { 'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString() },
+                options?.headers,
+            ]),
+        });
+    }
+    /**
+     * The Tunnels API is in research preview. It requires the
+     * `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a
+     * deprecation period. It supersedes the Admin API endpoints at
+     * `/v1/organizations/tunnels`, which remain available during a migration window.
+     *
+     * Rotates a tunnel's connector token. Rotation invalidates the current token for
+     * new connections and returns a fresh value; established connections are not
+     * severed. A connector restarted after rotation must use the new value.
+     *
+     * @example
+     * ```ts
+     * const betaTunnelToken =
+     *   await client.beta.tunnels.rotateToken('tunnel_id');
+     * ```
+     */
+    rotateToken(tunnelID, params, options) {
+        const { betas, ...body } = params;
+        return this._client.post(path `/v1/tunnels/${tunnelID}/rotate_token?beta=true`, {
+            body,
+            ...options,
+            headers: buildHeaders([
+                { 'anthropic-beta': [...(betas ?? []), 'mcp-tunnels-2026-06-22'].toString() },
+                options?.headers,
+            ]),
+        });
+    }
+}
+Tunnels.Certificates = Certificates;
+//# sourceMappingURL=tunnels.mjs.map

package/resources/beta/tunnels/tunnels.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnels.mjs","sourceRoot":"","sources":["../../../src/resources/beta/tunnels/tunnels.ts"],"names":[],"mappings":"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"}

package/resources/beta/tunnels.d.mts

@@ -0,0 +1,2 @@
+export * from "./tunnels/index.mjs";
+//# sourceMappingURL=tunnels.d.mts.map

package/resources/beta/tunnels.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnels.d.mts","sourceRoot":"","sources":["../../src/resources/beta/tunnels.ts"],"names":[],"mappings":"AAEA,oCAAgC"}

package/resources/beta/tunnels.d.ts

@@ -0,0 +1,2 @@
+export * from "./tunnels/index.js";
+//# sourceMappingURL=tunnels.d.ts.map

package/resources/beta/tunnels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnels.d.ts","sourceRoot":"","sources":["../../src/resources/beta/tunnels.ts"],"names":[],"mappings":"AAEA,mCAAgC"}

package/resources/beta/tunnels.js

@@ -0,0 +1,6 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("../../internal/tslib.js");
+tslib_1.__exportStar(require("./tunnels/index.js"), exports);
+//# sourceMappingURL=tunnels.js.map

package/resources/beta/tunnels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnels.js","sourceRoot":"","sources":["../../src/resources/beta/tunnels.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,6DAAgC"}

package/resources/beta/tunnels.mjs

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+export * from "./tunnels/index.mjs";
+//# sourceMappingURL=tunnels.mjs.map

package/resources/beta/tunnels.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnels.mjs","sourceRoot":"","sources":["../../src/resources/beta/tunnels.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,oCAAgC"}

package/src/lib/tools/SessionToolRunner.ts

@@ -63,7 +63,9 @@ export interface SessionToolRunnerOptions {
   /**
    * Once the session goes idle with `stop_reason.type === "end_turn"`, the
    * runner keeps running for this many milliseconds before stopping; any new
-   * event resets the countdown and it re-arms on the next `end_turn` idle.
+   * event resets the countdown and it re-arms on the next `end_turn` idle. The
+   * countdown is deferred while a confirmation-gated call is held or still
+   * dispatching, and starts fresh once the last one resolves.
    * Defaults to {@link DEFAULT_MAX_IDLE_MS} (60s). `0` (or negative) disables
    * it — the runner then only stops on session termination or the consumer
    * breaking out / aborting.
@@ -128,9 +130,22 @@ export interface DispatchedToolCall {
    * post itself failed (typically a permanent 4xx or send-retry exhaustion)
    * and also `false` — with no `result` event ever built — for a tool name
    * this runner does not own when it deliberately posts nothing and leaves the
-   * id pending for its owner (the split-client behavior).
+   * id pending for its owner (the split-client behavior), or when the call
+   * was denied and never executed (see `confirmation`).
    */
   readonly posted: boolean;
+  /**
+   * The confirmation verdict that gated this call, if any.
+   *
+   * `'allow'` — the call required user confirmation (the server evaluated
+   * its permission to `ask`, e.g. under an `always_ask` policy) and the
+   * matching `user.tool_confirmation` approved it before the tool ran.
+   * `'deny'` — the user denied it, or the server itself evaluated the
+   * permission to `deny`; the tool was never executed and nothing was posted
+   * (`result=undefined`, `posted=false`, `isError=false`).
+   * `undefined` — the call needed no confirmation.
+   */
+  readonly confirmation: 'allow' | 'deny' | undefined;
 }
 
 /** Returns true if `ev` is a `session.status_idle` with `stop_reason` `end_turn`. */
@@ -138,6 +153,95 @@ function isEndTurnIdle(ev: { type?: string; stop_reason?: { type?: string } }):
   return ev.type === 'session.status_idle' && ev.stop_reason?.type === 'end_turn';
 }
 
+/**
+ * The `maxIdleMs` stop-countdown, including its deferral. {@link noteEvent}
+ * arms on `session.status_idle` with `stop_reason: end_turn` and disarms on
+ * anything else. Gated tool work registered via {@link block} — a call held for
+ * user confirmation, or a user-approved call still dispatching — keeps
+ * {@link arm} pending until {@link unblock} retires the last blocker, at which
+ * point the countdown starts. Event-driven — there is no polling watchdog.
+ */
+class IdleClock {
+  readonly #maxIdleMs: number;
+  readonly #onExpire: () => void;
+  readonly #blockers = new Set<string>();
+  // Set when arm() found blockers outstanding; the unblock that retires the
+  // last blocker applies it. Cleared by any disarm.
+  #armPending = false;
+  #timer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(maxIdleMs: number, onExpire: () => void) {
+    this.#maxIdleMs = maxIdleMs;
+    this.#onExpire = onExpire;
+  }
+
+  /**
+   * Arm on `status_idle{end_turn}`; disarm otherwise. `user.tool_confirmation`
+   * is neutral: it signals neither agent activity nor an idle, and its effect
+   * on the clock flows through {@link block} / {@link unblock} instead —
+   * disarming here would discard the pending arm the verdict is about to
+   * settle.
+   */
+  noteEvent(ev: { type: string; stop_reason?: { type?: string } }): void {
+    if (ev.type === 'user.tool_confirmation') return;
+    if (isEndTurnIdle(ev)) this.arm();
+    else this.disarm();
+  }
+
+  /** Register gated work that must resolve before an idle countdown starts. */
+  block(toolUseId: string): void {
+    this.#blockers.add(toolUseId);
+    if (this.#timer !== undefined) {
+      // Defensive: every caller disarms first (any event that routes a tool
+      // call is itself a disarming event), but a countdown running when gated
+      // work appears is stale evidence — the session is not idly waiting to
+      // stop. Convert it into a pending arm rather than let it fire over the
+      // gated call.
+      this.#armPending = true;
+      clearTimeout(this.#timer);
+      this.#timer = undefined;
+    }
+  }
+
+  /**
+   * Retire gated work (a no-op for ids never blocked); applies a pending arm —
+   * with a fresh full `maxIdleMs` window — once the last blocker retires.
+   */
+  unblock(toolUseId: string): void {
+    this.#blockers.delete(toolUseId);
+    if (this.#blockers.size === 0 && this.#armPending) this.arm();
+  }
+
+  /**
+   * (Re)start the idle countdown — or, while blockers are outstanding, hold
+   * the arm pending instead. Stopping then would drop a held call when its
+   * verdict later arrives, or cut the runner off before a released call's
+   * result can drive the next turn.
+   */
+  arm(): void {
+    if (this.#maxIdleMs <= 0) return;
+    if (this.#blockers.size > 0) {
+      this.#armPending = true;
+      return;
+    }
+    this.#armPending = false;
+    if (this.#timer !== undefined) clearTimeout(this.#timer);
+    this.#timer = setTimeout(this.#onExpire, this.#maxIdleMs);
+  }
+
+  /**
+   * Cancel the idle countdown and any pending arm. Blockers persist — they
+   * track real outstanding work, retired only by {@link unblock}.
+   */
+  disarm(): void {
+    this.#armPending = false;
+    if (this.#timer !== undefined) {
+      clearTimeout(this.#timer);
+      this.#timer = undefined;
+    }
+  }
+}
+
 /**
  * The sessions-side counterpart to `client.beta.messages.toolRunner`: an
  * async-iterable that attaches to a managed-agents session, executes every
@@ -148,6 +252,18 @@ function isEndTurnIdle(ev: { type?: string; stop_reason?: { type?: string } }):
  * calls are not dispatched. Internally drives event-stream reconnect and result
  * posting.
  *
+ * A call the server gated with `evaluated_permission: "ask"` (the `always_ask`
+ * policy — or any value this SDK doesn't recognize, which fails closed) is held
+ * until its `user.tool_confirmation` arrives: only an explicit `allow` runs it;
+ * `deny` — or any verdict this SDK doesn't recognize, failing closed — is never
+ * executed and posts nothing (the denial resolves the call server-side), but is
+ * still yielded (`confirmation="deny"`, `posted=false`, `result=undefined`) so
+ * the consumer can observe it. A held call — and a user-approved one still
+ * dispatching — defers the `maxIdleMs` countdown, so an `end_turn` idle
+ * observed in the meantime cannot stop the runner: it waits until the verdict
+ * arrives, the session terminates, or the abort signal fires — pass
+ * `AbortSignal.timeout(...)` for a wall-clock bound.
+ *
  * Iteration ends when the session terminates (`session.status_terminated` /
  * `session.deleted`), when the consumer `break`s out of the loop or aborts the
  * supplied signal, or — once the session has gone idle with
@@ -183,12 +299,19 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
   readonly #logger: Logger;
   readonly #seen = new Set<string>();
   readonly #answered = new Set<string>();
+  // Confirmation gating (`always_ask` tools): `#confirmationVerdicts` records
+  // every `user.tool_confirmation` verdict by `tool_use_id`;
+  // `#awaitingConfirmation` holds the tool-call events whose
+  // `evaluated_permission` is `ask` and whose verdict has not arrived —
+  // released (or resolved as denied) by `#noteConfirmation` / the next
+  // reconcile pass. Like `#seen` and `#answered`, `#confirmationVerdicts` is
+  // per-session O(tool calls): recorded verdicts persist for the life of the run.
+  readonly #confirmationVerdicts = new Map<string, 'allow' | 'deny'>();
+  readonly #awaitingConfirmation = new Map<string, DispatchedToolUseEvent>();
   readonly #results = new AsyncQueue<DispatchedToolCall>();
   #inFlightCount = 0;
   #onIdle: (() => void) | null = null;
-  // When the session is idle past an `end_turn`, the pending stop timer; cleared
-  // by any new event. Event-driven — there is no polling watchdog.
-  #idleTimer: ReturnType<typeof setTimeout> | undefined;
+  readonly #idleClock: IdleClock;
 
   constructor(sessionId: string, opts: SessionToolRunnerOptions) {
     this.client = opts.client;
@@ -200,6 +323,14 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
     this.#controller = new AbortController();
     this.#detachExternal = linkAbort(opts.signal, this.#controller);
     this.#requestOpts = opts.requestOptions;
+    this.#idleClock = new IdleClock(this.maxIdleMs, () => {
+      this.#logger.info('session idle after end_turn; stopping', {
+        component: 'session-tool-runner',
+        session_id: this.sessionId,
+        max_idle_ms: this.maxIdleMs,
+      });
+      this.#controller.abort();
+    });
   }
 
   /** Read-only view of this runner's abort signal. */
@@ -250,7 +381,7 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
       }
     } finally {
       this.#controller.abort();
-      this.#disarmIdleTimer();
+      this.#idleClock.disarm();
       // Re-await defensively in case the consumer broke out of phase 1 before
       // phase 2 ran — a no-op if it already settled.
       await streamPromise;
@@ -362,12 +493,29 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
       return;
     }
     const unanswered = pending.filter((ev) => !this.#answered.has(ev.id));
-    // If the most recent event in history is an `end_turn` idle and there's no
-    // outstanding tool work, the session is done — arm the idle timer so the
-    // runner stops even if that `end_turn` arrived during a disconnect.
-    if (lastWasEndTurn && unanswered.length === 0) this.#armIdleTimer();
-    else this.#disarmIdleTimer();
-    for (const ev of unanswered) await this.#execute(ev);
+    // Disarm before routing: `#execute` runs inline here, so a timer left armed
+    // from before the reconnect could fire over an in-flight tool.
+    this.#idleClock.disarm();
+    for (const ev of unanswered) await this.#routeToolEvent(ev);
+    // A held call's verdict is normally applied by the routing pass above; if
+    // its tool_use fell outside the listed window the pass never saw it, so
+    // apply the verdict to the held copy here.
+    for (const held of [...this.#awaitingConfirmation.values()]) {
+      const verdict = this.#confirmationVerdicts.get(held.id);
+      if (verdict !== undefined) await this.#applyVerdict(held, verdict);
+    }
+    // Routing resolves denied calls in place (marking them answered) and holds
+    // ask-gated calls for their `user.tool_confirmation`. If the most recent
+    // event in history is an `end_turn` idle and no tool work is outstanding,
+    // the session is done — arm the idle clock so the runner stops even if that
+    // `end_turn` arrived during a disconnect. A held call is not outstanding
+    // here: it blocks the clock, so this arm stays pending until the verdict
+    // (and, for an allow, the dispatch it releases) resolves it.
+    const outstanding = unanswered.filter(
+      (ev) => !this.#answered.has(ev.id) && !this.#awaitingConfirmation.has(ev.id),
+    );
+    if (lastWasEndTurn && outstanding.length === 0) this.#idleClock.arm();
+    else this.#idleClock.disarm();
   }
 
   #ingestHistory(ev: BetaManagedAgentsSessionEvent, pending: DispatchedToolUseEvent[]): void {
@@ -382,23 +530,29 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
       this.#answered.add(ev.tool_use_id);
     } else if (ev.type === 'user.custom_tool_result') {
       this.#answered.add(ev.custom_tool_use_id);
+    } else if (ev.type === 'user.tool_confirmation') {
+      // Record the verdict only, before the pending pass, so a call whose
+      // confirmation appears later in the same history routes with its verdict
+      // already known. Releasing a held call here as well would dispatch it a
+      // second time when the routing pass reaches its tool_use event.
+      if (!this.#answered.has(ev.tool_use_id)) this.#confirmationVerdicts.set(ev.tool_use_id, ev.result);
     }
   }
 
   /** Returns true when the runner should exit. */
   async #handleStreamEvent(ev: BetaManagedAgentsStreamSessionEvents): Promise<boolean> {
-    // Arm/disarm the idle timer: an `end_turn` idle starts the grace countdown;
-    // any other event cancels it.
-    if (isEndTurnIdle(ev)) this.#armIdleTimer();
-    else this.#disarmIdleTimer();
+    this.#idleClock.noteEvent(ev);
     switch (ev.type) {
       case 'agent.tool_use':
       case 'agent.custom_tool_use':
         if (!this.#seen.has(ev.id)) {
           this.#seen.add(ev.id);
-          await this.#execute(ev);
+          await this.#routeToolEvent(ev);
         }
         return false;
+      case 'user.tool_confirmation':
+        await this.#noteConfirmation(ev);
+        return false;
       case 'user.tool_result':
         this.#answered.add(ev.tool_use_id);
         return false;
@@ -418,33 +572,115 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
     }
   }
 
-  // ===== idle timer =====
+  // ===== confirmation gating (always_ask tools) =====
 
-  /** (Re)start the grace countdown that stops the runner after `maxIdleMs` of idle. */
-  #armIdleTimer(): void {
-    this.#disarmIdleTimer();
-    if (this.maxIdleMs <= 0) return;
-    this.#idleTimer = setTimeout(() => {
-      this.#logger.info('session idle after end_turn; stopping', {
+  /**
+   * Dispatch `ev`, honoring its evaluated permission. A call the server gated
+   * (`evaluated_permission == "ask"`) is held until its `user.tool_confirmation`
+   * arrives. Fails closed: only an explicit `allow` verdict releases a gated
+   * call; a server-side `deny` overrides any recorded verdict; an unrecognized
+   * permission is held like `ask` and an unrecognized verdict is denied.
+   */
+  async #routeToolEvent(ev: DispatchedToolUseEvent): Promise<void> {
+    // `getattr`-style read: today only `agent.tool_use` carries
+    // `evaluated_permission`, but if it ever lands on `agent.custom_tool_use`
+    // the gate must keep failing closed rather than dispatch by event type.
+    const permission = (ev as { evaluated_permission?: 'allow' | 'ask' | 'deny' }).evaluated_permission;
+    // A server-side `deny` overrides any (stray) recorded verdict.
+    const verdict = permission === 'deny' ? 'deny' : this.#confirmationVerdicts.get(ev.id);
+    if (verdict === undefined) {
+      if (permission === undefined || permission === 'allow') {
+        await this.#execute(ev, undefined);
+      } else if (!this.#awaitingConfirmation.has(ev.id)) {
+        // "ask" — or a permission this SDK does not recognize, which must not
+        // dispatch unconfirmed — waits for the user's verdict. (Already-held: a
+        // reconcile after reconnect re-routes the call; keep the existing hold.)
+        this.#logger.info('tool call awaiting confirmation; holding', {
+          component: 'session-tool-runner',
+          session_id: this.sessionId,
+          tool: ev.name,
+          tool_use_id: ev.id,
+        });
+        this.#awaitingConfirmation.set(ev.id, ev);
+        this.#idleClock.block(ev.id);
+      }
+      return;
+    }
+    await this.#applyVerdict(ev, verdict);
+  }
+
+  /** Record an allow/deny verdict and release the held call it gates, if any. */
+  async #noteConfirmation(ev: { tool_use_id: string; result: 'allow' | 'deny' }): Promise<void> {
+    this.#confirmationVerdicts.set(ev.tool_use_id, ev.result);
+    const held = this.#awaitingConfirmation.get(ev.tool_use_id);
+    // Nothing held: the verdict gates a call this runner has not seen yet (or
+    // one it never gates, e.g. an `agent.mcp_tool_use`). Keeping it in
+    // `#confirmationVerdicts` lets a later route of that call resolve instantly.
+    if (held === undefined) return;
+    await this.#applyVerdict(held, ev.result);
+  }
+
+  /**
+   * Dispatch or resolve a gated call according to its verdict.
+   *
+   * The idle-clock blocker accounting lives here: a denial retires the held
+   * call's blocker, while an allow keeps one on the call — taking it now if the
+   * verdict was already known when the call was routed, so it was never held —
+   * until `#execute` has finished with it. The countdown must not run over
+   * gated work that is still in flight.
+   */
+  async #applyVerdict(ev: DispatchedToolUseEvent, verdict: 'allow' | 'deny'): Promise<void> {
+    const wasHeld = this.#awaitingConfirmation.delete(ev.id);
+    if (verdict === 'allow') {
+      this.#logger.info('tool call confirmed', {
         component: 'session-tool-runner',
         session_id: this.sessionId,
-        max_idle_ms: this.maxIdleMs,
+        tool: ev.name,
+        tool_use_id: ev.id,
       });
-      this.#controller.abort();
-    }, this.maxIdleMs);
+      if (!wasHeld) this.#idleClock.block(ev.id);
+      try {
+        await this.#execute(ev, 'allow');
+      } finally {
+        // The approved call is fully disposed of (executed, or moot because it
+        // was answered elsewhere) — the sole place an allow's blocker retires.
+        this.#idleClock.unblock(ev.id);
+      }
+      return;
+    }
+    // "deny" — or any value other than an explicit "allow" (fail closed). The
+    // denial resolves the call server-side, so mark it answered and yield it
+    // (nothing ran, nothing posted).
+    if (wasHeld) this.#idleClock.unblock(ev.id);
+    this.#answered.add(ev.id);
+    this.#logger.info('tool call denied; not executing', {
+      component: 'session-tool-runner',
+      session_id: this.sessionId,
+      tool: ev.name,
+      tool_use_id: ev.id,
+    });
+    this.#surfaceCall({
+      event: ev,
+      toolUseId: ev.id,
+      name: ev.name,
+      isError: false,
+      posted: false,
+      confirmation: 'deny',
+    });
   }
 
-  /** Cancel a pending idle countdown, if any. */
-  #disarmIdleTimer(): void {
-    if (this.#idleTimer !== undefined) {
-      clearTimeout(this.#idleTimer);
-      this.#idleTimer = undefined;
-    }
+  /**
+   * Yield `call` to the consumer. A closed queue — the consumer broke out of
+   * the iterator — makes `push` a no-op returning false; the underlying work
+   * already happened, so only the observability event is lost.
+   */
+  #surfaceCall(call: DispatchedToolCall): void {
+    this.#results.push(call);
   }
 
   // ===== tool execution =====
 
-  async #execute(ev: DispatchedToolUseEvent): Promise<void> {
+  async #execute(ev: DispatchedToolUseEvent, confirmation: 'allow' | undefined): Promise<void> {
     if (this.#answered.has(ev.id)) return;
     this.#logger.info('executing tool', {
       component: 'session-tool-runner',
@@ -472,7 +708,14 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
           tool: ev.name,
           tool_use_id: ev.id,
         });
-        this.#results.push({ event: ev, toolUseId: ev.id, name: ev.name, isError: false, posted: false });
+        this.#surfaceCall({
+          event: ev,
+          toolUseId: ev.id,
+          name: ev.name,
+          isError: false,
+          posted: false,
+          confirmation,
+        });
         return;
       }
       let content: string | Array<BetaToolResultContentBlockParam>;
@@ -504,13 +747,14 @@ export class SessionToolRunner implements AsyncIterable<DispatchedToolCall> {
       // unanswered and the session stuck.
       const result = buildResultEvent(ev, isError, toSessionContent(content));
       const posted = await this.#sendResult(result, ev.id);
-      this.#results.push({
+      this.#surfaceCall({
         event: ev,
         result,
         toolUseId: ev.id,
         name: ev.name,
         isError,
         posted,
+        confirmation,
       });
     } finally {
       this.#inFlightCount--;

package/src/resources/beta/agents/agents.ts

@@ -537,7 +537,7 @@ export interface BetaManagedAgentsCustomToolInputSchema {
 export interface BetaManagedAgentsCustomToolParams {
   /**
    * Description of what the tool does, shown to the agent to help it decide when to
-   * use the tool. 1-1024 characters.
+   * use the tool. 1-4096 characters.
    */
   description: string;