入口点与 SDK

01 入口点层

The src/entrypoints/ 目录是外部世界和 Claude Code 内部之间的边界。 它包含五个表面级文件 - cli.tsx, init.ts, mcp.ts, agentSdkTypes.ts， 和 sandboxTypes.ts — 加上一个 sdk/ 保存可序列化合约类型的子目录。 main.tsx 位于上一层，是一个基于 Commander 的大型 CLI 处理程序，几乎每个交互式和无头路径都流经该处理程序。

02 cli.tsx — Bootstrap 调度程序

src/entrypoints/cli.tsx 是实际的二进制入口点。 它在任何其他模块评估之前运行。 其设计理念： 为每个快速路径加载尽可能少的负载.

快速路径（按检测顺序）

// From cli.tsx — each fast-path is gated by a build-time feature() flag
if (feature('BRIDGE_MODE') && (args[0] === 'remote-control' || args[0] === 'rc'
    || args[0] === 'remote' || args[0] === 'sync' || args[0] === 'bridge')) {
  // Auth check → GrowthBook gate → policy limits → bridgeMain()
  const { bridgeMain } = await import('../bridge/bridgeMain.js');
  await bridgeMain(args.slice(1));
  return;
}

03 init.ts — 共享初始化

src/entrypoints/init.ts 是一个已记忆的 init() 由所有重要入口点共享的函数。 这是 不要求快速路径。 它执行第一次 API 调用之前必须发生的所有一次性设置。

一个单独的 initializeTelemetryAfterTrust() 仅在用户接受信任对话框后才调用该函数。 这将独立于同意的设置与同意门控遥测分开，并在初始化 OpenTelemetry 导出器之前等待远程托管设置加载。

04 mcp.ts — Claude Code 作为 MCP 服务器

当调用时 claude --mcp, Claude Code 作为标准运行 模型上下文协议服务器 通过工作室。 这会将 Claude Code 的所有工具（Bash、Edit、Read、WebFetch 等）公开给 other MCP 客户端 — 编辑器、代理或自动化脚本可以直接调用它们，而无需生成完整的 REPL。

// src/entrypoints/mcp.ts
const server = new Server(
  { name: 'claude/tengu', version: MACRO.VERSION },
  { capabilities: { tools: {} } }
)

// ListTools: enumerate every Claude Code tool with its Zod-derived JSON schema
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: await Promise.all(tools.map(async tool => ({
    ...tool,
    description: await tool.prompt(...),
    inputSchema: zodToJsonSchema(tool.inputSchema),
  })))
}))

// CallTool: validate input, check permissions, execute, return result
server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
  const tool = findToolByName(tools, params.name)
  return await tool.call(params.arguments, toolUseContext, ...)
})

05 agentSdkTypes.ts — 公共 SDK 合约

src/entrypoints/agentSdkTypes.ts 是 Agent SDK 包的主要导出。 它从三个子模块重新导出完整的公共 API，并声明 SDK 消费者调用的顶级函数。 所有函数体都会抛出异常 'not implemented' 在此文件中 - 实际实现由 SDK 传输层在运行时注入。

模块结构

顶级 SDK 函数

// V1 API (stable) — headless one-shot query
export function query(params: {
  prompt: string | AsyncIterable<SDKUserMessage>
  options?: Options
}): Query

// V2 API (@alpha) — persistent multi-turn sessions
export function unstable_v2_createSession(options: SDKSessionOptions): SDKSession
export function unstable_v2_resumeSession(sessionId: string, options: SDKSessionOptions): SDKSession
export async function unstable_v2_prompt(message: string, options: SDKSessionOptions): Promise<SDKResultMessage>

// Session management
export async function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>
export async function getSessionInfo(sessionId: string): Promise<SDKSessionInfo | undefined>
export async function getSessionMessages(sessionId: string): Promise<SessionMessage[]>
export async function renameSession(sessionId: string, title: string): Promise<void>
export async function tagSession(sessionId: string, tag: string | null): Promise<void>
export async function forkSession(sessionId: string, options?: ForkSessionOptions): Promise<ForkSessionResult>

// In-process MCP server
export function createSdkMcpServer(options: { name: string; tools: SdkMcpToolDefinition[] }): McpSdkServerConfigWithInstance
export function tool<S>(name, description, schema, handler): SdkMcpToolDefinition<S>

06 控制协议（SDK 构建器）

外部 SDK 实现（如 Python claude-code-sdk) 通过基于 JSON 的方式与 Claude Code 进程进行通信 控制协议 分层在 stdio 上。 模式定义在 sdk/controlSchemas.ts.

控制请求子类型

// Initialize request — sent by SDK to start a session
{
  subtype: "initialize",
  hooks: {
    "PreToolUse": [{ hookCallbackIds: ["my-hook"], matcher: "Bash" }]
  },
  sdkMcpServers: ["my-server"],
  systemPrompt: "You are a coding assistant.",
  agents: {
    "reviewer": { description: "Reviews code changes", ... }
  }
}

// Initialize response — returned by CLI
{
  commands: [...],    // available slash commands
  agents: [...],      // available agent types
  models: [...],      // available models
  account: {...},     // account info
  pid: 12345          // @internal CLI PID for tmux socket isolation
}

07 挂钩事件 — SDK 观察者模式

SDK 公开了丰富的钩子系统，使外部主机可以观察和拦截 Claude Code 的生命​​周期。 有 26 个命名的钩子事件，定义在 sdk/coreTypes.ts:

export const HOOK_EVENTS = [
  // Tool execution
  'PreToolUse', 'PostToolUse', 'PostToolUseFailure',
  // Permission flow
  'PermissionRequest', 'PermissionDenied',
  // Session lifecycle
  'SessionStart', 'SessionEnd', 'Setup',
  // Turn lifecycle
  'Stop', 'StopFailure',
  // Context management
  'PreCompact', 'PostCompact',
  // Agent/swarm lifecycle
  'SubagentStart', 'SubagentStop', 'TeammateIdle',
  'TaskCreated', 'TaskCompleted',
  // Notifications and user input
  'Notification', 'UserPromptSubmit',
  // Config changes
  'ConfigChange', 'InstructionsLoaded', 'CwdChanged', 'FileChanged',
  // Elicitation
  'Elicitation', 'ElicitationResult',
  // Worktree
  'WorktreeCreate', 'WorktreeRemove',
] as const

每个钩子都会发射 BaseHookInput 其中包括 session_id, transcript_path, cwd, agent_id （如果在子代理内部），以及 agent_type。 每个事件都会在顶部添加自己的特定字段。

08 守护进程和桥接模式 (@internal)

对于高级主机架构（桌面应用程序、CI 系统、claude.ai 集成）， agentSdkTypes.ts 还出口 @internal primitives:

计划任务/Cron

// Watch .claude/scheduled_tasks.json and yield fire/missed events
export function watchScheduledTasks(opts: {
  dir: string
  signal: AbortSignal
  getJitterConfig?: () => CronJitterConfig
}): ScheduledTasksHandle

// ScheduledTasksHandle — drain with for await
{
  events(): AsyncGenerator<ScheduledTaskEvent>  // fire | missed
  getNextFireTime(): number | null               // epoch ms of next scheduled run
}

这使得守护进程拥有父进程中的调度程序。 当任务触发时，守护进程会生成一个 query() 子进程——如果它崩溃了，守护进程可以在计划继续进行的同时重新生成它。

远程控制/桥接器

// Connect the local machine as a claude.ai remote-control environment
export async function connectRemoteControl(opts: ConnectRemoteControlOptions):
  Promise<RemoteControlHandle | null>

// RemoteControlHandle — two-way bridge over WebSocket
{
  sessionUrl: string
  environmentId: string
  bridgeSessionId: string
  write(msg: SDKMessage): void         // pipe query() yields in
  sendResult(): void                     // signal turn complete
  inboundPrompts(): AsyncGenerator<...>  // read user messages from claude.ai
  controlRequests(): AsyncGenerator<...> // interrupt, set_model, etc.
  permissionResponses(): AsyncGenerator<...>
  onStateChange(cb): void               // ready | connected | reconnecting | failed
  teardown(): Promise<void>
}

09 sandboxTypes.ts — 进程隔离配置

src/entrypoints/sandboxTypes.ts 是沙箱配置类型的单一事实来源。 SDK 和设置验证系统都从此处导入。 它是通过导出的 agentSdkTypes.ts 因此 SDK 消费者可以配置沙箱。

// SandboxSettings — full configuration for process-level isolation
{
  enabled: boolean
  failIfUnavailable: boolean    // hard-gate for managed deployments
  autoAllowBashIfSandboxed: boolean
  allowUnsandboxedCommands: boolean
  network: {
    allowedDomains: string[]
    allowManagedDomainsOnly: boolean  // enterprise: only managed domains
    allowUnixSockets: string[]        // macOS only
    allowLocalBinding: boolean
    httpProxyPort: number
    socksProxyPort: number
  }
  filesystem: {
    allowWrite: string[]      // merged with Edit() allow rules
    denyWrite: string[]       // merged with Edit() deny rules
    denyRead: string[]
    allowRead: string[]       // re-allow within denyRead regions
    allowManagedReadPathsOnly: boolean
  }
}

10 main.tsx — 调用模式

Once cli.tsx 落入 main.tsx，基于 Commander 的 CLI 处理其余的调用模式。 关键：

11 完整的调用流程