Claude Agent SDKClaude Agent SDK

• Anthropic 商业条款的具体约束（尤其面向客户的场景）
• TypeScript 版的授权状态
• 会话持久化的多进程并发语义
• session forking 的具体形态与限制
• permission_mode 全部取值与 can_use_tool 的优先级细节
• 捆绑 CLI 版本与系统安装版本的兼容差异

• The specific constraints of Anthropic's Commercial Terms (especially customer-facing scenarios)
• The TypeScript version's authorization status
• Multi-process concurrency semantics of session persistence
• The exact shape and limits of session forking
• All permission_mode values and the precedence details of can_use_tool
• Compatibility differences between the bundled CLI version and a system-installed version

本档未跑集成与性能实测；结论只覆盖 API 与官方文档披露的能力面。

实测建议：

This site has not completed measured runs.

The test protocol is at protocols/framework/_protocol.md.

Suggested measurement:

README 首行就把这事说了：

Python SDK for Claude Agent. The Claude Code CLI is automatically bundled with the package — no separate installation required!

捆绑的是哪个 CLI，有确切记录：

核验 _cli_version.py：__cli_version__ = "2.1.286"（捆绑的确切 CLI 版本）。

这意味着能力边界是固定的：

与 OpenAI Agents SDK 的根本差别：

• 后者是自建 agent loop 的框架（primitives-only）
• 本 SDK 是既有 CLI 的 SDK 化

这是本站最需要讲清的一组对照。

The README's first line already says it:

Python SDK for Claude Agent. The Claude Code CLI is automatically bundled with the package — no separate installation required!

Which CLI is bundled has an exact record:

verified _cli_version.py: __cli_version__ = "2.1.286" (the exact bundled CLI version).

This means the capability boundary is fixed:

The fundamental difference vs the OpenAI Agents SDK:

• the latter is a framework that builds its own agent loop (primitives-only)
• this SDK is the SDK-ification of an existing CLI

This is the contrast pair this site most needs to make clear.

换 provider 这条路，在这套 SDK 上是关着的。

⚠ 这直接关掉了本站的一条推荐路线。

• 模型层（models.specul.com）主推的本地量化模型 + Ollama/vLLM 自托管
• 在这套 SDK 上走不通 —— 想用本地权重就得换方案

The provider-swap path is closed on this SDK.

⚠ This directly closes one of this site's recommended routes.

• the model layer (models.specul.com) mainly recommends local quantized models + Ollama/vLLM self-hosting
• it does not work on this SDK — to use local weights you must switch solutions

官方给了完整的权限求值链 —— 这是本站目前见到的最详细的一份。

README 这段是权威说明：

allowed_tools is a permission allowlist: listed tools are auto-approved, and unlisted tools fall through to permission_mode and can_use_tool for a decision. It does not remove tools from Claude's toolset. To block specific tools, use disallowed_tools.

翻译成一张表：

⚠ 默认起步状态必须知道：

By default, Claude has access to the full Claude Code toolset (Read, Write, Edit, Bash, and others).

默认就有 Read / Write / Edit / Bash，而且没有沙箱层。

想收紧必须主动配置，三个开关：

• disallowed_tools
• hooks
• permission_mode

hooks 的定位值得单独记：

• 它是「Python 函数，由 Claude Code *应用*（not Claude）调用」
• 拦截发生在确定性代码里，不是靠模型自我约束

对照 Deep Agents：

• 那个的立场是「trust the LLM，不要指望模型自我约束」
• Anthropic 的答案：把拦截放在应用层

The official docs give a complete permission evaluation chain — the most detailed one seen on this site so far.

This README passage is the authoritative statement:

allowed_tools is a permission allowlist: listed tools are auto-approved, and unlisted tools fall through to permission_mode and can_use_tool for a decision. It does not remove tools from Claude's toolset. To block specific tools, use disallowed_tools.

Translated into a table:

⚠ The default starting state must be known:

By default, Claude has access to the full Claude Code toolset (Read, Write, Edit, Bash, and others).

By default it has Read / Write / Edit / Bash, with no sandbox layer.

Tightening requires deliberate configuration, three switches:

• disallowed_tools
• hooks
• permission_mode

The positioning of hooks deserves its own note:

• they are "Python functions invoked by Claude Code *applying* them (not Claude)"
• interception happens in deterministic code, not by relying on the model to self-restrain

Contrast with Deep Agents:

• that one's stance is "trust the LLM, don't expect the model to self-restrain"
• Anthropic's answer: put interception in the application layer

custom tools 以「进程内 MCP server」的形式运行。

官方原话：

"in-process MCP servers that run directly within your Python application"

官方列的收益有五条：

外部 MCP server 照样支持，两者可混用。

mcp_servers 字典里可以同时放：

• create_sdk_mcp_server(...) 的产物
• {"type":"stdio", ...} 外部 server

⚠ 注意能力边界：

• custom tools 与 hooks 只在 ClaudeSDKClient 下可用
• query() 用不了

Custom tools are not plain function calls but "in-process MCP servers."

Official wording:

"in-process MCP servers that run directly within your Python application"

The official list of benefits has five items:

External MCP servers are still supported; the two can be mixed.

The mcp_servers dict can hold at the same time:

• the output of create_sdk_mcp_server(...)
• {"type":"stdio", ...} external servers

⚠ Note the capability boundary:

• custom tools and hooks are only available under ClaudeSDKClient
• query() cannot use them

system prompt 有「快照」语义。

会话中途改 prompt 不会立刻生效。

README 原文：

Claude Code builds the system prompt on a session's first request, records it, and reuses it on every later request, including after you resume the session. A changed custom prompt, or changed append text... then has no effect until the session is compacted or you start a new session. To rebuild the prompt on every request instead... set snapshot to False.

想每次重建，要显式设 snapshot: False。

这需要 CLI 2.1.257+。

README 还记了一个历史 bug：

"Before 2.1.265, a session with an append or custom prompt recorded it only when snapshot was True"

这实质是「上下文快照不可变」：保证了 prompt 的确定性，代价是修改有延迟。

与本站主张的关系：

• 其他 harness 讲的是「如何压缩/持久化上下文」
• 这里讲的是「如何冻结上下文」

它保证同一会话内 prompt 恒定，避免 prompt 漂移导致行为不可预测。

这是一个第三种思路，本站首次记录（标注为本站观察，非官方表述）。

The system prompt has "snapshot" semantics.

Changing the prompt mid-session does not take effect immediately.

README wording:

Claude Code builds the system prompt on a session's first request, records it, and reuses it on every later request, including after you resume the session. A changed custom prompt, or changed append text... then has no effect until the session is compacted or you start a new session. To rebuild the prompt on every request instead... set snapshot to False.

To rebuild every time, explicitly set snapshot: False.

This needs CLI 2.1.257+.

The README also records a historical bug:

"Before 2.1.265, a session with an append or custom prompt recorded it only when snapshot was True"

This is essentially an "immutable context snapshot": it guarantees prompt determinism; the cost is delayed changes.

Relationship to this site's stance:

• other harnesses discuss "how to compact/persist context"
• this one discusses "how to freeze context"

It keeps the prompt constant within one session, avoiding unpredictable behavior from prompt drift.

This is a third approach, recorded here for the first time on this site (marked as this site's observation, not official wording).

结论：仓库是 MIT，用起来却还受 Anthropic 商业条款约束。

README 末节原文：

Use of this SDK is governed by Anthropic's Commercial Terms of Service, including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license.

仓库许可证标记是 MIT。

license API 确认 spdx_id: MIT。

但使用受 Anthropic 商业条款约束。

尤其「用它给你自己的客户提供产品/服务」这一条。

⚠ 本站标注：这不是「非开源」，也不是「不能商用」。

但做产品前必须读那份商业条款，MIT 标记本身不构成完整授权判断。

附一处核验发现：

• TypeScript 版仓库：anthropics/claude-agent-sdk-typescript
• 1,780★，活跃
• 没有 LICENSE 文件，license API 返回 null

授权状态与 Python 版是否一致未核实。

Python 版是 MIT + 商业条款；TS 版无文件可查。

选型时若要用 TS 版，授权需另行确认。

Conclusion: the repository is MIT, but usage is still governed by Anthropic's Commercial Terms.

README final-section wording:

Use of this SDK is governed by Anthropic's Commercial Terms of Service, including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license.

The repository license marker is MIT.

the license API confirms spdx_id: MIT.

But usage is governed by Anthropic's Commercial Terms.

Especially the clause about "using it to power products/services for your own customers".

⚠ This site's note: this is not "not open source", nor "cannot be used commercially".

But you must read those commercial terms before building a product; the MIT marker alone is not a complete authorization judgment.

One verification finding attached:

• the TypeScript repository: anthropics/claude-agent-sdk-typescript
• 1,780★, active
• no LICENSE file, the license API returns null

Whether its authorization status matches the Python version is not verified.

The Python version is MIT + commercial terms; the TS version has no file to check.

If selecting the TS version, authorization needs separate confirmation.

两条元数据是空的，如实记下来。

核验：description 为 null（GitHub API），homepage 也为 null。 文档入口在 README 首行的 platform.claude.com/docs/en/agent-sdk/python。

这样记，是为了避免读者以为信息缺失是我们没查。

Two metadata fields are empty; recorded as-is.

verified: description is null (GitHub API), and homepage is also null. The docs entry is in the README's first line: platform.claude.com/docs/en/agent-sdk/python.

Recording it this way prevents readers from assuming the missing information is because we did not check.

confidence: partial 的依据如下。

降级时间：2026-10-03，由 verified 降为 partial。

为什么降级：下方 ❌ 项的主语是本站的取证缺口，不是「官方未提供」。 按 v3 铁律「未知就说未知」，这些条目存在时标 verified 属于虚高，故降为 partial。

主要缺口有三处：

• Anthropic 商业条款的具体条款内容
• TS 版许可状态
• hooks 生命周期边界

已核验：

• ✅ 仓库存在与星数（8,334 · 滚动核验 2026-10-23）
• ✅ 许可（license API 返回 MIT）
• ✅ 最近推送（2026-10-22，仍活跃）
• ✅ 最新版本 0.2.173（2026-10-22 发布）
• ✅ 捆绑 CLI 版本 2.1.286（_cli_version.py 原文）
• ✅ README 全文 —— 权限求值链、hooks 定位、错误类型清单、default full toolset 表述
• ✅ README 全文 —— custom tools 为进程内 MCP server、system prompt snapshot 语义
• ✅ 许可条款末节原文
• ✅ v3 计划记录的 0.2.162 已被超越（2026-10-23 滚动核验时最新为 0.2.173）

⚠ 异常发现：

• 仓库 description 与 homepage 均为 null
• TS 版无 LICENSE 文件，license API 返回 null

❌ 未核验：

• Anthropic 商业条款的具体条款内容（未读原文，属法务范畴）
• 会话的多进程并发语义
• session forking 的具体形态与限制
• can_use_tool 与 permission_mode 的完整优先级链（README 只给了概述，细节在 permissions 专章）

一处计划数据修正：

v3 计划 §2.2 记的是 v0.2.162。

实际核验时已发布 v0.2.163，晚于计划编写。

这再次印证「快照会过期、必须现场核验」。

Basis for confidence: partial.

Downgrade time: 2026-10-03, downgraded from verified to partial.

Why downgraded: the subject of the ❌ items below is this site's evidence gap, not "not provided officially". Per the v3 rule "say unknown when unknown", marking verified while these items exist would be inflated, hence partial.

Three main gaps:

• the specific clauses of Anthropic's Commercial Terms
• the TS version's license status
• hooks' lifecycle boundaries

Verified:

• ✅ repository exists and star count (8,334 · rolling check 2026-10-23)
• ✅ license (license API returns MIT)
• ✅ last push (2026-10-22, still active)
• ✅ latest version 0.2.173 (released 2026-10-22)
• ✅ bundled CLI version 2.1.286 (_cli_version.py verbatim)
• ✅ full README — permission evaluation chain, hooks positioning, error-type list, default full toolset wording
• ✅ full README — custom tools as in-process MCP servers, system-prompt snapshot semantics
• ✅ the licensing final-section verbatim
• ✅ the 0.2.162 recorded in the v3 plan has been overtaken (latest 0.2.173 at the 2026-10-23 rolling check)

⚠ Anomaly findings:

• repository description and homepage are both null
• the TS version has no LICENSE file; the license API returns null

❌ Not verified:

• the specific clauses of Anthropic's Commercial Terms (original text not read; legal territory)
• multi-process concurrency semantics of sessions
• the exact shape and limits of session forking
• the full precedence chain of can_use_tool and permission_mode (the README gives an overview only; details are in the permissions chapter)

One plan-data correction:

v3 plan §2.2 recorded v0.2.162.

At verification time v0.2.163 had been released, later than the plan was written.

This again confirms "snapshots go stale; verification must happen live."