@anthropic-ai/claude-agent-sdk 0.3.308 → 0.3.310

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,13 +6,18 @@
6
6
  // export — keep it standalone and Node-importable (no Bun globals, no
7
7
  // local-relative imports).
8
8
 
9
- import { createHash } from 'crypto'
9
+ import { createHash, randomBytes } from 'crypto'
10
10
  import {
11
11
  chmodSync,
12
- existsSync,
12
+ closeSync,
13
+ constants as fsConstants,
14
+ fchmodSync,
15
+ fstatSync,
13
16
  lstatSync,
14
17
  mkdirSync,
18
+ openSync,
15
19
  readFileSync,
20
+ readSync,
16
21
  renameSync,
17
22
  unlinkSync,
18
23
  writeFileSync,
@@ -34,28 +39,30 @@ function tmpdir() {
34
39
  return osTmpdir()
35
40
  }
36
41
 
37
- // Inlined from src/utils/tempfile.ts#claudeTempDir + verifyTempDirOwnership —
38
- // keep behavior in sync. Per-UID Claude temp directory: `{tmpdir()}/claude-{uid}`
39
- // on Unix, `{tmpdir()}/claude` on Windows (where %TEMP% is already per-user).
40
- //
41
- // Defense-in-depth against a local attacker pre-creating the extraction dir
42
- // before the victim's first run: the content-hash dir name is fully predictable
43
- // (sha256 of a public npm binary) under shared `/tmp`, and
44
- // `mkdirSync({recursive:true})` is a silent no-op on a pre-existing dir without
45
- // enforcing owner or mode. Without this check an attacker-owned directory would
46
- // be used as-is, letting them swap the binary the SDK later spawns.
42
+ // Per-user extraction root: `{tmpdir()}/claude-agent-sdk-{uid}` on Unix,
43
+ // `{tmpdir()}/claude-agent-sdk` on Windows (where %TEMP% is already per-user).
44
+ // Deliberately NOT Claude Code's own temp root `{tmpdir()}/claude-{uid}`: that
45
+ // is the writable $TMPDIR Claude Code gives the commands it runs inside the
46
+ // Bash-tool sandbox, while the SDK application spawns the extracted CLI with
47
+ // no sandbox, so it lives where the sandbox's default write roots do not reach.
47
48
  function safeTempBase() {
48
49
  const dir = join(
49
50
  tmpdir(),
50
51
  process.platform === 'win32'
51
- ? 'claude'
52
- : `claude-${process.getuid?.() ?? 0}`,
52
+ ? 'claude-agent-sdk'
53
+ : `claude-agent-sdk-${process.getuid?.() ?? 0}`,
53
54
  )
54
- // Gate on getuid (POSIX-only) rather than process.platform: getuid presence
55
- // reflects the real OS. No-op on Windows where %TEMP% is already per-user.
55
+ // Create it 0700 and refuse anything but a directory this user owns: its
56
+ // name is predictable, and recursive mkdir silently accepts one that another
57
+ // local user pre-created in a shared /tmp. A same-user writer that reaches
58
+ // the temp dir can race this check; the byte comparison in extractFromBunfs()
59
+ // only stops it planting a file for a later start, not replacing one mid-run.
60
+ // Gated on getuid rather than process.platform, which tests mock.
56
61
  if (typeof process.getuid === 'function') {
57
62
  mkdirSync(dir, { recursive: true, mode: 0o700 })
58
63
  const uid = process.getuid()
64
+ // An older, path-based copy of src/utils/tempfile.ts#verifyTempDirOwnership,
65
+ // which now checks and tightens the directory through one fd.
59
66
  const st = lstatSync(dir)
60
67
  if (!st.isDirectory()) {
61
68
  throw new Error(
@@ -83,9 +90,86 @@ function safeTempBase() {
83
90
  return dir
84
91
  }
85
92
 
93
+ // Copy of src/utils/noFileIdentity.ts#hasNoFileIdentity (this file ships
94
+ // standalone and cannot import it): a stat file id that names no object.
95
+ function isNoFileId(ino) {
96
+ return (
97
+ ino === 0n ||
98
+ ino === -1n ||
99
+ ino === 0xffff_ffff_ffff_ffffn ||
100
+ ino === 1n << 64n
101
+ )
102
+ }
103
+
104
+ // True when `file` is a regular file (not a symlink, no second hard link)
105
+ // whose bytes equal `content`. A symlink or a second link would let the bytes
106
+ // change later through a path outside this directory.
107
+ function isExtractedCopy(file, content) {
108
+ let fd
109
+ let inoAtPath
110
+ try {
111
+ if (typeof process.getuid === 'function') {
112
+ // Judge the opened file itself: O_NOFOLLOW refuses a symlink at the path
113
+ // and O_NONBLOCK keeps a planted FIFO from hanging the open. Gated on
114
+ // getuid because Bun on Windows defines these flags with unusable values.
115
+ fd = openSync(
116
+ file,
117
+ fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK,
118
+ )
119
+ } else {
120
+ const atPath = lstatSync(file, { bigint: true })
121
+ if (!atPath.isFile()) {
122
+ return false
123
+ }
124
+ inoAtPath = atPath.ino
125
+ fd = openSync(file, 'r')
126
+ }
127
+ const st = fstatSync(fd, { bigint: true })
128
+ if (
129
+ !st.isFile() ||
130
+ Number(st.nlink) !== 1 ||
131
+ Number(st.size) !== content.length
132
+ ) {
133
+ return false
134
+ }
135
+ // Windows has no usable O_NOFOLLOW, so that open may have followed
136
+ // something swapped in after the lstat: treat it as not our copy unless the
137
+ // fd is the same file, by file id alone as in
138
+ // src/utils/noFileIdentity.ts#openedAnotherFile; an id of 0 or all-ones
139
+ // proves nothing.
140
+ if (
141
+ inoAtPath !== undefined &&
142
+ !isNoFileId(inoAtPath) &&
143
+ !isNoFileId(st.ino) &&
144
+ st.ino !== inoAtPath
145
+ ) {
146
+ return false
147
+ }
148
+ const chunk = Buffer.allocUnsafe(1 << 20)
149
+ let offset = 0
150
+ while (offset < content.length) {
151
+ const n = readSync(fd, chunk, 0, chunk.length, offset)
152
+ if (
153
+ n <= 0 ||
154
+ !chunk.subarray(0, n).equals(content.subarray(offset, offset + n))
155
+ ) {
156
+ return false
157
+ }
158
+ offset += n
159
+ }
160
+ return true
161
+ } catch {
162
+ return false
163
+ } finally {
164
+ if (fd !== undefined) {
165
+ closeSync(fd)
166
+ }
167
+ }
168
+ }
169
+
86
170
  /**
87
- * If `embeddedPath` is inside Bun's $bunfs virtual filesystem, extract it to a
88
- * temp directory and return the real path. Otherwise return the path unchanged.
171
+ * If `embeddedPath` is inside Bun's $bunfs, extract it to a per-user directory
172
+ * under the temp dir (CLAUDE_CODE_TMPDIR if set); otherwise return it as is.
89
173
  *
90
174
  * Uses a content hash for the directory name so that:
91
175
  * - Same binary version reuses the same extracted file (no accumulation)
@@ -112,39 +196,84 @@ export function extractFromBunfs(embeddedPath) {
112
196
  const fileName = basename(embeddedPath)
113
197
  const tmpPath = join(tmpDir, fileName)
114
198
  mkdirSync(tmpDir, { recursive: true, mode: 0o700 })
115
- // The directory is content-hash-keyed, so an existing tmpPath is byte-
116
- // identical to what we would write — short-circuit. This is a write
117
- // idempotency check on a content-addressed path, not a read TOCTOU
118
- // (the existence IS the contract). Without it, a second call (or a
119
- // concurrent app instance) on Windows would hit EPERM/EBUSY renaming over
120
- // the memory-mapped running .exe and fall back to the unspawnable $bunfs
121
- // path. It also skips a redundant write+chmod on every call.
122
- if (existsSync(tmpPath)) {
199
+ // Recursive mkdir accepts an existing symlink to a directory; refuse it, or
200
+ // every path below would resolve wherever the link points.
201
+ if (!lstatSync(tmpDir).isDirectory()) {
202
+ throw new Error(
203
+ 'The claude-agent-sdk-<hash> folder under the temp directory is a symlink or not a directory, possibly planted; delete it and restart',
204
+ )
205
+ }
206
+ // Reuse an earlier extraction only after re-reading it: a plain file with
207
+ // exactly these bytes. The owner-only root sits outside the Bash-tool
208
+ // sandbox's default write roots, but a widened write grant can still reach
209
+ // it; anything else found at the path is replaced below, or extraction
210
+ // fails. On Windows reuse also avoids renaming over the running,
211
+ // memory-mapped .exe, which fails.
212
+ if (isExtractedCopy(tmpPath, content)) {
123
213
  return tmpPath
124
214
  }
125
215
  // Write to a temp file and atomically rename to avoid truncation races —
126
216
  // concurrent readers always see either the old complete file or the new one.
127
- const tmpFile = join(tmpDir, `${fileName}.tmp.${process.pid}`)
128
- writeFileSync(tmpFile, content)
129
- chmodSync(tmpFile, 0o755)
217
+ // Unguessable name, exclusive create: a name planted in advance (say a
218
+ // symlink to a file elsewhere) is never written through or renamed into
219
+ // place.
220
+ const tmpFile = join(
221
+ tmpDir,
222
+ `${fileName}.tmp.${process.pid}.${randomBytes(8).toString('hex')}`,
223
+ )
224
+ const fd = openSync(tmpFile, 'wx', 0o700)
225
+ let renamed = false
130
226
  try {
131
- renameSync(tmpFile, tmpPath)
132
- } catch (e) {
133
- if ((e.code === 'EPERM' || e.code === 'EBUSY') && existsSync(tmpPath)) {
134
- // Lost a concurrent first-time-extraction race on Windows: the winner's
135
- // child holds tmpPath memory-mapped, so the loser's rename over it fails.
136
- // The content-hash dir guarantees byte-identity, so the winner's file is
137
- // exactly what we'd have written — use it.
227
+ try {
228
+ writeFileSync(fd, content)
229
+ // Through the fd, so a name swapped for a symlink mid-write cannot
230
+ // redirect the mode change to another file.
231
+ fchmodSync(fd, 0o755)
232
+ } finally {
233
+ closeSync(fd)
234
+ }
235
+ try {
236
+ renameSync(tmpFile, tmpPath)
237
+ } catch (e) {
238
+ // Bun on Windows refuses to rename onto an existing file (EEXIST, or
239
+ // EPERM/EBUSY while another process has that .exe mapped or a scanner
240
+ // briefly holds our new file). An identical copy already there (a
241
+ // concurrent first extraction won the race) is as good as ours;
242
+ // anything else is removed and the rename retried once.
243
+ if (e.code !== 'EEXIST' && e.code !== 'EPERM' && e.code !== 'EBUSY') {
244
+ throw e
245
+ }
246
+ if (isExtractedCopy(tmpPath, content)) {
247
+ return tmpPath
248
+ }
249
+ try {
250
+ unlinkSync(tmpPath)
251
+ } catch (unlinkError) {
252
+ if (unlinkError.code !== 'ENOENT') {
253
+ throw unlinkError
254
+ }
255
+ }
256
+ try {
257
+ renameSync(tmpFile, tmpPath)
258
+ } catch {
259
+ // A concurrent start may have put its own copy in place first.
260
+ if (isExtractedCopy(tmpPath, content)) {
261
+ return tmpPath
262
+ }
263
+ throw e
264
+ }
265
+ }
266
+ renamed = true
267
+ return tmpPath
268
+ } finally {
269
+ if (!renamed) {
138
270
  try {
139
271
  unlinkSync(tmpFile)
140
272
  } catch {
141
- // best-effort cleanup of our orphaned .tmp.{pid} file
273
+ // best-effort cleanup of our unused temp file
142
274
  }
143
- return tmpPath
144
275
  }
145
- throw e
146
276
  }
147
- return tmpPath
148
277
  } catch (err) {
149
278
  // oxlint-disable-next-line no-console -- intentional user-facing warning in standalone SDK helper
150
279
  console.warn(
package/manifest.json CHANGED
@@ -1,55 +1,52 @@
1
1
  {
2
- "version": "2.1.308",
2
+ "version": "2.1.310",
3
3
  "manifestSignatureEnforcement": "flag",
4
- "commit": "320f66eb8f834be58a10c98283ebef19e3640c37",
5
- "buildDate": "2026-10-22T03:48:37Z",
4
+ "commit": "0d2056ecf42d9452a8cd8e054600024e7c557add",
5
+ "buildDate": "2026-10-23T20:13:54Z",
6
6
  "platforms": {
7
7
  "darwin-arm64": {
8
8
  "binary": "claude",
9
- "checksum": "ca923c86ac84b30574a82331a05b6e066c27477a926ceaffe46a845a33e4dd37",
10
- "size": 274675680
9
+ "checksum": "ffb64331bc0ee1b69efb7c2c428bd3ab516bc31b75bf60886b356c97c1c25ffd",
10
+ "size": 274068224
11
11
  },
12
12
  "darwin-x64": {
13
13
  "binary": "claude",
14
- "checksum": "9a0bc140f5fb06e6366624d770371ef290e6731d1e84c4def5daf4df946d1b59",
15
- "size": 285902384
14
+ "checksum": "28fdbed5a84ef7d4205b5751c7f021e79151c4e319c4a401e48fe6aae86bbb39",
15
+ "size": 285291472
16
16
  },
17
17
  "linux-arm64": {
18
18
  "binary": "claude",
19
- "checksum": "fdd22e6cbb734d580f5664c48df4294eeec850218ff07f186f9af30426396ee1",
20
- "size": 292085944
19
+ "checksum": "9c64d9a7442436b65fcd7cc02c1aa0051bb5a7041e7788576ed3b5f29c447d54",
20
+ "size": 291496120
21
21
  },
22
22
  "linux-x64": {
23
23
  "binary": "claude",
24
- "checksum": "356733f185fa988e6bf3aa9a555269fdd167982a2e2a80d3c8a78037bb92ad58",
25
- "size": 292232560
24
+ "checksum": "b73676430af12f97316a798b8371f81d640f90a58bdcb8f3ce56a835bb47df56",
25
+ "size": 291638640
26
26
  },
27
27
  "linux-arm64-musl": {
28
28
  "binary": "claude",
29
- "checksum": "b820bec20177aa09875515cf5ffadb445ecf814ec7c8ed51ba2f86c3090a692d",
30
- "size": 284313472
29
+ "checksum": "adfd1f0ef12a3bcafa66e33491fc3e4204e41aeb4a7305ffc311c16c26793825",
30
+ "size": 283658112
31
31
  },
32
32
  "linux-x64-musl": {
33
33
  "binary": "claude",
34
- "checksum": "45cc10091e10ca658daa691e879058ba1d4752218c63577d1c7d54b0c7dc9a68",
35
- "size": 285896848
34
+ "checksum": "2ceb05e0a97b09be4c14717464a2156e8d087dea9867a399dd75d3b898ca4824",
35
+ "size": 285302928
36
36
  },
37
37
  "win32-x64": {
38
38
  "binary": "claude.exe",
39
- "checksum": "c9796ba22a9221586b36371b36f5b66198d66eb4badf6a4cf4a5f7b07becea53",
40
- "size": 297376928
39
+ "checksum": "f9a3920634ae3b961ee92c2eb58d0051f5f8852b120983d0a4f57b6a5efeba61",
40
+ "size": 296791712
41
41
  },
42
42
  "win32-arm64": {
43
43
  "binary": "claude.exe",
44
- "checksum": "35b5af5dde46a775ccd5a4d15760913c6088cf7292e1b15f0b09b1fd3f93bfd2",
45
- "size": 281453216
44
+ "checksum": "91da8a2247a8806162319bcdf3e70c6ffeeb58b568481a9827fbff167a694edb",
45
+ "size": 280850592
46
46
  }
47
47
  },
48
48
  "sdkCompat": {
49
49
  "testedWrapperVersions": [
50
- "0.3.274",
51
- "0.3.275",
52
- "0.3.276",
53
50
  "0.3.277",
54
51
  "0.3.278",
55
52
  "0.3.280",
@@ -75,7 +72,8 @@
75
72
  "0.3.302",
76
73
  "0.3.303",
77
74
  "0.3.304",
78
- "0.3.305"
75
+ "0.3.305",
76
+ "0.3.306"
79
77
  ],
80
78
  "harnessSchema": 1
81
79
  }
package/manifest.zst.json CHANGED
@@ -1,63 +1,60 @@
1
1
  {
2
- "version": "2.1.308",
2
+ "version": "2.1.310",
3
3
  "manifestSignatureEnforcement": "flag",
4
- "commit": "320f66eb8f834be58a10c98283ebef19e3640c37",
5
- "buildDate": "2026-10-22T03:50:00Z",
4
+ "commit": "0d2056ecf42d9452a8cd8e054600024e7c557add",
5
+ "buildDate": "2026-10-23T20:15:35Z",
6
6
  "platforms": {
7
7
  "darwin-arm64": {
8
8
  "binary": "claude.zst",
9
- "checksum": "e4d214226582e2f52eafa3de4b2f55469677974e49e6e96376aad740c37d2557",
10
- "size": 92822156,
9
+ "checksum": "0252ecc7c918fccc5a68d6f25a80c4579c4cf99fad8b315228236c2ee9c3f4af",
10
+ "size": 92705677,
11
11
  "bundle": {
12
- "checksum": "a93ded4b1b47515ff4ce671f79070a5398c47b62c13298a01067334a53f65764",
13
- "size": 92821576
12
+ "checksum": "1c80fdf086c7cc9d88430c466dfd9259fcfcc1a1824ddf11ea0803767c464891",
13
+ "size": 92707820
14
14
  }
15
15
  },
16
16
  "darwin-x64": {
17
17
  "binary": "claude.zst",
18
- "checksum": "540f89af5ad8e2048390719961739939d59d64a0f3b01af1a158cb1be6f412ae",
19
- "size": 98219435,
18
+ "checksum": "7c82300870d0b0eb565922f6e12bf7ebc0a1e3a35ebb61af55aab883af62d680",
19
+ "size": 98096628,
20
20
  "bundle": {
21
- "checksum": "21d7adb424d30f022ab6094c19b54fc2c991a98a780bc05597c69f6fc44bd1da",
22
- "size": 98232302
21
+ "checksum": "c119f31f16e4e8380028a5516809d5f9041251af395a4a827b96238ca98e8b43",
22
+ "size": 98116332
23
23
  }
24
24
  },
25
25
  "linux-arm64": {
26
26
  "binary": "claude.zst",
27
- "checksum": "6f872ce2362e3485abbd7dcb921514e3319ebe36c2efabb7193f128ed337d8d4",
28
- "size": 102117787
27
+ "checksum": "ad34932dfad2bd67c328b9358acaac7c998e8113dc065dd328958b984a73fe27",
28
+ "size": 102027606
29
29
  },
30
30
  "linux-x64": {
31
31
  "binary": "claude.zst",
32
- "checksum": "f8b3641a8d3664420bde0153433e03fd3fad5351a1a12cf6f798ed86c52c9ea9",
33
- "size": 103095977
32
+ "checksum": "9314f28f679546a97813f2914c4fb60a190801ef782805f47bf197317cc4ffd2",
33
+ "size": 102993457
34
34
  },
35
35
  "linux-arm64-musl": {
36
36
  "binary": "claude.zst",
37
- "checksum": "855a21751041185dbd5d73386e5a9e454f0ce434a8a4b23cb2ca66add70b5427",
38
- "size": 100464884
37
+ "checksum": "f4dc063aae358589c4b58027a5a2e0d8bdccde16109af11407301a50bb349281",
38
+ "size": 100369361
39
39
  },
40
40
  "linux-x64-musl": {
41
41
  "binary": "claude.zst",
42
- "checksum": "0c66f9a325b6c5c308272fd087c0f0994e6ebc081e64a4a51fcbcfbbfb484c37",
43
- "size": 101509546
42
+ "checksum": "ac75639744e4185547254e3d1054089d6a78747b4b838783f3b758ca369c77f1",
43
+ "size": 101393542
44
44
  },
45
45
  "win32-x64": {
46
46
  "binary": "claude.exe.zst",
47
- "checksum": "c17a819afb40d41ed558bacd5c432b52efdd004fe98068e6b47e77f540156bb9",
48
- "size": 106384354
47
+ "checksum": "f37a98ecff44e2605a30985bff7ba7c7a87bd936539eb3681a97b0c9794180a8",
48
+ "size": 106282873
49
49
  },
50
50
  "win32-arm64": {
51
51
  "binary": "claude.exe.zst",
52
- "checksum": "23655dab55802075e1652adb7117354424998ac4a9acca678ac2bf8903c79310",
53
- "size": 101582794
52
+ "checksum": "691b41c2a6e91f094dbc501421eeb2a6c667ca98632894814c609ed1886c6b57",
53
+ "size": 101465393
54
54
  }
55
55
  },
56
56
  "sdkCompat": {
57
57
  "testedWrapperVersions": [
58
- "0.3.274",
59
- "0.3.275",
60
- "0.3.276",
61
58
  "0.3.277",
62
59
  "0.3.278",
63
60
  "0.3.280",
@@ -83,7 +80,8 @@
83
80
  "0.3.302",
84
81
  "0.3.303",
85
82
  "0.3.304",
86
- "0.3.305"
83
+ "0.3.305",
84
+ "0.3.306"
87
85
  ],
88
86
  "harnessSchema": 1
89
87
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@anthropic-ai/claude-agent-sdk",
3
- "version": "0.3.308",
3
+ "version": "0.3.310",
4
4
  "main": "sdk.mjs",
5
5
  "types": "sdk.d.ts",
6
6
  "exports": {
@@ -61,14 +61,14 @@
61
61
  "zod": "^4.0.0"
62
62
  },
63
63
  "optionalDependencies": {
64
- "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.308",
65
- "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.308",
66
- "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.308",
67
- "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.308",
68
- "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.308",
69
- "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.308",
70
- "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.308",
71
- "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.308"
64
+ "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.310",
65
+ "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.310",
66
+ "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.310",
67
+ "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.310",
68
+ "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.310",
69
+ "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.310",
70
+ "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.310",
71
+ "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.310"
72
72
  },
73
73
  "files": [
74
74
  "sdk.mjs",
@@ -85,10 +85,10 @@
85
85
  "extractFromBunfs.d.ts",
86
86
  "manifest.json",
87
87
  "manifest.zst.json",
88
- "core-36zyfan5.mjs",
89
- "core-5682eevd.mjs",
90
- "core-nne0e2ds.mjs",
91
- "core-xpxe8nzb.mjs"
88
+ "core-4pv47a2z.mjs",
89
+ "core-bz5kkzv0.mjs",
90
+ "core-c86d180z.mjs",
91
+ "core-pzfwbvz7.mjs"
92
92
  ],
93
- "claudeCodeVersion": "2.1.308"
93
+ "claudeCodeVersion": "2.1.310"
94
94
  }
package/sdk.d.ts CHANGED
@@ -1227,6 +1227,7 @@ export declare type McpSdkServerConfig = {
1227
1227
  */
1228
1228
  timeout?: number;
1229
1229
 
1230
+
1230
1231
  /**
1231
1232
  * Per-tool permission policy the host declares for this server's tools (not the tool definitions passed to createSdkMcpServer). always_ask: the CLI asks the host (canUseTool or the permission prompt tool) before each call, even where an allow rule or allowedTools covers the tool, and under bypassPermissions outside a hosted remote session (CLAUDE_CODE_REMOTE); under dontAsk the call is denied; in auto mode the classifier decides, except that by default a tool annotated destructiveHint still asks. always_deny: calls are denied. always_allow and org_max_permission are ignored on sdk servers; grant allows with allowedTools or canUseTool. Read from initialize (sdkMcpServerConfigs) and from each mcp_set_servers entry that names the server. On the wire an entry without tools states no policy: on initialize the stored list and the rules stand; on mcp_set_servers the rules are replaced without them. The Agent SDK always re-sends the registered list. An entry whose policy is not one of the three asks; an entry without a string name is dropped and the rest apply; a value that is not a list reads as absent.
1232
1233
  */
@@ -1287,6 +1288,9 @@ export declare type McpServerStatus = {
1287
1288
  * Server configuration (includes URL for HTTP/SSE servers)
1288
1289
  */
1289
1290
  config?: McpServerStatusConfig;
1291
+
1292
+
1293
+
1290
1294
  /**
1291
1295
  * Configuration scope (e.g., project, user, local, claudeai, managed)
1292
1296
  */
@@ -2275,6 +2279,18 @@ export declare type Options = {
2275
2279
  * tier present, these apply as the sole policy tier (still filtered
2276
2280
  * restrictive-only — non-allowlisted keys are dropped regardless).
2277
2281
  *
2282
+ * Two hook keys are filtered by value rather than kept as written:
2283
+ * `disableAllHooks: true` binds as `allowManagedHooksOnly: true`, so the
2284
+ * machine administrator's own hooks keep running where the embedder's tier
2285
+ * cannot stop them — and because an enterprise configuration often yields
2286
+ * a boolean as text, any value but `false` and `"false"` binds it the same
2287
+ * way — and `allowedHttpHookUrls` / `httpHookAllowedEnvVars`
2288
+ * bind only as the empty list (admit nothing) — a non-empty one is dropped,
2289
+ * because these lists union across settings sources and would widen an
2290
+ * admin's. For the same reason an empty list binds only where no other
2291
+ * source sets one; pair it with `allowManagedHooksOnly` to stop a project's
2292
+ * HTTP hooks outright.
2293
+ *
2278
2294
  * Intended for embedding applications (e.g. desktop apps) that derive
2279
2295
  * lockdown settings from their own enterprise configuration and need to
2280
2296
  * enforce them on the spawned subprocess without writing root-owned files.
@@ -3207,6 +3223,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
3207
3223
 
3208
3224
 
3209
3225
 
3226
+
3210
3227
  /**
3211
3228
  * Reconnect an MCP server by name.
3212
3229
  * Throws on failure.
@@ -4652,7 +4669,7 @@ declare type SDKControlInitializeRequest = {
4652
4669
  hooks?: Partial<Record<coreTypes.HookEvent, SDKHookCallbackMatcher[]>>;
4653
4670
  sdkMcpServers?: string[];
4654
4671
  /**
4655
- * Settings for the SDK-hosted MCP servers named in sdkMcpServers, keyed by server name. Sent as a separate field so a CLI that predates it ignores it; entries whose name is not in sdkMcpServers, and values that do not match this shape, are ignored rather than rejected. timeout and disableAutoBackground apply when the server is first registered; tools (the per-tool permission policy) adds its ask and deny rules on every initialize that names the server. An initialize never removes a rule; mcp_set_servers replaces them.
4672
+ * Settings for the SDK-hosted MCP servers named in sdkMcpServers, keyed by server name. Sent as a separate field so a CLI that predates it ignores it; entries whose name is not in sdkMcpServers, and values that do not match this shape, are ignored rather than rejected. timeout, disableAutoBackground and connectorId apply when the server is first registered; tools (the per-tool permission policy) adds its ask and deny rules on every initialize that names the server. An initialize never removes a rule; mcp_set_servers replaces them.
4656
4673
  */
4657
4674
  sdkMcpServerConfigs?: Record<string, {
4658
4675
  /**
@@ -4660,6 +4677,7 @@ declare type SDKControlInitializeRequest = {
4660
4677
  */
4661
4678
  timeout?: number;
4662
4679
 
4680
+
4663
4681
  /**
4664
4682
  * Per-tool permission policy the host declares for this server's tools (not the tool definitions passed to createSdkMcpServer). always_ask: the CLI asks the host (canUseTool or the permission prompt tool) before each call, even where an allow rule or allowedTools covers the tool, and under bypassPermissions outside a hosted remote session (CLAUDE_CODE_REMOTE); under dontAsk the call is denied; in auto mode the classifier decides, except that by default a tool annotated destructiveHint still asks. always_deny: calls are denied. always_allow and org_max_permission are ignored on sdk servers; grant allows with allowedTools or canUseTool. Read from initialize (sdkMcpServerConfigs) and from each mcp_set_servers entry that names the server. On the wire an entry without tools states no policy: on initialize the stored list and the rules stand; on mcp_set_servers the rules are replaced without them. The Agent SDK always re-sends the registered list. An entry whose policy is not one of the three asks; an entry without a string name is dropped and the rest apply; a value that is not a list reads as absent.
4665
4683
  */
@@ -4791,6 +4809,7 @@ export declare type SDKControlInitializeResponse = {
4791
4809
 
4792
4810
 
4793
4811
 
4812
+
4794
4813
  };
4795
4814
 
4796
4815
  /**
@@ -4974,6 +4993,10 @@ declare type SDKControlMcpSetServersRequest = {
4974
4993
  */
4975
4994
  declare type SDKControlMcpStatusRequest = {
4976
4995
  subtype: 'mcp_status';
4996
+ /**
4997
+ * When true and the CLI writes to the session through CCR (a cloud session's worker, or a Remote Control worker), the success reply is published only to the clients attached at that moment, as a control_response marked live_only: true on the session's unsequenced event stream, and is not stored with the session's events; on a cloud session's worker its rows embed each server's configuration (URLs, headers, OAuth settings). Set it only if your client reads control_response frames from that stream; a reply sent while its stream is down is lost and the request must be sent again, and a reply over the live size limit comes back as a live error instead. Error replies other than that size-limit error, and every reply from hosts that do not send live replies (stdio hosts, and CLIs older than this field), are ordinary stored replies, so a client that sets it must accept either.
4998
+ */
4999
+ liveReply?: boolean;
4977
5000
  };
4978
5001
 
4979
5002
  /**
@@ -5036,7 +5059,7 @@ declare type SDKControlPermissionRequest = {
5036
5059
 
5037
5060
  description?: string;
5038
5061
  /**
5039
- * True when one-tap Approve/Deny must not be offered: the tool's approval card IS the user-interaction surface (Tool.requiresUserInteraction(): the user responds on the card itself), OR the pending ask is localDisplayOnly (its consent disclosure cannot ride this wire and only the local dialog renders it), OR the auto-mode classifier blocked the call and it was handed to a person (decision_reason_type 'classifier' on a person-only ask), which no stored grant or automatic approval may answer, OR the SDK host worded the ask (title and description are its consent copy, which a push cannot carry whole). In each case the user has to open the session to answer.
5062
+ * True when one-tap Approve/Deny must not be offered: the tool's approval card IS the user-interaction surface (Tool.requiresUserInteraction(): the user responds on the card itself), OR the pending ask is localDisplayOnly (its consent disclosure cannot ride this wire and only the local dialog renders it), OR the auto-mode classifier blocked the call and it was handed to a person (decision_reason_type 'classifier' on a person-only ask), which no stored grant or automatic approval may answer, OR the MCP server's name spells a claude.ai connector's key and the server came from neither claude.ai nor whoever launched the session, so a grant keyed on the tool name must not answer it, OR the SDK host worded the ask (title and description are its consent copy, which a push cannot carry whole). In each case the user has to open the session to answer.
5040
5063
  */
5041
5064
  requires_user_interaction?: boolean;
5042
5065
 
@@ -5283,7 +5306,7 @@ declare type SDKControlSetColorRequest = {
5283
5306
  };
5284
5307
 
5285
5308
  /**
5286
- * Sets the maximum number of thinking tokens for extended thinking. When max_thinking_tokens is null, thinking resets to the session default: any mid-session budget override is cleared (back to the spawn-time budget, if one was set), and thinking stays off for sessions that have it disabled. When max_thinking_tokens is omitted, the budget is left as it is, so a request that only changes thinking_display can leave the field out. thinking_display optionally sets the thinking display mode for the rest of the session: a value replaces the session display mode, null clears that override so Claude Code's default display handling applies again, and when omitted the display mode from session start (--thinking-display) is kept. 'highlights' returns one short title per stretch of thinking instead of a prose summary. The API accepts it only from Claude Code sessions that Anthropic hosts; if the API rejects it, the session sends 'omitted' (no thinking text) in its place from then on. A request for 'highlights' gets an error reply after such a rejection, on Amazon Bedrock, Google Vertex AI or another provider to which Claude Code sends no first-party-only beta features, when experimental betas are off (CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS or organization policy), or on a Claude 3 model (except on Microsoft Foundry). The error names which of these it was; the display stays as it was, and max_thinking_tokens still applies when the request has it.
5309
+ * Sets the maximum number of thinking tokens for extended thinking. When max_thinking_tokens is null, thinking resets to the session default: any mid-session budget override is cleared (back to the spawn-time budget, if one was set), and thinking stays off for sessions that have it disabled. When max_thinking_tokens is omitted, the budget is left as it is, so a request that only changes thinking_display can leave the field out. thinking_display optionally sets the thinking display mode for the rest of the session: a value replaces the session display mode, null clears that override so Claude Code's default display handling applies again, and when omitted the display mode from session start (--thinking-display) is kept. 'highlights' returns one short title per stretch of thinking instead of a prose summary. The API accepts it only from Claude Code sessions that Anthropic hosts; if the API rejects it, the session sends 'omitted' (no thinking text) in its place from then on. A request for 'highlights' gets an error reply after such a rejection, when experimental betas are off (CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS or organization policy), on a Claude 3 model (except on Microsoft Foundry), or on Amazon Bedrock (Mantle included), Google Vertex AI or a Claude apps gateway (API provider "gateway") with a model released before Claude Opus 4.7. The error names which of these it was; the display stays as it was, and max_thinking_tokens still applies when the request has it.
5287
5310
  */
5288
5311
  declare type SDKControlSetMaxThinkingTokensRequest = {
5289
5312
  subtype: 'set_max_thinking_tokens';
@@ -5929,6 +5952,7 @@ export declare type SDKResultError = {
5929
5952
  modelUsage: Record<string, ModelUsage>;
5930
5953
 
5931
5954
 
5955
+
5932
5956
  permission_denials: SDKPermissionDenial[];
5933
5957
  /**
5934
5958
  * User-initiated sends still waiting in the command queue when this result was produced. Greater than 0 means at least one more user turn (and result) follows without further input, barring cancellation; 0 means none is pending, or the session is ending (end_session or a shutdown latched mid-turn discards the backlog). Queued sends may coalesce into fewer turns, so this counts pending sends, not remaining results. System-generated queue entries are not counted. Absent on fatal startup results and on surfaces without a command queue.
@@ -6045,6 +6069,7 @@ export declare type SDKResultSuccess = {
6045
6069
  modelUsage: Record<string, ModelUsage>;
6046
6070
 
6047
6071
 
6072
+
6048
6073
  permission_denials: SDKPermissionDenial[];
6049
6074
  /**
6050
6075
  * User-initiated sends still waiting in the command queue when this result was produced. Greater than 0 means at least one more user turn (and result) follows without further input, barring cancellation; 0 means none is pending, or the session is ending (end_session or a shutdown latched mid-turn discards the backlog). Queued sends may coalesce into fewer turns, so this counts pending sends, not remaining results. System-generated queue entries are not counted. Absent on fatal startup results and on surfaces without a command queue.