chore(deps): bump @anthropic-ai/claude-agent-sdk to ^0.3.302 #471

Summary

packages/core pinned @anthropic-ai/claude-agent-sdk at ^0.3.283. npm latest is now 0.3.302. This issue tracks bumping the floor to ^0.3.302.

Retargeted 2026-10-17. This issue originally tracked a bump to ^0.3.286. Upstream moved on while the PR was open, so the target is now 0.3.302 and #472 has been updated to match. The 0.3.284–0.3.286 notes are kept below for continuity.

Upstream changes, 0.3.287 → 0.3.302

Fourteen releases shipped in this window (0.3.297, 0.3.298, 0.3.294, 0.3.291, 0.3.289, 0.3.288 are CLI-parity only).

Breaking / behavioural

• 0.3.302 — an omitted permissionMode now starts in default mode on third-party providers, with telemetry off, or on a fresh install; pass permissionMode: 'auto' to keep auto mode. Same shape as the 0.3.286 change.
• 0.3.302 — fork subagents (subagent_type: "fork") are on by default in SDK sessions, matching the terminal. run_in_background is still offered; CLAUDE_CODE_FORK_SUBAGENT=0 turns them off.
• 0.3.300 — thinking: { type: 'disabled' } and maxThinkingTokens: 0 now run as adaptive thinking on models that can't turn thinking off.
• 0.3.300 — updatedInput from PreToolUse and PermissionRequest hook callbacks is now validated like Claude's own input, and unknown keys are dropped. canUseTool is unchanged.
• 0.3.300 — reverted the 0.3.292 suppressAlwaysAllowRule: true on canUseTool options for org-gated connector tools.
• 0.3.295 — the SDK now passes named option values to Claude Code in the same argument as the flag (--flag=value).
• 0.3.299 — initialize, mcp_set_servers and claim_session now refuse reserved MCP server names (__proto__, __defineGetter__, …).
• 0.3.301 — the full-disk login-refresh error is now invalid_request rather than authentication_failed, with api_error_status null instead of 401.

New API

• 0.3.301 — BUILTIN_TOOL_NAMES and LEGACY_TOOL_NAME_ALIASES exports; per-tool permission_policy (always_ask / always_deny) on sdk-type MCP server configs; addPlugins on Query.reloadPlugins().
• 0.3.296 — claude_code_version on the initialize control response; autoCompactWindow on AgentDefinition.
• 0.3.295 — overageEnabled on SDKRateLimitInfo.
• 0.3.292 — agent_id on subagent messages; parent_task_id; run_id / origin.runId; typed sections/notes on ListAgents; recipient_kind on SendMessage inputs.
• 0.3.293 — optional subagent_type on background_tasks_changed entries.
• 0.3.299 — nextFireAt on CronCreate/CronList output; property_order on elicitation.
• 0.3.290 — optional offset on WebFetch input.
• 0.3.287 — remote-session latency fields on the success result message.

Notable fixes we inherit
importSessionToStore skipping transcript rows containing U+2028/U+2029 on Node 24 and Bun (0.3.300); assistant text blocks losing citations in streamed responses (0.3.295); includePartialMessages streams never emitting message_stop on a cut/interrupted stream (0.3.287, 0.3.290); a tool call to an in-process MCP server left hanging after toggleMcpServer()/setMcpServers() (0.3.287); commands_changed arriving before init or twice at startup (0.3.287); setModel() failing while the account is at a usage limit (0.3.301); in-process SDK MCP servers named constructor/toString being dropped on SpareProcess.claim() (0.3.299); the sandbox option discarding an inline settings.sandbox block (0.3.296).

Also several new MCP payload size caps (0.3.287, 0.3.295, 0.3.296) — structuredContent, _meta and result-text truncation thresholds, with SDK-server tools generally exempt.

Impact on herdctl

Assessed as low — no adaptation required. Verified:

• Neither permissionMode default change reaches us. toSDKOptions (packages/core/src/runner/sdk-adapter.ts:181) always sets it (agent.permission_mode ?? "acceptEdits"), and cli-runtime.ts:241 always passes --permission-mode. An agent configured permission_mode: default still gets exactly default.
• The 0.3.300 thinking change is inert: herdctl never sets thinking or maxThinkingTokens in SDKQueryOptions.
• The 0.3.300 updatedInput validation is inert: packages/core/src/session/session-hooks.ts registers only Stop and PostToolUse callbacks, not PreToolUse or PermissionRequest.
• The 0.3.295 --flag=value change is internal to the SDK's own spawn path. herdctl's CLI runtime builds its own argv and is unaffected.
• API surface is additive: diffing sdk.d.ts, agentSdkTypes.d.ts, sdk-tools.d.ts, core.d.ts, bridge.d.ts from 0.3.286 → 0.3.302 shows exactly two added exports (BUILTIN_TOOL_NAMES, LEGACY_TOOL_NAME_ALIASES) and nothing removed. PermissionMode, SdkPluginConfig and SettingSource are byte-identical.
• Peer ranges unchanged: @anthropic-ai/sdk >=0.93.0, @modelcontextprotocol/sdk ^1.29.0, zod ^4.0.0.
• One runtime change to be aware of rather than fix: fork subagents default on in SDK sessions (0.3.302). herdctl's forkSession option is a different thing (session forking, not subagent_type: "fork").

Plan

• Bump packages/core/package.json to ^0.3.302 and refresh pnpm-lock.yaml
• pnpm build / pnpm typecheck / pnpm lint / pnpm test
• Changeset (patch, @herdctl/core)