@anthropic-ai/sdk 0.96.0 → 0.97.0

package/src/resources/beta/sessions/events.ts

@@ -1,13 +1,19 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import type { Anthropic } from '../../../client';
 import { APIResource } from '../../../core/resource';
 import * as BetaAPI from '../beta';
+import * as SessionsAPI from './sessions';
 import { APIPromise } from '../../../core/api-promise';
 import { PageCursor, type PageCursorParams, PagePromise } from '../../../core/pagination';
 import { Stream } from '../../../core/streaming';
 import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
+import {
+  SessionToolRunner,
+  type SessionToolRunnerOptions as RunnerSessionToolRunnerOptions,
+} from '../../../lib/tools/SessionToolRunner';
 
 export class Events extends APIResource {
   /**
@@ -109,6 +115,29 @@ export class Events extends APIResource {
       stream: true,
     }) as APIPromise<Stream<BetaManagedAgentsStreamSessionEvents>>;
   }
+
+  /**
+   * Attach to a session and dispatch every incoming `agent.tool_use` and
+   * `agent.custom_tool_use` event to a local tool registry, sending the matching
+   * result back (`user.tool_result` / `user.custom_tool_result`). The
+   * sessions-side counterpart to `client.beta.messages.toolRunner`: yields one
+   * entry per completed tool call so callers can observe each dispatch (and
+   * `break` to abort cleanly).
+   *
+   * @example
+   * ```ts
+   * import { betaAgentToolset20260401 } from '@anthropic-ai/sdk/tools/agent-toolset/node';
+   *
+   * for await (const call of client.beta.sessions.events.toolRunner(work.data.id, {
+   *   tools: [...betaAgentToolset20260401({ workdir }), myTool],
+   * })) {
+   *   console.log(`${call.name} -> ${call.isError ? 'error' : 'ok'}`);
+   * }
+   * ```
+   */
+  toolRunner(sessionID: string, opts: Omit<RunnerSessionToolRunnerOptions, 'client'>): SessionToolRunner {
+    return new SessionToolRunner(sessionID, { ...opts, client: this._client as Anthropic });
+  }
 }
 
 export type BetaManagedAgentsSessionEventsPageCursor = PageCursor<BetaManagedAgentsSessionEvent>;
@@ -524,7 +553,8 @@ export type BetaManagedAgentsEventParams =
   | BetaManagedAgentsUserInterruptEventParams
   | BetaManagedAgentsUserToolConfirmationEventParams
   | BetaManagedAgentsUserCustomToolResultEventParams
-  | BetaManagedAgentsUserDefineOutcomeEventParams;
+  | BetaManagedAgentsUserDefineOutcomeEventParams
+  | BetaManagedAgentsUserToolResultEventParams;
 
 /**
  * Document referenced by file ID.
@@ -804,6 +834,7 @@ export interface BetaManagedAgentsSendSessionEvents {
     | BetaManagedAgentsUserToolConfirmationEvent
     | BetaManagedAgentsUserCustomToolResultEvent
     | BetaManagedAgentsUserDefineOutcomeEvent
+    | SessionsAPI.BetaManagedAgentsUserToolResultEvent
   >;
 }
 
@@ -897,7 +928,9 @@ export type BetaManagedAgentsSessionEvent =
   | BetaManagedAgentsSessionThreadStatusRunningEvent
   | BetaManagedAgentsSessionThreadStatusIdleEvent
   | BetaManagedAgentsSessionThreadStatusTerminatedEvent
-  | BetaManagedAgentsSessionThreadStatusRescheduledEvent;
+  | SessionsAPI.BetaManagedAgentsUserToolResultEvent
+  | BetaManagedAgentsSessionThreadStatusRescheduledEvent
+  | SessionsAPI.BetaManagedAgentsSessionUpdatedEvent;
 
 /**
  * The agent is idle waiting on one or more blocking user-input events (tool
@@ -1380,7 +1413,9 @@ export type BetaManagedAgentsStreamSessionEvents =
   | BetaManagedAgentsSessionThreadStatusRunningEvent
   | BetaManagedAgentsSessionThreadStatusIdleEvent
   | BetaManagedAgentsSessionThreadStatusTerminatedEvent
-  | BetaManagedAgentsSessionThreadStatusRescheduledEvent;
+  | SessionsAPI.BetaManagedAgentsUserToolResultEvent
+  | BetaManagedAgentsSessionThreadStatusRescheduledEvent
+  | SessionsAPI.BetaManagedAgentsSessionUpdatedEvent;
 
 /**
  * Regular text content.
@@ -1744,6 +1779,38 @@ export interface BetaManagedAgentsUserToolConfirmationEventParams {
   deny_message?: string | null;
 }
 
+/**
+ * Parameters for providing the result of an agent-toolset tool execution. Only
+ * valid on `self_hosted` environments, where sandbox-routed tools are executed by
+ * the client rather than the server.
+ */
+export interface BetaManagedAgentsUserToolResultEventParams {
+  /**
+   * The id of the `agent.tool_use` event this result corresponds to, which can be
+   * found in the last `session.status_idle`
+   * [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids)
+   * `stop_reason.event_ids` field.
+   */
+  tool_use_id: string;
+
+  type: 'user.tool_result';
+
+  /**
+   * The result content returned by the tool.
+   */
+  content?: Array<
+    | BetaManagedAgentsTextBlock
+    | BetaManagedAgentsImageBlock
+    | BetaManagedAgentsDocumentBlock
+    | BetaManagedAgentsSearchResultBlock
+  >;
+
+  /**
+   * Whether the tool execution resulted in an error.
+   */
+  is_error?: boolean | null;
+}
+
 export interface EventListParams extends PageCursorParams {
   /**
    * Query param: Return events created after this time (exclusive).
@@ -1803,7 +1870,13 @@ export interface EventStreamParams {
   betas?: Array<BetaAPI.AnthropicBeta>;
 }
 
+export { SessionToolRunner, type SessionToolRunnerOptions } from '../../../lib/tools/SessionToolRunner';
+
+Events.SessionToolRunner = SessionToolRunner;
+
 export declare namespace Events {
+  export { SessionToolRunner };
+
   export {
     type BetaManagedAgentsAgentCustomToolUseEvent as BetaManagedAgentsAgentCustomToolUseEvent,
     type BetaManagedAgentsAgentMCPToolResultEvent as BetaManagedAgentsAgentMCPToolResultEvent,
@@ -1876,6 +1949,7 @@ export declare namespace Events {
     type BetaManagedAgentsUserMessageEventParams as BetaManagedAgentsUserMessageEventParams,
     type BetaManagedAgentsUserToolConfirmationEvent as BetaManagedAgentsUserToolConfirmationEvent,
     type BetaManagedAgentsUserToolConfirmationEventParams as BetaManagedAgentsUserToolConfirmationEventParams,
+    type BetaManagedAgentsUserToolResultEventParams as BetaManagedAgentsUserToolResultEventParams,
     type BetaManagedAgentsSessionEventsPageCursor as BetaManagedAgentsSessionEventsPageCursor,
     type EventListParams as EventListParams,
     type EventSendParams as EventSendParams,

package/src/resources/beta/sessions/index.ts

@@ -73,6 +73,7 @@ export {
   type BetaManagedAgentsUserMessageEventParams,
   type BetaManagedAgentsUserToolConfirmationEvent,
   type BetaManagedAgentsUserToolConfirmationEventParams,
+  type BetaManagedAgentsUserToolResultEventParams,
   type EventListParams,
   type EventSendParams,
   type EventStreamParams,
@@ -110,9 +111,12 @@ export {
   type BetaManagedAgentsOutcomeEvaluationResource,
   type BetaManagedAgentsSession,
   type BetaManagedAgentsSessionAgent,
+  type BetaManagedAgentsSessionAgentUpdate,
   type BetaManagedAgentsSessionMultiagentCoordinator,
   type BetaManagedAgentsSessionStats,
+  type BetaManagedAgentsSessionUpdatedEvent,
   type BetaManagedAgentsSessionUsage,
+  type BetaManagedAgentsUserToolResultEvent,
   type SessionCreateParams,
   type SessionRetrieveParams,
   type SessionUpdateParams,
@@ -124,7 +128,6 @@ export {
 export {
   Threads,
   type BetaManagedAgentsSessionThread,
-  type BetaManagedAgentsSessionThreadAgent,
   type BetaManagedAgentsSessionThreadStats,
   type BetaManagedAgentsSessionThreadStatus,
   type BetaManagedAgentsSessionThreadUsage,

package/src/resources/beta/sessions/sessions.ts

@@ -77,6 +77,7 @@ import {
   BetaManagedAgentsUserMessageEventParams,
   BetaManagedAgentsUserToolConfirmationEvent,
   BetaManagedAgentsUserToolConfirmationEventParams,
+  BetaManagedAgentsUserToolResultEventParams,
   EventListParams,
   EventSendParams,
   EventStreamParams,
@@ -102,7 +103,6 @@ import {
 import * as ThreadsAPI from './threads/threads';
 import {
   BetaManagedAgentsSessionThread,
-  BetaManagedAgentsSessionThreadAgent,
   BetaManagedAgentsSessionThreadStats,
   BetaManagedAgentsSessionThreadStatus,
   BetaManagedAgentsSessionThreadUsage,
@@ -596,6 +596,29 @@ export interface BetaManagedAgentsSessionAgent {
   version: number;
 }
 
+/**
+ * Mid-session agent configuration update. Only `tools` and `mcp_servers` are
+ * updatable. Full replacement: the provided array becomes the new value. To
+ * preserve existing entries, GET the session, modify the array, and POST it back.
+ */
+export interface BetaManagedAgentsSessionAgentUpdate {
+  /**
+   * Replacement MCP server list. Full replacement: the provided array becomes the
+   * new value. Send an empty array to clear; omit to preserve.
+   */
+  mcp_servers?: Array<AgentsAPI.BetaManagedAgentsURLMCPServerParams>;
+
+  /**
+   * Replacement tool list. Full replacement: the provided array becomes the new
+   * value. Send an empty array to clear; omit to preserve.
+   */
+  tools?: Array<
+    | AgentsAPI.BetaManagedAgentsAgentToolset20260401Params
+    | AgentsAPI.BetaManagedAgentsMCPToolsetParams
+    | AgentsAPI.BetaManagedAgentsCustomToolParams
+  >;
+}
+
 /**
  * Resolved coordinator topology with full agent definitions for each roster
  * member.
@@ -604,7 +627,7 @@ export interface BetaManagedAgentsSessionMultiagentCoordinator {
   /**
    * Full `agent` definitions the coordinator may spawn as session threads.
    */
-  agents: Array<ThreadsAPI.BetaManagedAgentsSessionThreadAgent>;
+  agents: Array<AgentsAPI.BetaManagedAgentsSessionThreadAgent>;
 
   type: 'coordinator';
 }
@@ -626,6 +649,42 @@ export interface BetaManagedAgentsSessionStats {
   duration_seconds?: number;
 }
 
+/**
+ * Emitted when an UpdateSession request changed at least one field. Carries only
+ * the fields that changed; absent fields were not part of the update. The new
+ * configuration applies from the next turn.
+ */
+export interface BetaManagedAgentsSessionUpdatedEvent {
+  /**
+   * Unique identifier for this event.
+   */
+  id: string;
+
+  /**
+   * A timestamp in RFC 3339 format
+   */
+  processed_at: string;
+
+  type: 'session.updated';
+
+  /**
+   * Resolved `agent` definition for a `session`. Snapshot of the `agent` at
+   * `session` creation time.
+   */
+  agent?: BetaManagedAgentsSessionAgent | null;
+
+  /**
+   * The session's full metadata bag after the update. Present when the update set
+   * non-empty metadata; absent when metadata was unchanged or cleared to empty.
+   */
+  metadata?: { [key: string]: string };
+
+  /**
+   * The session's new title. Present only when the update changed it.
+   */
+  title?: string | null;
+}
+
 /**
  * Cumulative token usage for a session across all turns.
  */
@@ -651,6 +710,54 @@ export interface BetaManagedAgentsSessionUsage {
   output_tokens?: number;
 }
 
+/**
+ * Event sent by the client providing the result of an agent-toolset tool
+ * execution. Only valid on `self_hosted` environments, where sandbox-routed tools
+ * are executed by the client rather than the server.
+ */
+export interface BetaManagedAgentsUserToolResultEvent {
+  /**
+   * Unique identifier for this event.
+   */
+  id: string;
+
+  /**
+   * The id of the `agent.tool_use` event this result corresponds to, which can be
+   * found in the last `session.status_idle`
+   * [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids)
+   * `stop_reason.event_ids` field.
+   */
+  tool_use_id: string;
+
+  type: 'user.tool_result';
+
+  /**
+   * The result content returned by the tool.
+   */
+  content?: Array<
+    | EventsAPI.BetaManagedAgentsTextBlock
+    | EventsAPI.BetaManagedAgentsImageBlock
+    | EventsAPI.BetaManagedAgentsDocumentBlock
+    | EventsAPI.BetaManagedAgentsSearchResultBlock
+  >;
+
+  /**
+   * Whether the tool execution resulted in an error.
+   */
+  is_error?: boolean | null;
+
+  /**
+   * A timestamp in RFC 3339 format
+   */
+  processed_at?: string | null;
+
+  /**
+   * Routes this result to a subagent thread. Copy from the `agent.tool_use` event's
+   * `session_thread_id`.
+   */
+  session_thread_id?: string | null;
+}
+
 export interface SessionCreateParams {
   /**
    * Body param: Agent identifier. Accepts the `agent` ID string, which pins the
@@ -706,6 +813,14 @@ export interface SessionRetrieveParams {
 }
 
 export interface SessionUpdateParams {
+  /**
+   * Body param: Mid-session agent configuration update. Only `tools` and
+   * `mcp_servers` are updatable. Full replacement: the provided array becomes the
+   * new value. To preserve existing entries, GET the session, modify the array, and
+   * POST it back.
+   */
+  agent?: BetaManagedAgentsSessionAgentUpdate;
+
   /**
    * Body param: Metadata patch. Set a key to a string to upsert it, or to null to
    * delete it. Omit the field to preserve.
@@ -824,9 +939,12 @@ export declare namespace Sessions {
     type BetaManagedAgentsOutcomeEvaluationResource as BetaManagedAgentsOutcomeEvaluationResource,
     type BetaManagedAgentsSession as BetaManagedAgentsSession,
     type BetaManagedAgentsSessionAgent as BetaManagedAgentsSessionAgent,
+    type BetaManagedAgentsSessionAgentUpdate as BetaManagedAgentsSessionAgentUpdate,
     type BetaManagedAgentsSessionMultiagentCoordinator as BetaManagedAgentsSessionMultiagentCoordinator,
     type BetaManagedAgentsSessionStats as BetaManagedAgentsSessionStats,
+    type BetaManagedAgentsSessionUpdatedEvent as BetaManagedAgentsSessionUpdatedEvent,
     type BetaManagedAgentsSessionUsage as BetaManagedAgentsSessionUsage,
+    type BetaManagedAgentsUserToolResultEvent as BetaManagedAgentsUserToolResultEvent,
     type BetaManagedAgentsSessionsPageCursor as BetaManagedAgentsSessionsPageCursor,
     type SessionCreateParams as SessionCreateParams,
     type SessionRetrieveParams as SessionRetrieveParams,
@@ -909,6 +1027,7 @@ export declare namespace Sessions {
     type BetaManagedAgentsUserMessageEventParams as BetaManagedAgentsUserMessageEventParams,
     type BetaManagedAgentsUserToolConfirmationEvent as BetaManagedAgentsUserToolConfirmationEvent,
     type BetaManagedAgentsUserToolConfirmationEventParams as BetaManagedAgentsUserToolConfirmationEventParams,
+    type BetaManagedAgentsUserToolResultEventParams as BetaManagedAgentsUserToolResultEventParams,
     type BetaManagedAgentsSessionEventsPageCursor as BetaManagedAgentsSessionEventsPageCursor,
     type EventListParams as EventListParams,
     type EventSendParams as EventSendParams,
@@ -935,7 +1054,6 @@ export declare namespace Sessions {
   export {
     Threads as Threads,
     type BetaManagedAgentsSessionThread as BetaManagedAgentsSessionThread,
-    type BetaManagedAgentsSessionThreadAgent as BetaManagedAgentsSessionThreadAgent,
     type BetaManagedAgentsSessionThreadStats as BetaManagedAgentsSessionThreadStats,
     type BetaManagedAgentsSessionThreadStatus as BetaManagedAgentsSessionThreadStatus,
     type BetaManagedAgentsSessionThreadUsage as BetaManagedAgentsSessionThreadUsage,

package/src/resources/beta/sessions/threads/index.ts

@@ -4,7 +4,6 @@ export { Events, type EventListParams, type EventStreamParams } from './events';
 export {
   Threads,
   type BetaManagedAgentsSessionThread,
-  type BetaManagedAgentsSessionThreadAgent,
   type BetaManagedAgentsSessionThreadStats,
   type BetaManagedAgentsSessionThreadStatus,
   type BetaManagedAgentsSessionThreadUsage,

package/src/resources/beta/sessions/threads/threads.ts

@@ -121,7 +121,7 @@ export interface BetaManagedAgentsSessionThread {
    * at thread creation time. The multiagent roster is not repeated here; read it
    * from `Session.agent`.
    */
-  agent: BetaManagedAgentsSessionThreadAgent;
+  agent: AgentsAPI.BetaManagedAgentsSessionThreadAgent;
 
   /**
    * A timestamp in RFC 3339 format
@@ -166,40 +166,6 @@ export interface BetaManagedAgentsSessionThread {
   usage: BetaManagedAgentsSessionThreadUsage | null;
 }
 
-/**
- * Resolved `agent` definition for a single `session_thread`. Snapshot of the agent
- * at thread creation time. The multiagent roster is not repeated here; read it
- * from `Session.agent`.
- */
-export interface BetaManagedAgentsSessionThreadAgent {
-  id: string;
-
-  description: string | null;
-
-  mcp_servers: Array<AgentsAPI.BetaManagedAgentsMCPServerURLDefinition>;
-
-  /**
-   * Model identifier and configuration.
-   */
-  model: AgentsAPI.BetaManagedAgentsModelConfig;
-
-  name: string;
-
-  skills: Array<AgentsAPI.BetaManagedAgentsAnthropicSkill | AgentsAPI.BetaManagedAgentsCustomSkill>;
-
-  system: string | null;
-
-  tools: Array<
-    | AgentsAPI.BetaManagedAgentsAgentToolset20260401
-    | AgentsAPI.BetaManagedAgentsMCPToolset
-    | AgentsAPI.BetaManagedAgentsCustomTool
-  >;
-
-  type: 'agent';
-
-  version: number;
-}
-
 /**
  * Timing statistics for a session thread.
  */
@@ -287,7 +253,9 @@ export type BetaManagedAgentsStreamSessionThreadEvents =
   | EventsAPI.BetaManagedAgentsSessionThreadStatusRunningEvent
   | EventsAPI.BetaManagedAgentsSessionThreadStatusIdleEvent
   | EventsAPI.BetaManagedAgentsSessionThreadStatusTerminatedEvent
-  | EventsAPI.BetaManagedAgentsSessionThreadStatusRescheduledEvent;
+  | SessionsAPI.BetaManagedAgentsUserToolResultEvent
+  | EventsAPI.BetaManagedAgentsSessionThreadStatusRescheduledEvent
+  | SessionsAPI.BetaManagedAgentsSessionUpdatedEvent;
 
 export interface ThreadRetrieveParams {
   /**
@@ -325,7 +293,6 @@ Threads.Events = Events;
 export declare namespace Threads {
   export {
     type BetaManagedAgentsSessionThread as BetaManagedAgentsSessionThread,
-    type BetaManagedAgentsSessionThreadAgent as BetaManagedAgentsSessionThreadAgent,
     type BetaManagedAgentsSessionThreadStats as BetaManagedAgentsSessionThreadStats,
     type BetaManagedAgentsSessionThreadStatus as BetaManagedAgentsSessionThreadStatus,
     type BetaManagedAgentsSessionThreadUsage as BetaManagedAgentsSessionThreadUsage,

package/src/resources/beta/skills/index.ts

@@ -22,5 +22,6 @@ export {
   type VersionRetrieveParams,
   type VersionListParams,
   type VersionDeleteParams,
+  type VersionDownloadParams,
   type VersionListResponsesPageCursor,
 } from './versions';

package/src/resources/beta/skills/skills.ts

@@ -8,6 +8,7 @@ import {
   VersionCreateResponse,
   VersionDeleteParams,
   VersionDeleteResponse,
+  VersionDownloadParams,
   VersionListParams,
   VersionListResponse,
   VersionListResponsesPageCursor,
@@ -380,5 +381,6 @@ export declare namespace Skills {
     type VersionRetrieveParams as VersionRetrieveParams,
     type VersionListParams as VersionListParams,
     type VersionDeleteParams as VersionDeleteParams,
+    type VersionDownloadParams as VersionDownloadParams,
   };
 }

package/src/resources/beta/skills/versions.ts

@@ -127,6 +127,35 @@ export class Versions extends APIResource {
       ]),
     });
   }
+
+  /**
+   * Download a skill version's content as a zip archive.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.skills.versions.download(
+   *   'version',
+   *   { skill_id: 'skill_id' },
+   * );
+   *
+   * const content = await response.blob();
+   * console.log(content);
+   * ```
+   */
+  download(version: string, params: VersionDownloadParams, options?: RequestOptions): APIPromise<Response> {
+    const { skill_id, betas } = params;
+    return this._client.get(path`/v1/skills/${skill_id}/versions/${version}/content?beta=true`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          'anthropic-beta': [...(betas ?? []), 'skills-2025-10-02'].toString(),
+          Accept: 'application/binary',
+        },
+        options?.headers,
+      ]),
+      __binaryResponse: true,
+    });
+  }
 }
 
 export type VersionListResponsesPageCursor = PageCursor<VersionListResponse>;
@@ -359,6 +388,20 @@ export interface VersionDeleteParams {
   betas?: Array<BetaAPI.AnthropicBeta>;
 }
 
+export interface VersionDownloadParams {
+  /**
+   * Path param: Unique identifier for the skill.
+   *
+   * The format and length of IDs may change over time.
+   */
+  skill_id: string;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) you want to use.
+   */
+  betas?: Array<BetaAPI.AnthropicBeta>;
+}
+
 export declare namespace Versions {
   export {
     type VersionCreateResponse as VersionCreateResponse,
@@ -370,5 +413,6 @@ export declare namespace Versions {
     type VersionRetrieveParams as VersionRetrieveParams,
     type VersionListParams as VersionListParams,
     type VersionDeleteParams as VersionDeleteParams,
+    type VersionDownloadParams as VersionDownloadParams,
   };
 }

package/src/tools/agent-toolset/fs-util.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared, Node-only filesystem helpers for the agent toolset's file tools:
+ * path confinement (symlink-aware), an atomic write, and language-independent
+ * error messages. Kept out of `node.ts` so the tool implementations stay focused
+ * and these helpers can be reused by every file tool.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ToolError } from '../../lib/tools/ToolError';
+
+/** Mode for directories the file tools create — not world-writable under a 0 umask. */
+export const DIR_CREATE_MODE = 0o755;
+/** Mode for files the file tools create. */
+export const FILE_CREATE_MODE = 0o644;
+
+/** `realpath` `p`, or return `p` unchanged when it cannot be resolved. */
+async function realpathOrSelf(p: string): Promise<string> {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Fully resolve `abs`: `realpath` the longest existing ancestor and re-append
+ * the rest, but never re-append a component that is itself a symlink — read the
+ * link and continue from its target instead. This handles paths being created
+ * (write/edit) without letting a symlink leaf (e.g. a dangling one pointing
+ * outside a confinement root) slip through unresolved.
+ */
+export async function canonicalize(abs: string): Promise<string> {
+  const tail: string[] = [];
+  let prefix = abs;
+  for (;;) {
+    let real: string;
+    try {
+      real = await fs.realpath(prefix);
+    } catch {
+      let isLink = false;
+      try {
+        isLink = (await fs.lstat(prefix)).isSymbolicLink();
+      } catch {
+        /* prefix truly doesn't exist (ENOENT) — fall through and walk up */
+      }
+      if (isLink) {
+        // Resolve the symlink ourselves and retry; `tail` (the part below it)
+        // still applies to the link's target.
+        prefix = path.resolve(path.dirname(prefix), await fs.readlink(prefix));
+        continue;
+      }
+      const parent = path.dirname(prefix);
+      if (parent === prefix) return abs; // walked past the FS root without a hit
+      tail.push(path.basename(prefix));
+      prefix = parent;
+      continue;
+    }
+    return tail.length ? path.join(real, ...tail.reverse()) : real;
+  }
+}
+
+/**
+ * Resolve `p` and confine it to `root`.
+ *
+ * Unless `allowOutside` is set, absolute inputs are rejected and the
+ * **canonical** path is returned — every symlink in `p` (including the leaf,
+ * even a dangling one) is resolved before the confinement check, and the
+ * resolved path is what the caller then operates on, so a symlink inside `root`
+ * that points outside it can neither pass the check nor be followed afterwards.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; this is why a
+ * sandbox is still recommended for the toolset as a whole.
+ */
+export async function confineToRoot(
+  root: string,
+  p: string,
+  opts?: { allowOutside?: boolean },
+): Promise<string> {
+  const allowOutside = opts?.allowOutside ?? false;
+  if (path.isAbsolute(p)) {
+    if (!allowOutside) {
+      throw new ToolError(`absolute path ${JSON.stringify(p)} not permitted`);
+    }
+    return path.resolve(p);
+  }
+  const realRoot = await realpathOrSelf(path.resolve(root));
+  const abs = path.resolve(realRoot, p);
+  if (allowOutside) return abs;
+  const real = await canonicalize(abs);
+  const rootSep = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep;
+  if (real !== realRoot && !real.startsWith(rootSep)) {
+    throw new ToolError(`path ${JSON.stringify(p)} escapes workdir`);
+  }
+  return real;
+}
+
+/**
+ * Atomically write `content` to `targetPath`: write a sibling temp file, fsync
+ * it, then rename over the target. The rename is atomic on most filesystems, so
+ * a crash mid-write never leaves the target half-written.
+ */
+export async function atomicWriteFile(targetPath: string, content: string): Promise<void> {
+  const dir = path.dirname(targetPath);
+  const tempPath = path.join(dir, `.tmp-${process.pid}-${randomUUID()}`);
+  let handle: fs.FileHandle | undefined;
+  try {
+    handle = await fs.open(tempPath, 'wx', FILE_CREATE_MODE);
+    await handle.writeFile(content, 'utf-8');
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await fs.rename(tempPath, targetPath);
+  } catch (err) {
+    if (handle) await handle.close().catch(() => {});
+    await fs.unlink(tempPath).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Map a thrown filesystem error to a consistent, language-independent message,
+ * so the model sees the same wording regardless of the runtime (Node's raw
+ * `ENOENT: no such file...` text would otherwise leak through). Falls back to
+ * the raw error message for codes we don't special-case.
+ */
+export function fsErrorMessage(err: unknown, file: string): string {
+  const code = (err as { code?: string } | null)?.code;
+  switch (code) {
+    case 'ENOENT':
+      return `${file}: no such file or directory`;
+    case 'EACCES':
+    case 'EPERM':
+      return `${file}: permission denied`;
+    case 'ENOTDIR':
+      return `${file}: not a directory`;
+    case 'EISDIR':
+      return `${file}: is a directory`;
+    case 'ELOOP':
+      return `${file}: too many levels of symbolic links`;
+    case 'ENAMETOOLONG':
+      return `${file}: file name too long`;
+    case 'ENOSPC':
+      return `${file}: no space left on device`;
+    case 'EMFILE':
+    case 'ENFILE':
+      return `${file}: too many open files`;
+    default:
+      return `${file}: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}