@anthropic-ai/sdk 0.115.0 → 0.117.1

package/src/resources/messages/messages.ts

@@ -86,7 +86,7 @@ export class Messages extends APIResource {
       );
     }
 
-    let timeout = (this._client as any)._options.timeout as number | null;
+    let timeout = options?.timeout ?? ((this._client as any)._options.timeout as number | null);
     if (!body.stream && timeout == null) {
       const maxNonstreamingTokens = MODEL_NONSTREAMING_TOKENS[body.model] ?? undefined;
       timeout = this._client.calculateNonstreamingTimeout(body.max_tokens, maxNonstreamingTokens);
@@ -1272,8 +1272,6 @@ export type Model =
   | 'claude-opus-4-5-20251101'
   | 'claude-sonnet-4-5'
   | 'claude-sonnet-4-5-20250929'
-  | 'claude-opus-4-1'
-  | 'claude-opus-4-1-20250805'
   | (string & {});
 
 export interface OutputConfig {
@@ -1304,28 +1302,7 @@ export interface OutputTokensDetails {
 }
 const DEPRECATED_MODELS: {
   [K in Model]?: string;
-} = {
-  'claude-1.3': 'November 6th, 2024',
-  'claude-1.3-100k': 'November 6th, 2024',
-  'claude-instant-1.1': 'November 6th, 2024',
-  'claude-instant-1.1-100k': 'November 6th, 2024',
-  'claude-instant-1.2': 'November 6th, 2024',
-  'claude-3-sonnet-20240229': 'July 21st, 2025',
-  'claude-3-opus-20240229': 'January 5th, 2026',
-  'claude-2.1': 'July 21st, 2025',
-  'claude-2.0': 'July 21st, 2025',
-  'claude-3-7-sonnet-latest': 'February 19th, 2026',
-  'claude-3-7-sonnet-20250219': 'February 19th, 2026',
-  'claude-3-5-haiku-latest': 'February 19th, 2026',
-  'claude-3-5-haiku-20241022': 'February 19th, 2026',
-  'claude-opus-4-0': 'June 15th, 2026',
-  'claude-opus-4-20250514': 'June 15th, 2026',
-  'claude-sonnet-4-0': 'June 15th, 2026',
-  'claude-sonnet-4-20250514': 'June 15th, 2026',
-  'claude-opus-4-1': 'August 5th, 2026',
-  'claude-opus-4-1-20250805': 'August 5th, 2026',
-  'claude-mythos-preview': 'June 30th, 2026',
-};
+} = {};
 
 const MODELS_TO_WARN_WITH_THINKING_ENABLED: Model[] = ['claude-mythos-preview', 'claude-opus-4-6'];
 
@@ -1444,12 +1421,28 @@ export type RawMessageStreamEvent =
   | RawContentBlockStopEvent;
 
 export interface RedactedThinkingBlock {
+  /**
+   * The contents of this redacted thinking block, returned when portions of the
+   * model's thinking were safety-redacted. This field is opaque and encrypted, with
+   * no readable content.
+   *
+   * Pass `redacted_thinking` blocks back to the API unchanged when continuing a
+   * multi-turn conversation.
+   *
+   * See
+   * [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks)
+   * for details.
+   */
   data: string;
 
   type: 'redacted_thinking';
 }
 
 export interface RedactedThinkingBlockParam {
+  /**
+   * The `data` value of this redacted thinking block, exactly as returned by the API
+   * in a previous response. Opaque and encrypted; pass it back unchanged.
+   */
   data: string;
 
   type: 'redacted_thinking';
@@ -1584,6 +1577,11 @@ export interface ServerToolUseBlockParam {
 }
 
 export interface SignatureDelta {
+  /**
+   * The `signature` for this thinking block: an opaque value used to verify that the
+   * block was generated by Claude when it is passed back to the API. Delivered in a
+   * `signature_delta` event just before the block's `content_block_stop` event.
+   */
   signature: string;
 
   type: 'signature_delta';
@@ -1767,16 +1765,41 @@ export interface TextEditorCodeExecutionViewResultBlockParam {
 }
 
 export interface ThinkingBlock {
+  /**
+   * A value used to verify that this thinking block was generated by Claude when it
+   * is passed back to the API.
+   *
+   * This is an opaque field and should not be interpreted or parsed. When passing
+   * thinking blocks back to the API (required when using tools with extended
+   * thinking), pass them back exactly as received, with this field intact.
+   *
+   * See
+   * [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
+   * for details.
+   */
   signature: string;
 
+  /**
+   * The text of Claude's thinking process for this block.
+   */
   thinking: string;
 
   type: 'thinking';
 }
 
 export interface ThinkingBlockParam {
+  /**
+   * The `signature` value of this thinking block, exactly as returned by the API in
+   * a previous response. Used to verify that the block was generated by Claude.
+   *
+   * Thinking blocks must be passed back unmodified and in their original order; a
+   * modified block results in a 400 `invalid_request_error`.
+   */
   signature: string;
 
+  /**
+   * The `thinking` text of this block as returned by the API.
+   */
   thinking: string;
 
   type: 'thinking';
@@ -1837,6 +1860,11 @@ export interface ThinkingConfigEnabled {
 export type ThinkingConfigParam = ThinkingConfigEnabled | ThinkingConfigDisabled | ThinkingConfigAdaptive;
 
 export interface ThinkingDelta {
+  /**
+   * The incremental `thinking` text for this content block. Concatenate the
+   * `thinking` values of successive `thinking_delta` events to assemble the block's
+   * full `thinking` value.
+   */
   thinking: string;
 
   type: 'thinking_delta';

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

@@ -24,12 +24,27 @@ async function realpathOrSelf(p: string): Promise<string> {
   }
 }
 
+/** Matches Linux MAXSYMLINKS, the threshold at which `realpath` itself reports ELOOP. */
+const MAX_SYMLINK_HOPS = 40;
+
+/** The `code` of a Node system error, or `undefined` for anything else. */
+export function errnoCode(err: unknown): string | undefined {
+  const code = (err as { code?: unknown } | null)?.code;
+  return typeof code === 'string' ? code : undefined;
+}
+
 /**
  * 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.
+ *
+ * Returns a symlink-free path or throws an errno-carrying error (`ELOOP` for a
+ * cycle or more than {@link MAX_SYMLINK_HOPS} links, the `lstat`/`realpath`
+ * error for an unreadable component); it never returns `abs` unresolved. Only
+ * symlink hops count against the cap, so any depth of not-yet-existing
+ * directories still resolves.
  */
 export async function canonicalize(abs: string): Promise<string> {
   const tail: string[] = [];
@@ -39,28 +54,24 @@ export async function canonicalize(abs: string): Promise<string> {
     let real: string;
     try {
       real = await fs.realpath(prefix);
-    } catch {
-      let isLink = false;
+    } catch (realpathErr) {
+      let isLink: boolean;
       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. The hop cap matches Linux
-        // MAXSYMLINKS — the same threshold at which `realpath` itself would
-        // have returned ELOOP — so a cycle of unresolvable links terminates.
-        if (++hops > 40) {
-          throw new ToolError(`path ${JSON.stringify(abs)} has too many levels of symbolic links`);
-        }
-        prefix = path.resolve(path.dirname(prefix), await fs.readlink(prefix));
+      } catch (lstatErr) {
+        const code = errnoCode(lstatErr);
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') throw lstatErr;
+        const parent = path.dirname(prefix);
+        if (parent === prefix) throw lstatErr;
+        tail.push(path.basename(prefix));
+        prefix = parent;
         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;
+      if (!isLink) throw realpathErr;
+      if (++hops > MAX_SYMLINK_HOPS) {
+        throw Object.assign(new Error('too many levels of symbolic links'), { code: 'ELOOP' });
+      }
+      prefix = path.resolve(path.dirname(prefix), await fs.readlink(prefix));
       continue;
     }
     return tail.length ? path.join(real, ...tail.reverse()) : real;
@@ -76,6 +87,9 @@ export async function canonicalize(abs: string): Promise<string> {
  * 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.
+ * `..` is collapsed lexically before any symlink is followed. A path that cannot
+ * be resolved (symlink loop, unreadable component) is rejected with a
+ * `ToolError` naming `p`, never the host's absolute path.
  *
  * 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
@@ -91,7 +105,12 @@ export async function confineToRoot(
   const realRoot = await realpathOrSelf(path.resolve(root));
   const abs = path.resolve(realRoot, p);
   if (allowOutside) return abs;
-  const real = await canonicalize(abs);
+  let real: string;
+  try {
+    real = await canonicalize(abs);
+  } catch (err) {
+    throw new ToolError(fsErrorMessage(err, `path ${JSON.stringify(p)}`));
+  }
   if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
     throw new ToolError(`path ${JSON.stringify(p)} escapes workdir`);
   }
@@ -124,11 +143,12 @@ export async function atomicWriteFile(targetPath: string, content: string): Prom
 /**
  * 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.
+ * `ENOENT: no such file...` text would otherwise leak through). Codes we don't
+ * special-case render as the bare code, never Node's message, which embeds the
+ * host's absolute path.
  */
 export function fsErrorMessage(err: unknown, file: string): string {
-  const code = (err as { code?: string } | null)?.code;
+  const code = errnoCode(err);
   switch (code) {
     case 'ENOENT':
       return `${file}: no such file or directory`;
@@ -149,6 +169,6 @@ export function fsErrorMessage(err: unknown, file: string): string {
     case 'ENFILE':
       return `${file}: too many open files`;
     default:
-      return `${file}: ${err instanceof Error ? err.message : String(err)}`;
+      return `${file}: ${code !== undefined ? `i/o error (${code})` : 'i/o error'}`;
   }
 }

package/src/tools/agent-toolset/node.browser.ts

@@ -44,6 +44,20 @@ export function resolvePath(_ctx: AgentToolContext, _p: string): Promise<string>
   return nodeOnly('resolvePath');
 }
 
+/**
+ * A bash command exceeded its `timeoutMs`. Carries the timeout so a caller can
+ * tell it apart from an abort without matching on the message text.
+ */
+export class BashTimeoutError extends AnthropicError {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number) {
+    super(`bash command timed out after ${timeoutMs}ms`);
+    this.name = 'BashTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 export class BashSession {
   constructor(_dir: string, _env?: NodeJS.ProcessEnv) {
     nodeOnly('BashSession');

package/src/tools/agent-toolset/node.ts

@@ -55,6 +55,20 @@ const GREP_OUTPUT_LIMIT = 100 * 1024;
 const GREP_MAX_LINE_LENGTH = 2000;
 const GLOB_RESULT_LIMIT = 200;
 
+/**
+ * A bash command exceeded its `timeoutMs`. Carries the timeout so a caller can
+ * tell it apart from an abort without matching on the message text.
+ */
+export class BashTimeoutError extends AnthropicError {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number) {
+    super(`bash command timed out after ${timeoutMs}ms`);
+    this.name = 'BashTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
 
 // `fs.glob` is Node 22+. `@types/node` may still target an older line, so the
@@ -271,9 +285,9 @@ export class BashSession {
     }
     const timeoutMs = opts.timeoutMs ?? BASH_DEFAULT_TIMEOUT_MS;
     const signal = opts.signal;
-    if (signal?.aborted) {
-      throw new AnthropicError('bash command aborted');
-    }
+    // Reject with the signal's own reason, so a caller telling a user cancel
+    // apart from an `AbortSignal.timeout()` sees the platform's name intact.
+    signal?.throwIfAborted();
     this.#buf = '';
     this.#truncated = false;
     // Per-call nonce so a command that prints a fixed marker can't spoof the
@@ -298,14 +312,11 @@ export class BashSession {
         await Promise.race([
           sentinelSeen,
           new Promise<never>((_, reject) => {
-            timer = setTimeout(
-              () => reject(new AnthropicError(`bash command timed out after ${timeoutMs}ms`)),
-              timeoutMs,
-            );
+            timer = setTimeout(() => reject(new BashTimeoutError(timeoutMs)), timeoutMs);
           }),
           new Promise<never>((_, reject) => {
             if (!signal) return;
-            onAbort = () => reject(new AnthropicError('bash command aborted'));
+            onAbort = () => reject(signal.reason);
             signal.addEventListener('abort', onAbort, { once: true });
           }),
         ]);
@@ -459,7 +470,7 @@ export function betaReadTool(ctx: AgentToolContext): BetaRunnableTool {
         if (e instanceof ToolError) throw e;
         throw new ToolError(`read: ${fsErrorMessage(e, file_path)}`);
       }
-      if (!view_range) return data;
+      if (!view_range?.length) return data;
       if (view_range.length !== 2) throw new ToolError('read: view_range must be [start_line, end_line]');
       const [startLine, endLine] = view_range as [number, number];
       const lines = data.split('\n');

package/src/tools/agent-toolset/skills.ts

@@ -15,7 +15,7 @@ import { pipeline } from 'node:stream/promises';
 import type { Anthropic } from '../../client';
 import { AnthropicError } from '../../core/error';
 import { loggerFor } from '../../internal/utils/log';
-import { DIR_CREATE_MODE } from './fs-util';
+import { DIR_CREATE_MODE, errnoCode } from './fs-util';
 import type { AgentToolContext } from './node';
 
 const execFileAsync = promisify(execFile);
@@ -115,8 +115,8 @@ export async function resolveSkillVersion(
 }
 
 /** Reject archive members that are absolute or contain a `..` component. */
-function assertSafeMemberNames(names: string): void {
-  for (const raw of names.split('\n')) {
+function assertSafeMemberNames(names: string[]): void {
+  for (const raw of names) {
     const entry = raw.trim();
     if (!entry) continue;
     if (path.isAbsolute(entry) || entry.split(/[\\/]/).includes('..')) {
@@ -125,19 +125,77 @@ function assertSafeMemberNames(names: string): void {
   }
 }
 
+const INCONSISTENT_LISTING = 'skill archive listing is inconsistent; refusing to extract';
+
+/**
+ * Type chars (first byte of each `ls`-style line from `unzip -Z` / `tar -tvf`)
+ * that denote a regular file or directory. `zipinfo` prints `?` for entries
+ * with no Unix type bits, which `unzip` extracts as regular files; GNU tar
+ * prints `C` for contiguous files. Everything else — `l` symlink, `h`
+ * hardlink, `b`/`c` device, `p` fifo, `s` socket, unknown tar types — is a
+ * special member.
+ */
+const PLAIN_TYPE_CHARS = { unzip: new Set(['-', 'd', '?']), tar: new Set(['-', 'd', 'C']) };
+
+function listingLines(listing: string): string[] {
+  const lines = listing.split('\n');
+  if (lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
 /**
- * Reject archives that contain anything other than regular files and
- * directories. The type char is the first byte of each `ls`-style line emitted
- * by `tar -tvf` / `unzip -Z`: `-` file, `d` dir, `l` symlink, `h` hardlink,
- * `b`/`c` device, `p` fifo, `s` socket. A symlink/hardlink member is how an
- * archive escapes its extraction dir even when no name contains `..`.
+ * A special member is excluded by handing its listed name back to the CLI as
+ * a pattern, so the name must be byte-identical to what is stored. `tar`,
+ * `bsdtar` and `unzip` print bytes they cannot show literally as `\ooo`, `^X`
+ * or `#U` escapes, or as raw non-ASCII; any such name cannot be excluded
+ * reliably. A leading `-` would let `unzip` parse the pattern as an option.
  */
-function assertNoSpecialMembers(verboseListing: string): void {
-  for (const line of verboseListing.split('\n')) {
-    const type = line.trimStart()[0];
-    if (type === 'l' || type === 'h' || type === 'b' || type === 'c' || type === 'p' || type === 's') {
-      throw new AnthropicError('refusing to extract archive with symlink/hardlink/device member');
+function canExcludeVerbatim(cmd: 'unzip' | 'tar', name: string): boolean {
+  return /^[\x20-\x7E]+$/.test(name) && !/[\\^#]/.test(name) && !(cmd === 'unzip' && name.startsWith('-'));
+}
+
+/**
+ * Pair an archive's name listing (`unzip -Z1` / `tar -tf`) with its typed
+ * listing (`unzip -Z --h --t` / `tar -tvf`) and split the members into plain
+ * (regular file or directory) and special (everything else). Special members
+ * are excluded from extraction rather than rejected; the archive is refused
+ * only when the two listings disagree in length or a special member's name
+ * cannot be passed back to the CLI verbatim (see {@link canExcludeVerbatim}).
+ */
+export function classifyArchiveListing(
+  cmd: 'unzip' | 'tar',
+  names: string,
+  typed: string,
+): { plain: string[]; special: string[] } {
+  const nameLines = listingLines(names);
+  const typedLines = listingLines(typed);
+  if (nameLines.length !== typedLines.length) throw new AnthropicError(INCONSISTENT_LISTING);
+  const plain: string[] = [];
+  const special: string[] = [];
+  nameLines.forEach((name, i) => {
+    if (PLAIN_TYPE_CHARS[cmd].has(typedLines[i]!.charAt(0))) {
+      plain.push(name);
+      return;
     }
+    if (!canExcludeVerbatim(cmd, name)) {
+      throw new AnthropicError(
+        `refusing to extract archive: cannot safely exclude member ${JSON.stringify(name)}`,
+      );
+    }
+    special.push(name);
+  });
+  return { plain, special };
+}
+
+/**
+ * Walk `dir` with `lstat` semantics and reject anything that is not a regular
+ * file or directory. Never follows a link and never descends into anything
+ * but a real directory.
+ */
+export async function assertOnlyPlainEntries(dir: string): Promise<void> {
+  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) await assertOnlyPlainEntries(path.join(dir, entry.name));
+    else if (!entry.isFile()) throw new AnthropicError(INCONSISTENT_LISTING);
   }
 }
 
@@ -152,7 +210,7 @@ async function runArchiveTool(cmd: 'unzip' | 'tar', args: string[]): Promise<str
     const { stdout } = await execFileAsync(cmd, args);
     return stdout;
   } catch (e) {
-    if (e != null && typeof e === 'object' && (e as { code?: unknown }).code === 'ENOENT') {
+    if (errnoCode(e) === 'ENOENT') {
       throw new AnthropicError(
         `skill extraction requires the \`${cmd}\` command, but it was not found on PATH`,
       );
@@ -162,17 +220,17 @@ async function runArchiveTool(cmd: 'unzip' | 'tar', args: string[]): Promise<str
 }
 
 /**
- * The single top-level directory shared by every entry in a newline-separated
- * archive listing, or `''` if entries don't all live under one common
- * directory. Skill bundles are packaged wrapped in one directory named after
- * the skill (e.g. `pdf/SKILL.md`, `pdf/scripts/...`); the extractor strips it
- * so contents land directly in the skill's dir instead of a redundant nested
- * `<skill>/<skill>/` level. A flat or multi-root archive yields `''`.
+ * The single top-level directory shared by every entry in an archive listing,
+ * or `''` if entries don't all live under one common directory. Skill bundles
+ * are packaged wrapped in one directory named after the skill (e.g.
+ * `pdf/SKILL.md`, `pdf/scripts/...`); the extractor strips it so contents land
+ * directly in the skill's dir instead of a redundant nested `<skill>/<skill>/`
+ * level. A flat or multi-root archive yields `''`.
  */
-function archiveTopDir(listing: string): string {
+function archiveTopDir(names: string[]): string {
   let top: string | undefined;
   let nested = false;
-  for (const raw of listing.split('\n')) {
+  for (const raw of names) {
     // Drop `.` / empty segments so a `./pdf/...`-style listing (e.g. from
     // `tar -C dir .`) is treated the same as `pdf/...`.
     const parts = raw
@@ -195,9 +253,14 @@ function archiveTopDir(listing: string): string {
  * to `unzip`/`tar` — consistent with the rest of the toolset, which already
  * invokes `bash` and `rg`. Both `unzip` and `tar` must be available on `PATH`; a
  * missing binary surfaces as a clear error (see {@link runArchiveTool}). Refuses
- * any member that would escape `dest` (zip-slip / tar-slip), including
- * symlink/hardlink members: skill archives come from the API, but skills can be
- * third-party.
+ * any member that would escape `dest` (zip-slip / tar-slip): skill archives
+ * come from the API, but skills can be third-party. Members that are not a
+ * regular file or directory (symlink, hardlink, device, fifo) are excluded
+ * from extraction rather than rejected; an archive whose special members
+ * cannot be excluded reliably is refused (see {@link classifyArchiveListing}).
+ * `tar` matches exclusions unanchored, so a plain member sharing a special
+ * member's name may be dropped too. The staging tree is verified to hold only
+ * regular files and directories before anything is promoted into `dest`.
  *
  * The skill bundle's single wrapper directory is stripped: the archive is
  * extracted into a staging dir and the wrapper's contents are promoted into
@@ -215,6 +278,7 @@ export async function extractSkillArchive(resp: Response, dest: string): Promise
     fssync.createWriteStream(tmp),
   );
   const stage = path.join(path.dirname(dest), `.skill-stage-${process.pid}-${Date.now()}`);
+  const excludeFile = path.join(path.dirname(dest), `.skill-exclude-${process.pid}-${Date.now()}`);
   try {
     // Sniff the first bytes: zip archives start with "PK\x03\x04"; treat
     // anything else as a tar.* archive (`tar -xf` autodetects gzip/bzip2/xz).
@@ -224,25 +288,57 @@ export async function extractSkillArchive(resp: Response, dest: string): Promise
     const archiveCmd = isZip ? 'unzip' : 'tar';
     // List first, validate, then extract — `tar`/`unzip` will happily write a
     // `../` member (or follow a symlink member) outside `-C`/`-d` otherwise.
-    const listing = await runArchiveTool(archiveCmd, isZip ? ['-Z1', tmp] : ['-tf', tmp]);
-    assertSafeMemberNames(listing);
-    assertNoSpecialMembers(await runArchiveTool(archiveCmd, isZip ? ['-Z', tmp] : ['-tvf', tmp]));
-    const top = archiveTopDir(listing);
+    const names = await runArchiveTool(archiveCmd, isZip ? ['-Z1', tmp] : ['-tf', tmp]);
+    const typed = await runArchiveTool(archiveCmd, isZip ? ['-Z', '--h', '--t', tmp] : ['-tvf', tmp]);
+    const { plain, special } = classifyArchiveListing(archiveCmd, names, typed);
+    assertSafeMemberNames([...plain, ...special]);
+    const top = archiveTopDir(plain);
     await fs.mkdir(stage, { recursive: true, mode: DIR_CREATE_MODE });
-    await runArchiveTool(archiveCmd, isZip ? ['-oq', tmp, '-d', stage] : ['-xf', tmp, '-C', stage]);
+    // `unzip` exits non-zero when every member is excluded, so only run the
+    // extractor when there is something to extract.
+    if (plain.length > 0) {
+      await runArchiveTool(archiveCmd, await extractArgs(archiveCmd, tmp, stage, special, excludeFile));
+    }
+    await assertOnlyPlainEntries(stage);
     // Promote the wrapper's contents (or the staged tree itself, if the
     // archive wasn't wrapped) into the already-created empty `dest`. `stage`
     // is a sibling of `dest`, so each rename stays on one filesystem.
     const srcRoot = top ? path.join(stage, top) : stage;
-    for (const entry of await fs.readdir(srcRoot)) {
+    const entries = await fs.readdir(srcRoot).catch((e: unknown) => {
+      throw errnoCode(e) === 'ENOENT' ? new AnthropicError(INCONSISTENT_LISTING) : e;
+    });
+    for (const entry of entries) {
       await fs.rename(path.join(srcRoot, entry), path.join(dest, entry));
     }
   } finally {
     await fs.rm(tmp, { force: true });
+    await fs.rm(excludeFile, { force: true });
     await fs.rm(stage, { recursive: true, force: true });
   }
 }
 
+/**
+ * Arguments that extract `archive` into `stage` while excluding every member
+ * in `special`. Names are glob-escaped because both CLIs treat exclusions as
+ * patterns; `tar` reads them from `excludeFile`, `unzip` takes them after
+ * `-x`, which must follow `-d` so no pattern is parsed as an option.
+ */
+async function extractArgs(
+  cmd: 'unzip' | 'tar',
+  archive: string,
+  stage: string,
+  special: string[],
+  excludeFile: string,
+): Promise<string[]> {
+  const patterns = special.map((name) => name.replace(/[*?[\\]/g, '\\$&'));
+  if (cmd === 'unzip') {
+    return ['-oq', archive, '-d', stage, ...(patterns.length > 0 ? ['-x', ...patterns] : [])];
+  }
+  if (patterns.length === 0) return ['-xf', archive, '-C', stage];
+  await fs.writeFile(excludeFile, patterns.join('\n') + '\n', { flag: 'wx', mode: 0o600 });
+  return ['-xf', archive, '-C', stage, '-X', excludeFile];
+}
+
 /** Read the first `n` bytes of `file`. */
 async function readHead(file: string, n: number): Promise<Buffer> {
   const handle = await fs.open(file, 'r');

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.115.0'; // x-release-please-version
+export const VERSION = '0.117.1'; // x-release-please-version

package/tools/agent-toolset/fs-util.d.mts

@@ -8,12 +8,20 @@
 export declare const DIR_CREATE_MODE = 493;
 /** Mode for files the file tools create. */
 export declare const FILE_CREATE_MODE = 420;
+/** The `code` of a Node system error, or `undefined` for anything else. */
+export declare function errnoCode(err: unknown): string | undefined;
 /**
  * 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.
+ *
+ * Returns a symlink-free path or throws an errno-carrying error (`ELOOP` for a
+ * cycle or more than {@link MAX_SYMLINK_HOPS} links, the `lstat`/`realpath`
+ * error for an unreadable component); it never returns `abs` unresolved. Only
+ * symlink hops count against the cap, so any depth of not-yet-existing
+ * directories still resolves.
  */
 export declare function canonicalize(abs: string): Promise<string>;
 /**
@@ -25,6 +33,9 @@ export declare function canonicalize(abs: string): Promise<string>;
  * 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.
+ * `..` is collapsed lexically before any symlink is followed. A path that cannot
+ * be resolved (symlink loop, unreadable component) is rejected with a
+ * `ToolError` naming `p`, never the host's absolute path.
  *
  * 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
@@ -43,8 +54,9 @@ export declare function atomicWriteFile(targetPath: string, content: string): Pr
 /**
  * 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.
+ * `ENOENT: no such file...` text would otherwise leak through). Codes we don't
+ * special-case render as the bare code, never Node's message, which embeds the
+ * host's absolute path.
  */
 export declare function fsErrorMessage(err: unknown, file: string): string;
 //# sourceMappingURL=fs-util.d.mts.map

package/tools/agent-toolset/fs-util.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fs-util.d.mts","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,uFAAuF;AACvF,eAAO,MAAM,eAAe,MAAQ,CAAC;AACrC,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAWtC;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkC/D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBxF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjE"}
+{"version":3,"file":"fs-util.d.mts","sourceRoot":"","sources":["../../src/tools/agent-toolset/fs-util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,uFAAuF;AACvF,eAAO,MAAM,eAAe,MAAQ,CAAC;AACrC,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AActC,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,OAAO,CAAC,MAAM,CAAC,CAejB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBxF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjE"}