Claude Code CLI 与 Claude Agent SDK
机制、边界，以及要不要自建业务 agent

01同源关系：SDK 就是在跑 CLI

这一节是后面所有结论的地基。理解了进程模型，隔离、权限回调、session 存储的行为都会变得可推导。

02差异清单：只剩一维——宿主进程能不能被回调

线协议层面零差距（SDK 内部用的就是 claude -p --output-format stream-json --input-format stream-json）。剩余差异全在“工具调用能不能回到你的进程里”。

03并发与隔离：危险的不是并发，是共享

一个容器跑多个 SDK 子进程是官方推荐的部署形态之一，不是反模式。“Long-running sessions: Run persistent container instances, often hosting multiple SDK processes per container.”

四种 session 生命周期模式（按空闲模式选，不是按安全性选）

真正会踩的四类干扰

settingSources: [] 关不掉的四项

“Do not rely on default query() options for multi-tenant isolation. Because the inputs above are read regardless of settingSources, an SDK process can pick up host-level configuration and per-directory memory.” code.claude.com/docs/en/agent-sdk/claude-code-features

关键区分

// 跨租户参考写法（注意展开 process.env）
for await (const message of query({
  prompt,
  options: {
    cwd: tenantDir,
    settingSources: [],
    env: {
      ...process.env,
      CLAUDE_CONFIG_DIR: configDir,
      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
    },
  },
})) { /* ... */ }

04canUseTool：工具执行前回调到你的进程

SDK 相对 CLI 唯一的硬增量。理解它的实现机制，也就理解了「进程内」这三个字的准确含义。

调用链：stdio 双向控制协议

类型定义（sdk.d.ts L188-233 / L1953-1965，一字不差）

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;                // 用户关页面/超时就 abort
    suggestions?: PermissionUpdate[];   // 「总是允许」用，原样回传即可
    toolUseID: string;
    title?: string;        // bridge 已渲染：「Claude wants to read foo.txt」
    displayName?: string;  // 「Read file」
    description?: string;
    blockedPath?: string;
    decisionReason?: string;
    agentID?: string;      // 来自 subagent 时标识来源
  }
) => Promise<PermissionResult>;

type PermissionResult =
  | { behavior: 'allow'; updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[]; /* ... */ }
  | { behavior: 'deny'; message: string; interrupt?: boolean; /* ... */ };

权限评估六步序：canUseTool 在最后一步

选型：canUseTool 还是 PreToolUse hook

“For checks that must run on every tool call, use a PreToolUse hook: hooks run before every other step, and a hook deny applies even in bypassPermissions mode.” code.claude.com/docs/en/agent-sdk/permissions

• 审计 / 硬性合规闸门 / 必须 100% 覆盖的黑名单 → hook。唯一不被 allow 规则和 bypass 绕过的位置。
• 面向用户的交互式审批 UI（弹窗、「总是允许」按钮）→ canUseTool。
• 需要改写工具入参 → 只能 canUseTool。
• 两者可叠加，文件系统 hooks 与编程 hooks 并行执行。

05SessionStore：镜像，不是替代 alpha

默认 transcript 写在本机 ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl。多实例部署时，用户第二次请求被打到另一台机器就 resume 不了 —— 这就是它要解决的问题。

接口定义

type SessionKey = {
  projectKey: string;   // 默认由 cwd 推导
  sessionId: string;
  subpath?: string;     // 未设 = 主 transcript；设了 = subagent
};

type SessionStore = {
  // 必需
  append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
  load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
  // 可选
  listSessions?(projectKey: string): Promise<Array<{sessionId: string; mtime: number}>>;
  listSessionSummaries?(projectKey: string): Promise<SessionSummaryEntry[]>;
  delete?(key: SessionKey): Promise<void>;
  listSubkeys?(key: {projectKey: string; sessionId: string}): Promise<string[]>;
};

镜像什么、不镜像什么

06选型：还有必要自建业务 agent 吗

把「agent」这个词拆成两层，问题就自己回答了。

手脚具体装什么，按投入产出排序

什么时候确实不该用这个 harness

07harness 边界之外：必须你自己担的

这不是可选的加固，是 harness 架构决定的必然分工。文档白纸黑字：“put authentication at a gateway in front of the agent container. The agent should not be the component that validates user tokens.”