# Commit Log：sdk-contract-alignment-loop

> 规则：每次该循环产生新提交，必须在本文件追加一条记录。

## 2026-03-04

- `1e8f7f3` `test(core,plans): harden model metadata prefix priority`
  - 切片：`MOD-07`
  - 说明：将 metadata 前缀匹配改为按长度降序，避免 `gpt-4*` 抢占 `gpt-4o* / gpt-4-turbo*`；补充 `gpt-4-turbo-*` 回归断言防止能力字段误回退。

- `72ba9cd` `refactor(core,plans): derive openai defaults from shared metadata`
  - 切片：`MOD-06`
  - 说明：将 OpenAI 默认模型列表与 fetch fallback 统一改为复用 `inferModelMetadata` 构建，消除 `getDefaultModels` 与 metadata 表重复定义，并补齐对齐回归测试。

- `830c33d` `feat(sdk,core,plans): infer active model capability compatibility fields`
  - 切片：`MOD-05`
  - 说明：扩展核心 `inferModelMetadata` 输出 `supports_vision/supports_function_calling`，并复用到 `sdk/query.supportedModels()` 活动模型回填项；同步补齐 core/sdk 测试与 SDK 对齐文档说明。

- `502c8eb` `feat(sdk,core,plans): fill inferred active model metadata fields`
  - 切片：`MOD-04`
  - 说明：在核心模型推导层新增 `inferModelMetadata` 并复用到 `sdk/query.supportedModels()`，对活动模型回填项在可推导时补齐 `max_tokens/contextWindowTokens`；同步补充 core/sdk 测试与对齐文档。

- `a9d4a5e` `refactor(sdk,core,plans): centralize model effort inference helper`
  - 切片：`MOD-03`
  - 说明：将 OpenAI 模型 effort 推导规则上移到 `core/models` 单一来源（新增 `inferModelReasoningEffortSupport`），`fetchOpenAIModels` 与 `sdk/query` 共用该规则，减少能力字段漂移并补齐核心单测。

- `88d1a07` `feat(sdk,runtime,subagents,plans): expose agent model in supportedAgents`
  - 切片：`AGT-01`
  - 说明：贯通 `subagents registry -> runtime -> sdk query.supportedAgents()` 的可选 `model` 字段透传；当底层代理配置含模型信息时返回 `model`，同时补齐 registry/runtime/sdk 回归测试与对齐文档。

- `7241a30` `feat(sdk,plans): infer effort fields for active model fallback`
  - 切片：`MOD-02`
  - 说明：`supportedModels()` 对活动模型回填项新增高置信度 effort 能力推导（目前覆盖 OpenAI 已知前缀），在可推导时补齐 `supportsEffort/supportsAdaptiveThinking/supports_reasoning_effort`，并补齐 true/false 回归测试与对齐文档。

- `d435cd5` `feat(sdk,plans): add supportedModels adaptive-thinking compatibility`
  - 切片：`MOD-01`
  - 说明：`supportedModels()` 在可推导能力时新增官方兼容字段 `supportsAdaptiveThinking`，并补齐测试与对齐文档；同时更新滚动计划 TODO 到下一切片 `MOD-02`。

- `0fce229` `feat(sdk): align accountInfo apiKeySource semantics`
  - 切片：`SDK-15`、`TYP-01`
  - 说明：将 `accountInfo.apiKeySource` 收紧到官方兼容语义（`env -> temporary`、`config -> user`），保留 `tokenSource` 作为 Formax 来源细节；新增 `ApiKeySource` 类型并将 `AccountInfo.apiKeySource` 与其建立兼容关联，补齐类型/校验/测试与导出文档。

- `765a479` `feat(sdk): expand accountInfo compatibility fields`
  - 切片：`SDK-14`
  - 说明：`query.accountInfo()` 在保留既有 `provider/model/baseUrl/hasApiKey` 字段的基础上，补齐官方常用兼容字段子集（`tokenSource/apiKeySource`）并扩展类型与输出校验，附带回归测试与对齐文档更新。

- `4d6657c` `feat(sdk): refine canUseTool updatedPermissions mapping`
  - 切片：`QRY-69`
  - 说明：收紧 `updatedPermissions -> approval answers` 映射：仅对当前可表达更新类型触发 `approve_remember`，并按 destination 映射 scope；遇到不可表达更新或 mixed-destination 时降级为一次性 `approve`，避免 scope 放大。

- `0765a28` `feat(sdk,tools): apply safe updatedInput flow for canUseTool`
  - 切片：`QRY-68`
  - 说明：`canUseTool.updatedInput` 在 `approval_request` 下可受控回写执行入参；SDK 侧新增 `updated_input_json` 映射，执行侧补齐策略重校验（policy deny / permission deny / bash deny + fs 路径变更约束），并修复审计日志动作与最终执行动作一致性。

- `37da31b` `feat(sdk,tools,streaming): support canUseTool input handling`
  - 切片：`QRY-65`、`QRY-66`、`QRY-67`
  - 说明：`query` 正式支持 `options.canUseTool`（统一处理 `approval_request` 与 `ask_user_question`），并移除 SDK 对外 `onInputRequest`；补齐 `PermissionResult/PermissionUpdate/CanUseTool` 类型与返回校验；扩展 `approval_request` 事件上下文（`blockedPath`/`decisionReason`）并补测试、文档与对齐矩阵。

- `6cbcabf` `feat(sdk): return structured rewindFiles fallback`
  - 切片：`QRY-64`
  - 说明：`query.rewindFiles()` 从抛错改为返回结构化不支持结果（`canRewind=false` + `error`），以稳定方法契约并保持当前能力边界。

- `29c5e3c` `feat(sdk): support query stopTask compatibility`
  - 切片：`QRY-63`
  - 说明：`query.stopTask()` 从显式不支持改为中止式兼容语义（复用 query abort 路径），并更新测试与文档标注。

- `d3975eb` `feat(sdk): relax query permissionMode compatibility`
  - 切片：`QRY-62`
  - 说明：`query` 对 `permissionMode=dontAsk/bypassPermissions` 从显式报错调整为兼容 no-op 接受；`default/acceptEdits/plan` 映射语义保持不变。

- `2c05b4e` `feat(sdk): accept query maxTurns compatibility`
  - 切片：`QRY-61`
  - 说明：`query` 接收 `maxTurns` 并在 in-process SDK 模式下按兼容 no-op 处理（包含 `>1` 输入），不再直接报“不支持”。

- `3f3b235` `feat(sdk): support query onElicitation fallback`
  - 切片：`QRY-60`
  - 说明：`query` 支持 `onElicitation` 作为 `ask_user_question` 的 fallback 回调（`onInputRequest` 优先），并补齐请求/结果校验与回归测试。

- `b1f424c` `feat(sdk): accept query resumeSessionAt compatibility`
  - 切片：`QRY-59`
  - 说明：`query` 接收 `resumeSessionAt` 并在 in-process SDK 模式下按兼容 no-op 处理；`resume/sessionId/continue` 既有恢复语义保持不变。

- `41960c3` `feat(sdk): accept query budget compatibility`
  - 切片：`QRY-58`
  - 说明：`query` 接收 `maxBudgetUsd` 并在 in-process SDK 模式下按兼容 no-op 处理，不再直接报“不支持”。

- `0bbb0ca` `feat(sdk): accept query effort compatibility`
  - 切片：`QRY-57`
  - 说明：`query` 接收 `effort` 并在 in-process SDK 模式下按兼容 no-op 处理，不再直接报“不支持”。

- `e2f4c9a` `feat(sdk): accept query extension compatibility options`
  - 切片：`QRY-56`
  - 说明：`query` 接收 `plugins/settingSources` 并在 in-process SDK 模式下按兼容 no-op 处理；`onElicitation` 继续显式不支持。

- `9795590` `feat(sdk): accept query agent compatibility options`
  - 切片：`QRY-55`
  - 说明：`query` 接收 `agent/agents` 并在 in-process SDK 模式下按兼容 no-op 处理，不再直接报“不支持”。

- `9b55914` `feat(sdk): accept query additionalDirectories compatibility`
  - 切片：`QRY-54`
  - 说明：`query` 接收 `additionalDirectories` 并在 in-process SDK 模式下按兼容 no-op 处理；`sandbox` 继续显式不支持。

- `4dc3053` `feat(sdk): accept query fallbackModel compatibility`
  - 切片：`QRY-53`
  - 说明：`query` 接收 `fallbackModel`，在 in-process SDK 模式下按兼容 no-op 处理，不再直接报“不支持”。

- `9e4e8f8` `feat(sdk): relax query permission-prompt compatibility`
  - 切片：`QRY-52`
  - 说明：`permissionPromptToolName/promptSuggestions` 在 in-process SDK 模式下改为兼容 no-op；`allowDangerouslySkipPermissions=true` 继续显式不支持（保持权限安全语义）。

- `f5ab7cb` `feat(sdk): accept query process-spawn compatibility options`
  - 切片：`QRY-51`
  - 说明：`query` 接收 `pathToClaudeCodeExecutable/spawnClaudeCodeProcess`，在 in-process SDK 模式下按兼容 no-op 处理，不再直接报“不支持”。

- `c9b28b6` `feat(sdk): accept query cli-exec compatibility options`
  - 切片：`QRY-50`
  - 说明：`query` 接收 `executable/executableArgs/extraArgs/betas`，在 in-process SDK 模式下按兼容 no-op 处理，不再直接报“不支持”。

- `bc5f0d6` `feat(sdk): align query continue and sessionId`
  - 切片：`QRY-49`
  - 说明：`continue+sessionId` 对齐增强：当 `sessionId` 与最新会话一致时允许继续，不匹配时保留显式冲突错误（除非 `forkSession=true`）。

- `45ba95a` `feat(sdk): support query debugFile option`
  - 切片：`QRY-48`
  - 说明：`query` 正式支持 `options.debugFile`（作为非阻塞调试日志文件输出）；与 `debug/stderr` 一起可形成本地调试观测路径。

- `72a52fc` `feat(sdk): support query debug option`
  - 切片：`QRY-47`
  - 说明：`query` 正式支持 `options.debug=true`（通过 `FORMAX_HOOKS_DEBUG=1` 接入现有 hook debug 路径）；`debugFile` 仍显式报“暂不支持”。

- `943f873` `feat(sdk): support query stderr callback`
  - 切片：`QRY-46`
  - 说明：`query` 正式支持 `options.stderr`（作为可选错误输出回调）；不再因传入 `stderr` 参数而直接报“不支持”。

- `0da1b3c` `feat(sdk): support query enableFileCheckpointing`
  - 切片：`QRY-45`
  - 说明：`query` 正式支持 `options.enableFileCheckpointing=true`（复用现有会话持久化路径并写入历史快照），不再作为“不支持”参数报错。

- `71cc050` `feat(sdk): support query forkSession option`
  - 切片：`QRY-44`
  - 说明：`query` 正式支持 `options.forkSession=true`（将 `resume/continue` 历史重绑定到新 session，并在持久化时写入新文件）；`enableFileCheckpointing` 仍显式报“暂不支持”。

- `6b1597a` `feat(sdk): support query persistSession option`
  - 切片：`QRY-43`
  - 说明：`query` 正式支持 `options.persistSession=true`（新会话写入或在 `resume/continue` 文件上追加）；`forkSession/enableFileCheckpointing` 仍显式报“暂不支持”。

- `35bffaa` `feat(sdk): support query tools option`
  - 切片：`QRY-42`
  - 说明：`query` 正式支持 `options.tools`（数组子集过滤 + `preset` 默认集）；`mcpServers` 仍显式报“暂不支持”。

- `1cb305c` `feat(sdk): support query continue option`
  - 切片：`QRY-41`
  - 说明：`query` 正式支持 `options.continue`（恢复当前 cwd 最近本地会话历史；无历史则按新会话继续）；`fallbackModel` 仍显式报“暂不支持”。

- `13dc31f` `feat(sdk): support query resume and sessionId`
  - 切片：`QRY-40`
  - 说明：`query` 正式支持 `options.resume/options.sessionId`（基于本地持久化会话恢复历史）；`resumeSessionAt` 仍显式报“暂不支持”。

## 2026-03-03

- `110149e` `feat(sdk): align query permission and abort inputs`
  - 切片：`QRY-01`、`QRY-02`
  - 说明：新增 `permissionMode` 与 `abortController` 对齐入口，补类型/校验/测试/文档。

- `e247e3a` `refactor(sdk): extract query input request handlers`
  - 切片：`QRY-03`
  - 说明：将 approval/ask_user_question 处理分支从 `query/runner` 抽离为独立模块，保持行为不变。

- `0c96a72` `docs(sdk): add query contract alignment matrix`
  - 切片：`QRY-04`
  - 说明：新增 query 对齐矩阵文档，并在 SDK README 建立引用。

- `4d6d9e4` `feat(sdk): align systemPrompt preset option`
  - 切片：`QRY-05`
  - 说明：支持 `systemPrompt` 官方 preset 形态子集（`claude_code` + `append`），并补充校验与测试。

- `46af01d` `feat(sdk): align thinking config option`
  - 切片：`QRY-06`
  - 说明：支持 `thinking` 子集对齐（`adaptive/enabled/disabled`）并映射现有执行开关。

- `7ce0ef4` `test(sdk): add query option alignment regression suite`
  - 切片：`QRY-07`
  - 说明：新增 query 选项对齐回归测试组，覆盖 `permissionMode`、`abortController`、`systemPrompt preset`、`thinking`。

- `7012aa5` `feat(sdk): align async iterable prompt input`
  - 切片：`QRY-08`、`QRY-09`
  - 说明：支持 `query` 的 `prompt: AsyncIterable<SDKUserMessage>` 子集输入，并补齐空流/非法结构/中断清理等边界测试。

- `86e7553` `feat(sdk): align full permissionMode input set`
  - 切片：`QRY-10`
  - 说明：对齐官方 `permissionMode` 输入全集，并为当前未支持值提供显式一致错误。

- `9483220` `feat(sdk): align maxThinkingTokens option`
  - 切片：`QRY-11`
  - 说明：增加 `maxThinkingTokens` 输入对齐，并与 `thinking`/`thinkingEnabled` 做一致性约束。

- `3c5118c` `feat(sdk): align maxTurns option`
  - 切片：`QRY-12`
  - 说明：增加 `maxTurns` 对齐入口，当前仅支持 `1` 并对更大值显式报不支持。

- `bdc2fce` `feat(sdk): align maxBudgetUsd option`
  - 切片：`QRY-13`
  - 说明：增加 `maxBudgetUsd` 对齐入口，输入通过后统一显式报当前不支持。

- `6a2887a` `feat(sdk): align query interrupt handle`
  - 切片：`QRY-14`
  - 说明：将 `query` 返回值升级为带 `interrupt()` 的 Query 对象，并保持 `for await` 兼容。

- `a8c93bc` `feat(sdk): align query close handle`
  - 切片：`QRY-15`
  - 说明：为 `query` 增加 `close()`，复用中断语义实现进程内关闭控制。

- `6555043` `feat(sdk): align query resume option inputs`
  - 切片：`QRY-16`
  - 说明：接收 `resume/sessionId/resumeSessionAt` 输入字段，并统一显式报当前不支持。

- `11c7d79` `feat(sdk): align query debug option inputs`
  - 切片：`QRY-17`
  - 说明：接收 `debug/debugFile` 输入字段，并统一显式报当前不支持。

- `e023b5f` `feat(sdk): align query stderr option input`
  - 切片：`QRY-18`
  - 说明：接收 `stderr` 输入字段，并统一显式报当前不支持。

- `7a2426b` `feat(sdk): align query process spawn option inputs`
  - 切片：`QRY-19`
  - 说明：接收 `pathToClaudeCodeExecutable/spawnClaudeCodeProcess` 输入字段，并统一显式报当前不支持。

- `0a88cad` `feat(sdk): align query cli execution option inputs`
  - 切片：`QRY-20`
  - 说明：接收 `extraArgs/executable/executableArgs/betas` 输入字段，并统一显式报当前不支持。

- `ac94fa3` `feat(sdk): align query permission prompt option inputs`
  - 切片：`QRY-21`
  - 说明：接收 `allowDangerouslySkipPermissions/permissionPromptToolName/promptSuggestions` 输入字段，并统一显式报当前不支持。

- `7180f84` `feat(sdk): align query continuation option inputs`
  - 切片：`QRY-22`
  - 说明：接收 `continue/fallbackModel` 输入字段，并统一显式报当前不支持。

- `46d939d` `feat(sdk): align query strict MCP option input`
  - 切片：`QRY-23`
  - 说明：接收 `strictMcpConfig` 输入字段，并统一显式报当前不支持。

- `3379599` `feat(sdk): align query session persistence option inputs`
  - 切片：`QRY-24`
  - 说明：接收 `persistSession/forkSession/enableFileCheckpointing` 输入字段，并统一显式报当前不支持。

- `c896955` `feat(sdk): align query filesystem sandbox option inputs`
  - 切片：`QRY-25`
  - 说明：接收 `additionalDirectories/sandbox` 输入字段，并统一显式报当前不支持。

- `6633be1` `feat(sdk): align query agent option inputs`
  - 切片：`QRY-26`
  - 说明：接收 `agent/agents` 输入字段，并统一显式报当前不支持。

- `ced59ea` `feat(sdk): align query tools and MCP option inputs`
  - 切片：`QRY-27`
  - 说明：接收 `tools/mcpServers` 输入字段，并统一显式报当前不支持。

- `70ac09f` `feat(sdk): align query hook permission option inputs`
  - 切片：`QRY-28`
  - 说明：接收 `hooks/canUseTool` 输入字段，并统一显式报当前不支持。

- `dc5e9c2` `feat(sdk): align query extension option inputs`
  - 切片：`QRY-29`
  - 说明：接收 `plugins/settingSources/onElicitation` 输入字段，并统一显式报当前不支持。

- `34f3d3d` `feat(sdk): align query pre-start control methods`
  - 切片：`QRY-30`
  - 说明：为 `Query` 增加 `setModel/setPermissionMode/setMaxThinkingTokens` 启动前覆盖能力，并在启动后拒绝修改。

- `44396d3` `feat(sdk): add session query APIs with validated outputs`
  - 切片：`SES-01`
  - 说明：新增 `listSessions/getSessionMessages`、统一入口导出、校验与测试。

- `ca4c333` `feat(sdk): enrich session list metadata safely`
  - 切片：`SES-02`
  - 说明：补齐 `firstPrompt/fileSize` 元数据与容错，并更新测试与文档。

- `4b81f4d` `feat(sdk): align query initializationResult method`
  - 切片：`QRY-31`
  - 说明：为 `Query` 增加 `initializationResult()`（含 pre-start close 中止路径），并补测试与文档。

- `9573b1c` `feat(sdk): align query supportedCommands method`
  - 切片：`QRY-32`
  - 说明：为 `Query` 增加 `supportedCommands()`，返回已支持 slash command 清单并做输出校验。

- `17fba5d` `feat(sdk): align query supportedAgents method`
  - 切片：`QRY-33`
  - 说明：为 `Query` 增加 `supportedAgents()`，返回当前可用子代理清单并做输出校验。

- `7defd30` `feat(sdk): align query supportedModels method`
  - 切片：`QRY-34`
  - 说明：为 `Query` 增加 `supportedModels()`，返回当前 provider 的可用模型子集并做输出校验。

- `47c7f3e` `feat(sdk): align query accountInfo method`
  - 切片：`QRY-35`
  - 说明：为 `Query` 增加 `accountInfo()`，返回当前账号配置子集并做输出校验。

- `f54f859` `feat(sdk): align query mcpServerStatus method`
  - 切片：`QRY-36`
  - 说明：为 `Query` 增加 `mcpServerStatus()`，当前能力下返回显式“不支持”错误语义。

- `7bca16c` `feat(sdk): align query MCP control methods`
  - 切片：`QRY-37`
  - 说明：为 `Query` 增加 `setMcpServers/reconnectMcpServer/toggleMcpServer()`，当前能力下返回显式“不支持”错误语义。

- `18cec9e` `feat(sdk): align query task control methods`
  - 切片：`QRY-38`
  - 说明：为 `Query` 增加 `streamInput()/stopTask()`，当前能力下返回显式“不支持”错误语义。

- `23448c0` `feat(sdk): align query rewindFiles method`
  - 切片：`QRY-39`
  - 说明：为 `Query` 增加 `rewindFiles()`，当前能力下返回显式“不支持”错误语义。

- `b4603c0` `feat(sdk): align HOOK_EVENTS constant export`
  - 切片：`SDK-01`
  - 说明：新增 `HOOK_EVENTS` 常量导出（基于现有 hooks 事件能力），并补测试与文档。

- `abc263c` `feat(sdk): align AbortError export`
  - 切片：`SDK-02`
  - 说明：新增 `AbortError` 导出，并在 query 中断相关路径统一使用该错误类型。

- `8fdc555` `feat(sdk): align EXIT_REASONS constant export`
  - 切片：`SDK-03`
  - 说明：新增 `EXIT_REASONS` 常量导出，并补测试与文档。

- `a3887eb` `feat(sdk): align HookEvent and ExitReason types`
  - 切片：`SDK-04`
  - 说明：新增 `HookEvent/ExitReason` 类型导出，并确保与常量导出保持一致。

- `e6c6372` `docs(sdk): add exports alignment index`
  - 切片：`SDK-05`
  - 说明：新增 SDK 导出对齐索引文档，并在 README 增加入口链接。

- `61b70dc` `feat(sdk): add official-aligned type aliases`
  - 切片：`SDK-06`
  - 说明：新增 `Options` 与 `SDK*Message` 系列官方同名类型别名导出，并补类型回归测试。

- `a943bbf` `feat(sdk): align supportedCommands shape fields`
  - 切片：`SDK-07`
  - 说明：`supportedCommands()` 补齐官方同名 `name/argumentHint` 字段，并保留 `command/argHint` 兼容字段。

- `3506c80` `feat(sdk): align supportedModels shape fields`
  - 切片：`SDK-08`
  - 说明：`supportedModels()` 补齐官方常用 `value/displayName/supportsEffort` 字段，并保留 `model/provider` 兼容字段。

- `0f8c3fd` `feat(sdk): align MCP control return types`
  - 切片：`SDK-09`
  - 说明：补齐 `setMcpServers()/rewindFiles()` 等控制方法的官方同名返回类型（仅类型层对齐）。

- `c8e7c60` `feat(sdk): align options effort input contract`
  - 切片：`SDK-10`
  - 说明：新增 `options.effort` 官方值输入校验，并保持当前显式“暂不支持”语义。

- `e463e4a` `feat(sdk): add prompt request type aliases`
  - 切片：`SDK-11`
  - 说明：新增 `PromptRequest/PromptRequestOption/PromptResponse` 官方同名类型别名（已支持交互子集）。

- `e34210a` `feat(sdk): add output format type aliases`
  - 切片：`SDK-12`
  - 说明：新增 `OutputFormatType/BaseOutputFormat` 官方同名类型别名（当前 `json_schema` 子集）。

- `c49372a` `feat(sdk): add elicitation type aliases`
  - 切片：`SDK-13`
  - 说明：新增 `ElicitationRequest/ElicitationResult/OnElicitation` 官方同名类型别名（类型层对齐）。
