← Harness 图谱

「Claude Code 的编程接口」 —— 不是自建 agent 框架，是把一个成熟的 coding CLI 变成 Python 可驱动的对象。

模型与开放条件

只支持 Claude。 README 全文没有 provider-agnostic 的表述， pyproject.toml 层面也没有 litellm / any-llm 之类的可选依赖。 ⚠ 这是它与其他九个对象最本质的差别：本站其他 harness 都能接自托管模型（Ollama / vLLM / llama.cpp）， 本 SDK 不能。模型层（models.specul.com）推荐的本地量化路线在这里走不通。

运行位置

它是「你运营 Python 进程 + 它驱动一个 CLI 子进程」的双层结构。 README 明说CLI 随 wheel 捆绑（核验：_cli_version.py 里 __cli_version__ = "2.1.286"）， 默认用捆绑版；也可指向系统安装（ClaudeAgentOptions(cli_path="/path/to/claude")）。 实际形态：pip 包 → 内含 Claude Code CLI → CLI 连 Anthropic API。 换句话说这不是「库」，是「带 CLI 的库」。

本地文件

默认就是全套文件工具，且是全权限起步。 README 原文： 「By default, Claude has access to the full Claude Code toolset (Read, Write, Edit, Bash, and others)」。 工作目录用 ClaudeAgentOptions(cwd="/path/to/project") 指定。 这是与本站其他对象最大的风险差异 —— 默认就能读文件、改文件、跑 Bash。

关机后的任务

进程关了就停，但会话可续。 错误类型里 CLIConnectionError / CLINotFoundError / ProcessError / ResultError 揭示了进程依赖结构。 会话持久化有官方支撑：README 提到「records it, and reuses it on every later request, including after you resume the session」，以及 CHANGELOG 的 「session forking features」—— 即 resume + fork 是一等能力。 具体存储位置本次未核验。

工具与扩展

两个入口，能力不同（这是很关键的设计细节）： query() 是单向提问，只能用 CLI 自带工具集； ClaudeSDKClient 是双向会话，额外解锁 custom tools 与 hooks。 custom tools 是「进程内 MCP server」：README 说它们是 「in-process MCP servers that run directly within your Python application」， 官方列的收益是 no subprocess management / no IPC overhead / 单进程部署 / 更好调试 / 类型安全。 外部 MCP server 也支持，且两者可混用（mcp_servers 可同时放 SDK server 与 stdio 外部 server）。

上下文与记忆

有一个本站很关注、但容易被忽略的机制：system prompt 的 snapshot 语义。 README 原文：Claude Code 会在会话首次请求时构建并记录 system prompt， 之后每次请求（含恢复会话后）都复用它； 改了自定义 prompt 或 claude_code preset 的 append 文本， 要等到会话被compact 或开了新会话才生效—— 除非把 snapshot 设为 False（需要 CLI 2.1.257+）。 这实质上是「上下文快照不可变」的设计，与本站「状态 ≠ 上下文」的讨论直接相关： 它保证了 prompt 的确定性，代价是改动生效有延迟。

权限与限制

官方给了完整的权限求值链，这是本站目前见到的最详细的一份。 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.」 翻译：allowed_tools 是准入白名单（列进去=自动批准）， 未列的走 permission_mode 与 can_use_tool 判定； 它不会把工具从工具集里移除 —— 要真正禁用得用 disallowed_tools。 hooks 提供确定性拦截：README 说 hooks 是「Python 函数，由 Claude Code *应用*（不是 Claude）调用」， 可在 PreToolUse 返回 permissionDecision: "deny" + 理由，示例就是拦 Bash 命令。 ⚠ 默认起步是全工具 + 无沙箱，想收紧必须主动配置。

适合什么任务

适合：想要一个已经被打磨过的 coding agent（工具集、权限链、hooks、session fork 都在） 并且团队用 Python；愿意把推理完全交给 Claude。 不适合：需要换模型 / 接自托管权重（直接排除）； 需要框架级的自定义 agent loop（它是 CLI 的接口，loop 形状由 Claude Code 决定）； 需要多agent 编排（它没有 agents-as-tools 那种一等委派机制）。

本页由 ai-coding-agent-atlas 数据层生成（CC BY 4.0）。 方法论与坐标系定义见仓库内 METHODOLOGY.md。