结构化结果的运行边界

第一次有效 structured_output 调用会结束运行；消费端仍需核对进程退出状态，不能只检查是否收到一个合法 JSON 对象。

重试与同轮其他工具

参数不满足 schema 时，工具返回 Ajv 错误，模型可在下一轮修正。每次重试是完整模型轮次，schema 作为函数参数定义也随每次请求发送，大型 schema 会持续增加输入成本。

模型在同一轮同时调用有副作用的工具和 structured_output 时，预扫描会抑制有副作用的兄弟调用，即使结构验证失败也不执行。

验证成功后直接结束，被抑制调用丢弃；验证失败后，模型会看到合成的 Skipped 工具结果，需要在不包含 structured_output 的另一轮重新提交该操作。不要依赖“最终结果和写文件同轮”来保证文件已写入。

失败状态

模型只输出普通文字而不调用终止工具时退出 1，并在错误中给出轮数及截断预览。达到 maxSessionTurns 退出 53，提示排查未调用工具、工具被 deny、schema 无法满足等原因。

SIGINT 退出 130。成功结果已捕获而 stdout 尚未发出时，约 500ms 收尾等待不轮询中断，仍可能输出结果；所以 stdout 有对象不代表进程成功退出。

json/stream-json 的部分失败会在 stdout 给 result.is_error，但轮数超限 53 和信号 130 可能仅有 stderr。先看退出码，再按实际存在的事件解析。

权限与名称冲突

structured_output 绕过 --core-tools 白名单，但显式 permissions.deny / --exclude-tools 会阻止注册；常见后果是模型回答文本并退出 1，或循环到 53。

--bare 忽略大多数设置来源，包括设置级 deny 与 tools.exclude，因此只写配置无法在 bare 阻止该工具；argv 的 --exclude-tools structured_output 仍生效。

MCP 若暴露同名工具，会改名为 mcp____structured_output，synthetic 工具保留裸名和用户 schema。

恢复会话

--json-schema 是每次启动参数，不属于会话持久属性。--continue/--resume 时需再次传入才能保持契约；可以改 schema，但意味着新的约束。未重传则恢复普通无头会话，不再注册终止工具。

数据去向

schema 本身每轮发给模型提供商，enum、const、default、examples、description 和 $comment 中的字面值都包含在内。约束描述不应被当作秘密存储。

structured_output 参数在 ToolCallEvent 遥测和磁盘会话 JSONL 中用 __redacted 占位，验证失败重试也脱敏；周边事件和工具计时等指标保留。原始 payload 仍输出到 stdout。

PreToolUse、PostToolUse、PostToolUseFailure Hooks 仍接收原始 tool_input，HTTP Hooks 也可能转发。上述记录脱敏不能推出 Hooks 已脱敏，需按 tool_name 过滤或在 Hook 内处理。