@zhushanwen/pi-structured-output 5.0.0-dev.0 → 5.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-structured-output",
-  "version": "5.0.0-dev.0",
+  "version": "5.0.1",
   "description": "Structured output tool for Pi — enforces JSON Schema via tool call mechanism with Ajv validation",
   "type": "module",
   "main": "index.ts",

package/src/ajv-validator.ts

@@ -0,0 +1,27 @@
+/**
+ * Ajv 编译缓存 — 纯逻辑叶节点（零业务依赖）。
+ *
+ * 从 index.ts 拆出：WeakMap 缓存 + getOrCompileValidator 编译入口。
+ * schema 对象引用即缓存 key（WeakMap 不强引用，GC 友好）；
+ * boolean 根 schema 不缓存（见下注释）。
+ */
+
+import Ajv, { type ValidateFunction } from "ajv";
+
+// ── Ajv WeakMap cache ─────────────────────────────────────────
+const ajvCache = new WeakMap<object, ValidateFunction>();
+
+export function getOrCompileValidator(schema: Record<string, unknown> | boolean): ValidateFunction {
+	// boolean 根 schema（true=接受一切，false=拒绝一切）是合法 draft-07，
+	// 但 boolean 不能做 WeakMap key，故不缓存（编译结果恒定，重复编译无副作用）。
+	if (typeof schema === "boolean") {
+		return new Ajv({ strict: false }).compile(schema);
+	}
+	const cached = ajvCache.get(schema);
+	if (cached) return cached;
+
+	const ajv = new Ajv({ strict: false });
+	const validate = ajv.compile(schema);
+	ajvCache.set(schema, validate);
+	return validate;
+}

package/src/execute.ts

@@ -0,0 +1,240 @@
+/**
+ * executeStructuredOutput 编排 + 校验双函数（IF-6 拆分）。
+ *
+ * 两种模式：
+ *   - 权威模式（workflow）：`authoritativeSchema` 存在时，只用它校验 data，LLM 传入的
+ *     `schema` 不参与校验（仅用于错误回显）。这从根上杜绝 LLM 自报 schema 自洽绕过
+ *     （[HISTORICAL] 2026-08-01 事故：ds-flash 重写 add_channels.items 的 schema 后
+ *     自洽通过，4 条 channel 修复静默丢失）。
+ *   - 日常模式（交互式）：无 `authoritativeSchema`，走 validateAgainstSelfReported 防御链。
+ *
+ * 权威模式设防（SO-1 修复）：权威分支不再跳过防御链——keyword-less 权威 schema
+ * （{} / {a:1}）被显式拒绝（ERR-3），boolean true（accept-all，无形状约束）被拦截
+ * （ERR-7），否则 workflow 声明的约束会在 ajv strict:false 下静默失效。
+ *
+ * 日常模式防御顺序（编译前拦截，治静默腐败的根）：
+ *   1. 互换检测 — schema 像数据（无 keyword）且 data 像 schema（有 keyword）→ 抛纠错
+ *   2. keyword-less schema 拒绝 — schema 是对象但无任何识别 keyword（{} / {a:1}）
+ *      → 抛 "no recognized keyword"，否则 ajv strict:false 会编译成"接受一切"
+ *   3. ajv 编译失败 → 抛 "Invalid JSON Schema"（含回显）
+ *   4. 校验失败 → 抛 "Schema validation failed"（含回显）
+ */
+
+import type { ValidateFunction } from "ajv";
+
+import { getOrCompileValidator } from "./ajv-validator.js";
+import {
+	assertJsonSchemaRoot,
+	CORRECT_USAGE_HINT,
+	echo,
+	hasSchemaKeyword,
+	isPlainObject,
+	tryParseJson,
+} from "./schema-guards.js";
+
+/**
+ * 权威模式校验（IF-6）。authSchema 由 workflow 脚本（PI_WORKFLOW_SCHEMA env）注入，
+ * 是唯一校验权威——LLM 传入的 schema 不参与校验，仅用于编排层错误回显。
+ *
+ * 权威模式不再跳过日常防御链（SO-1 修复）：keyword-less 权威 schema 必须先过
+ * schema-guards 检查，否则 ajv strict:false 会静默编译成 accept-all，workflow 的
+ * 形状约束失效且零报错（与 08-01 事故同类的静默腐败路径）。
+ *
+ * @returns 校验通过恒为 true；任何失败形态抛错（带恢复指引 + 回显）。
+ */
+export function validateWithAuthoritative(data: unknown, authSchema: object): boolean {
+	// 类型收窄：签名声明 object（C2 契约），hasSchemaKeyword 需要索引签名。
+	// 编排层已 assertJsonSchemaRoot 保证 plain object；直接调用方传 plain object。
+	if (!isPlainObject(authSchema)) {
+		throw new Error(
+			"Authoritative schema (PI_WORKFLOW_SCHEMA) must be a plain object, got "
+			+ typeof authSchema,
+		);
+	}
+
+	// 1. keyword-less 拒绝（ERR-3）：权威 schema 必须用 JSON Schema 关键字描述形状。
+	// 无 keyword 的对象会被 ajv 编译成"接受一切"，必须显式拦截并给恢复指引。
+	if (!hasSchemaKeyword(authSchema)) {
+		throw new Error(
+			"Authoritative schema (PI_WORKFLOW_SCHEMA) has no recognized keyword. "
+			+ "A workflow schema must describe shape via type/properties/items/... "
+			+ "👉 检查 workflow 脚本的 outputSchema 定义，补全 JSON Schema 关键字。 "
+			+ `Received schema=${echo(authSchema)}, data=${echo(data)}`,
+		);
+	}
+
+	// 2. 编译 + 校验。编译失败抛清晰错误（含权威 schema 回显供 workflow 作者修正）。
+	let validate: ValidateFunction;
+	try {
+		validate = getOrCompileValidator(authSchema);
+	} catch (e) {
+		throw new Error(
+			`Invalid authoritative JSON Schema (from PI_WORKFLOW_SCHEMA): ${(e as Error).message}. `
+			+ `The authoritative schema (PI_WORKFLOW_SCHEMA) is: ${echo(authSchema)}. `
+			+ `Received data=${echo(data)}`,
+		);
+	}
+
+	const valid = validate(data);
+	if (!valid) {
+		const errors = validate.errors
+			?.map((err) => `${err.instancePath} ${err.message}`)
+			.join("; ");
+		throw new Error(
+			`Schema validation failed (authoritative): ${errors}. `
+			+ `The authoritative schema (PI_WORKFLOW_SCHEMA) is: ${echo(authSchema)}. `
+			+ `Received data=${echo(data)}`,
+		);
+	}
+	return true;
+}
+
+/**
+ * 日常模式防御链（原 4 步原样迁移）：LLM 自报 schema 的校验路径。
+ * 编译前拦截两类静默腐败形态：互换（schema 像数据 + data 像 schema）和
+ * keyword-less schema（{} / {a:1} 会被 ajv strict:false 编译成"接受一切"）。
+ *
+ * @returns 校验通过恒为 true；任何失败形态抛错（带 CORRECT_USAGE_HINT + 回显）。
+ */
+export function validateAgainstSelfReported(schema: unknown, data: unknown): boolean {
+	// 1. 互换检测：schema 像数据（对象无 keyword）且 data 像 schema（对象有 keyword）。
+	// 这是最严重的静默腐败路径——若放行，ajv 会把"数据形态的 schema"编译成接受一切，
+	// 真正的 schema（此时在 data 里）被丢弃，校验通过并存入垃圾。
+	if (isPlainObject(schema) && !hasSchemaKeyword(schema) && isPlainObject(data) && hasSchemaKeyword(data)) {
+		throw new Error(
+			"Likely swapped: schema looks like data and data looks like a schema. "
+			+ CORRECT_USAGE_HINT
+			+ `Received schema=${echo(schema)}, data=${echo(data)}`,
+		);
+	}
+
+	// 2. keyword-less schema 拒绝：治静默腐败的根。{} / {a:1} 这类对象会被
+	// ajv strict:false 编译成"接受一切"的 validator，模型把答案塞进 schema 时会静默通过。
+	if (isPlainObject(schema) && !hasSchemaKeyword(schema)) {
+		throw new Error(
+			"Invalid JSON Schema: schema has no recognized keyword "
+			+ "(type/properties/items/enum/...). If you passed the answer value as schema, "
+			+ "you likely swapped schema and data. "
+			+ CORRECT_USAGE_HINT
+			+ `Received schema=${echo(schema)}`,
+		);
+	}
+
+	// 3. ajv 编译。schema 此时可能是 object（过 keyword 检查）、boolean（合法 draft-07 根）、
+	// 或 string/number/array/null（非法 → 显式抛错给清晰提示）。getOrCompileValidator 只接受
+	// object|boolean，消除原先的 `as Record<string,unknown>` 不安全 cast。
+	let validate: ValidateFunction;
+	try {
+		if (isPlainObject(schema) || typeof schema === "boolean") {
+			validate = getOrCompileValidator(schema);
+		} else {
+			throw new Error(`schema must be a JSON Schema object or boolean, got ${typeof schema}`);
+		}
+	} catch (e) {
+		throw new Error(
+			`Invalid JSON Schema: ${(e as Error).message}. `
+			+ `Received schema=${echo(schema)}, data=${echo(data)}`,
+		);
+	}
+
+	// 4. 校验
+	const valid = validate(data);
+	if (!valid) {
+		const errors = validate.errors
+			?.map((err) => `${err.instancePath} ${err.message}`)
+			.join("; ");
+		throw new Error(
+			`Schema validation failed: ${errors}. `
+			+ `Received schema=${echo(schema)}, data=${echo(data)}`,
+		);
+	}
+	return true;
+}
+
+/**
+ * 执行 schema 校验。从 createToolDefinition.execute 抽出以便单元测试直接调用。
+ *
+ * 编排：tryParseJson 归一 → 权威分支（assertJsonSchemaRoot 收窄 + boolean 拦截 +
+ * validateWithAuthoritative）→ 日常分支 validateAgainstSelfReported。
+ */
+export async function executeStructuredOutput(params: {
+	schema: unknown;
+	data: unknown;
+	/** 权威 schema（workflow 模式由 PI_WORKFLOW_SCHEMA env 注入）。存在时成为唯一校验权威。 */
+	authoritativeSchema?: unknown;
+}): Promise<{
+	content: Array<{ type: "text"; text: string }>;
+	// data 可能是 primitive/array/object（根 schema 决定），故 details 为 unknown。
+	// 测试断言 toEqual(42)/toEqual(true)/toEqual(["a","b","c"])，不可窄化为 Record。
+	details: unknown;
+}> {
+	// Normalize: some models pass schema/data as JSON strings instead of objects
+	const schema = tryParseJson(params.schema);
+	const data = tryParseJson(params.data);
+
+	// ── 权威模式（workflow）：用 PI_WORKFLOW_SCHEMA 声明的期望 schema 校验 data。 ──
+	// LLM 传入的 schema 仅用于错误回显（告知期望形态），不参与校验——否则 LLM
+	// 可同时控制 schema 与 data 自洽绕过任何约束。日常模式无权威 schema 走下方防御链。
+	const authoritative =
+		params.authoritativeSchema !== undefined ? tryParseJson(params.authoritativeSchema) : undefined;
+	if (authoritative !== undefined) {
+		try {
+			// 先用 assert 函数把 unknown 收窄为 Record<string,unknown> | boolean，
+			// 使后续分支在类型层面成立（type-safety）。非 object/boolean 抛清晰错误，
+			// 由外层 catch 包成含 echo 的错误。
+			assertJsonSchemaRoot(authoritative);
+		} catch (e) {
+			throw new Error(
+				`Invalid authoritative JSON Schema (from PI_WORKFLOW_SCHEMA): ${(e as Error).message}. `
+				+ `Received schema=${echo(schema)}, data=${echo(data)}`,
+			);
+		}
+
+		if (authoritative === true) {
+			// ERR-7：boolean true（accept-all）不提供任何形状约束，workflow 用它等于没校验。
+			// 必须改为 object schema 才构成真正的约束（keyword-less 拒绝见 validateWithAuthoritative）。
+			throw new Error(
+				"Authoritative schema (PI_WORKFLOW_SCHEMA) is boolean true (accept-all), "
+				+ "provides no shape constraint. 👉 改为带 type/properties/items 的 object schema。"
+				+ `Received schema=${echo(schema)}, data=${echo(data)}`,
+			);
+		}
+
+		if (authoritative === false) {
+			// boolean false = reject-all（draft-07 合法根，有形状约束语义：拒绝一切）。
+			// 保留原行为：编译 + 校验失败抛 'Schema validation failed (authoritative)'。
+			const validate = getOrCompileValidator(false);
+			const valid = validate(data);
+			if (!valid) {
+				const errors = validate.errors
+					?.map((err) => `${err.instancePath} ${err.message}`)
+					.join("; ");
+				throw new Error(
+					`Schema validation failed (authoritative): ${errors}. `
+					+ `The authoritative schema (PI_WORKFLOW_SCHEMA) is: ${echo(authoritative)}. `
+					+ `Received schema=${echo(schema)}, data=${echo(data)}`,
+				);
+			}
+		} else {
+			// object 权威 schema：过 keyword-less 检查（ERR-3）+ 编译 + 校验。
+			validateWithAuthoritative(data, authoritative);
+		}
+
+		return {
+			content: [
+				{ type: "text" as const, text: "Structured output recorded successfully." },
+			],
+			details: data,
+		};
+	}
+
+	// ── 日常模式防御链（validateAgainstSelfReported：互换/keyword-less/编译/校验）──
+	validateAgainstSelfReported(schema, data);
+
+	return {
+		content: [
+			{ type: "text" as const, text: "Structured output recorded successfully." },
+		],
+		details: data,
+	};
+}

package/src/index.ts

@@ -9,438 +9,23 @@
  *   turn_end 时检查模型是否调用了 structured-output 工具。
  *   如果没调 → 通过 pi.sendUserMessage() 注入 steering message 强制调用。
  *   最多重试 2 次，防止无限循环。
+ *
+ * 模块拆分（M4）：实现体分布于 ajv-validator.ts（编译缓存）/
+ * schema-guards.ts（形态守卫）/ execute.ts（校验编排）/ tool-definition.ts（工具定义）/
+ * workflow-hook.ts（hook + RetryState）。本文件仅剩 entry 装配与 re-export。
  */
 
-import { Type } from "typebox";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import Ajv, { type ValidateFunction } from "ajv";
+
+import { executeStructuredOutput } from "./execute.js";
+import { createToolDefinition, ENV_SCHEMA } from "./tool-definition.js";
+import { RetryState, setupWorkflowHook } from "./workflow-hook.js";
 
 /** Pi Extension API — properly typed via ExtensionAPI from pi-coding-agent SDK */
 type PiAPI = ExtensionAPI;
 
-const TOOL_NAME = "structured-output";
-const ENV_SCHEMA = "PI_WORKFLOW_SCHEMA";
-const MAX_HOOK_RETRIES = 2;
-
-// ── Ajv WeakMap cache ─────────────────────────────────────────
-const ajvCache = new WeakMap<object, ValidateFunction>();
-
-function getOrCompileValidator(schema: Record<string, unknown> | boolean): ValidateFunction {
-	// boolean 根 schema（true=接受一切，false=拒绝一切）是合法 draft-07，
-	// 但 boolean 不能做 WeakMap key，故不缓存（编译结果恒定，重复编译无副作用）。
-	if (typeof schema === "boolean") {
-		return new Ajv({ strict: false }).compile(schema);
-	}
-	const cached = ajvCache.get(schema);
-	if (cached) return cached;
-
-	const ajv = new Ajv({ strict: false });
-	const validate = ajv.compile(schema);
-	ajvCache.set(schema, validate);
-	return validate;
-}
-
-// ── Schema-shape guards (swap detection + silent-corruption prevention) ──
-//
-// 核心问题：schema 和 data 参数都用 Type.Unknown()，结构无差别。弱模型常把答案
-// 塞进 schema、把形状塞进 data。因 ajv strict:false 把无 keyword 的对象编译成
-// "接受一切" 的 validator，互换后会校验通过、存垃圾、无报错（静默腐败）。
-// 这组守卫在编译前拦截两类形态：互换（schema 像数据 + data 像 schema）和
-// keyword-less schema（{} / {a:1} 这种会被 ajv 静默放行）。
-
-/** JSON Schema draft-07 识别 keyword。只要 schema 含其一就认为是"真 schema"。 */
-const SCHEMA_KEYWORDS = [
-	// 核心类型
-	"type",
-	// object
-	"properties", "required", "additionalProperties", "patternProperties",
-	"minProperties", "maxProperties",
-	// array
-	"items", "additionalItems", "minItems", "maxItems", "uniqueItems",
-	// enum / const
-	"enum", "const",
-	// 组合
-	"allOf", "anyOf", "oneOf", "not",
-	// 条件验证（draft-07）
-	"if", "then", "else",
-	// 依赖与约束
-	"dependencies", "propertyNames", "contains",
-	// 引用与定义
-	"$ref", "$id", "$defs", "definitions",
-	// 数值
-	"minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf",
-	// 字符串
-	"minLength", "maxLength", "pattern", "format",
-] as const;
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function hasSchemaKeyword(obj: Record<string, unknown>): boolean {
-	return SCHEMA_KEYWORDS.some((keyword) => keyword in obj);
-}
-
-/** 错误回显长度上限（截断长 schema/data，避免错误消息爆炸）。 */
-const ECHO_MAX_CHARS = 200;
-
-function echo(value: unknown): string {
-	let str: string;
-	try {
-		// JSON.stringify(undefined) 返回 undefined（不是 throw），需 ?? 兜底，
-		// 否则后续 str.length 会 "Cannot read properties of undefined"。
-		str = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
-	} catch {
-		str = String(value);
-	}
-	return str.length <= ECHO_MAX_CHARS ? str : `${str.slice(0, ECHO_MAX_CHARS)}...`;
-}
-
-/**
- * 尝试 JSON.parse；失败（malformed JSON）时保留原值，让 Ajv 拒绝。
- * 模型有时把 schema/data 当 JSON 字符串传；parse 失败不是错误，保持原样让下游校验拒绝。
- * catch 里有实质处理（决定返回原值），满足 taste/no-silent-catch。
- */
-function tryParseJson(raw: unknown): unknown {
-	if (typeof raw !== "string") return raw;
-	try {
-		return JSON.parse(raw);
-	} catch {
-		return raw; // malformed JSON → 保留原字符串，Ajv 会拒绝
-	}
-}
-
-/**
- * 把 authoritative schema 的 unknown 收窄为合法 JSON Schema 根类型（object | boolean）。
- * draft-07 允许 boolean 根 schema（true=接受一切，false=拒绝一切）。
- * 独立守卫使后续 getOrCompileValidator(authoritative) 在类型层面也成立，
- * 避免在守卫块外直接用 unknown。非合法形态抛清晰错误（与日常模式第 235 行同构）。
- */
-function assertJsonSchemaRoot(value: unknown): asserts value is Record<string, unknown> | boolean {
-	if (!(isPlainObject(value) || typeof value === "boolean")) {
-		throw new Error(`authoritative schema must be a JSON Schema object or boolean, got ${typeof value}`);
-	}
-}
-
-/** turn_end event 是否可安全访问 message.stopReason（用于判断模型是否还在调工具链）。 */
-function isTurnEndEvent(e: unknown): e is { message?: { stopReason?: string } } {
-	return typeof e === "object" && e !== null;
-}
-
-/** tool_execution_end event 结构守卫（替代直接 cast，配合 taste/no-unsafe-cast）。 */
-function isToolExecutionEndEvent(
-	e: unknown,
-): e is { toolName: unknown; isError: unknown; result?: unknown } {
-	return typeof e === "object" && e !== null && "toolName" in e && "isError" in e;
-}
-
-/** swap 检测 + keyword-less schema 拒绝的纠错文案前缀，所有相关错误共用。 */
-const CORRECT_USAGE_HINT =
-	"Correct: structured_output({schema:{type:'object',properties:{...}}, data:{...actual values}}). ";
-
-/**
- * 执行 schema 校验。从 createToolDefinition.execute 抽出以便单元测试直接调用。
- *
- * 两种模式：
- *   - 权威模式（workflow）：`authoritativeSchema` 存在时，只用它校验 data，LLM 传入的
- *     `schema` 不参与校验（仅用于错误回显）。这从根上杜绝 LLM 自报 schema 自洽绕过
- *     （[HISTORICAL] 2026-08-01 事故：ds-flash 重写 add_channels.items 的 schema 后
- *     自洽通过，4 条 channel 修复静默丢失）。权威分支提前 return，跳过日常防御链
- *     （权威 schema 由 workflow 脚本写死，不存在互换/keyword-less 风险）。
- *   - 日常模式（交互式）：无 `authoritativeSchema`，走下方防御链。
- *
- * 日常模式防御顺序（编译前拦截，治静默腐败的根）：
- *   1. 互换检测 — schema 像 data（无 keyword）且 data 像 schema（有 keyword）→ 抛纠错
- *   2. keyword-less schema 拒绝 — schema 是对象但无任何识别 keyword（{} / {a:1}）
- *      → 抛 "no recognized keyword"，否则 ajv strict:false 会编译成"接受一切"
- *   3. ajv 编译失败 → 抛 "Invalid JSON Schema"（含回显）
- *   4. 校验失败 → 抛 "Schema validation failed"（含回显）
- */
-export async function executeStructuredOutput(params: {
-	schema: unknown;
-	data: unknown;
-	/** 权威 schema（workflow 模式由 PI_WORKFLOW_SCHEMA env 注入）。存在时成为唯一校验权威。 */
-	authoritativeSchema?: unknown;
-}): Promise<{
-	content: Array<{ type: "text"; text: string }>;
-	// data 可能是 primitive/array/object（根 schema 决定），故 details 为 unknown。
-	// 测试断言 toEqual(42)/toEqual(true)/toEqual(["a","b","c"])，不可窄化为 Record。
-	details: unknown;
-}> {
-	// Normalize: some models pass schema/data as JSON strings instead of objects
-	const schema = tryParseJson(params.schema);
-	const data = tryParseJson(params.data);
-
-	// ── 权威模式（workflow）：用 PI_WORKFLOW_SCHEMA 声明的期望 schema 校验 data。 ──
-	// LLM 传入的 schema 仅用于错误回显（告知期望形态），不参与校验——否则 LLM
-	// 可同时控制 schema 与 data 自洽绕过任何约束。日常模式无权威 schema 走下方防御链。
-	const authoritative =
-		params.authoritativeSchema !== undefined ? tryParseJson(params.authoritativeSchema) : undefined;
-	if (authoritative !== undefined) {
-		let validate: ValidateFunction;
-		try {
-			// 先用 assert 函数把 unknown 收窄为 Record<string,unknown> | boolean，
-			// 使后续 getOrCompileValidator(authoritative) 在类型层面也成立（type-safety）。
-			// 运行时行为不变：非 object/boolean 抛清晰错误，由外层 catch 包成含 echo 的错误。
-			assertJsonSchemaRoot(authoritative);
-			validate = getOrCompileValidator(authoritative);
-		} catch (e) {
-			throw new Error(
-				`Invalid authoritative JSON Schema (from PI_WORKFLOW_SCHEMA): ${(e as Error).message}. `
-				+ `Received schema=${echo(schema)}, data=${echo(data)}`,
-			);
-		}
-		const valid = validate(data);
-		if (!valid) {
-			const errors = validate.errors
-				?.map((err) => `${err.instancePath} ${err.message}`)
-				.join("; ");
-			throw new Error(
-				`Schema validation failed (authoritative): ${errors}. `
-				+ `The authoritative schema (PI_WORKFLOW_SCHEMA) is: ${echo(authoritative)}. `
-				+ `Received schema=${echo(schema)}, data=${echo(data)}`,
-			);
-		}
-		return {
-			content: [
-				{ type: "text" as const, text: "Structured output recorded successfully." },
-			],
-			details: data,
-		};
-	}
-
-	// ── 日常模式防御链 ──────────────────────────────────────────────
-
-	// 1. 互换检测：schema 像数据（对象无 keyword）且 data 像 schema（对象有 keyword）。
-	// 这是最严重的静默腐败路径——若放行，ajv 会把"数据形态的 schema"编译成接受一切，
-	// 真正的 schema（此时在 data 里）被丢弃，校验通过并存入垃圾。
-	if (isPlainObject(schema) && !hasSchemaKeyword(schema) && isPlainObject(data) && hasSchemaKeyword(data)) {
-		throw new Error(
-			"Likely swapped: schema looks like data and data looks like a schema. "
-			+ CORRECT_USAGE_HINT
-			+ `Received schema=${echo(schema)}, data=${echo(data)}`,
-		);
-	}
-
-	// 2. keyword-less schema 拒绝：治静默腐败的根。{} / {a:1} 这类对象会被
-	// ajv strict:false 编译成"接受一切"的 validator，模型把答案塞进 schema 时会静默通过。
-	if (isPlainObject(schema) && !hasSchemaKeyword(schema)) {
-		throw new Error(
-			"Invalid JSON Schema: schema has no recognized keyword "
-			+ "(type/properties/items/enum/...). If you passed the answer value as schema, "
-			+ "you likely swapped schema and data. "
-			+ CORRECT_USAGE_HINT
-			+ `Received schema=${echo(schema)}`,
-		);
-	}
-
-	// 3. ajv 编译。schema 此时可能是 object（过 keyword 检查）、boolean（合法 draft-07 根）、
-	// 或 string/number/array/null（非法 → 显式抛错给清晰提示）。getOrCompileValidator 只接受
-	// object|boolean，消除原先的 `as Record<string,unknown>` 不安全 cast。
-	let validate: ValidateFunction;
-	try {
-		if (isPlainObject(schema) || typeof schema === "boolean") {
-			validate = getOrCompileValidator(schema);
-		} else {
-			throw new Error(`schema must be a JSON Schema object or boolean, got ${typeof schema}`);
-		}
-	} catch (e) {
-		throw new Error(
-			`Invalid JSON Schema: ${(e as Error).message}. `
-			+ `Received schema=${echo(schema)}, data=${echo(data)}`,
-		);
-	}
-
-	// 4. 校验
-	const valid = validate(data);
-	if (!valid) {
-		const errors = validate.errors
-			?.map((err) => `${err.instancePath} ${err.message}`)
-			.join("; ");
-		throw new Error(
-			`Schema validation failed: ${errors}. `
-			+ `Received schema=${echo(schema)}, data=${echo(data)}`,
-		);
-	}
-
-	return {
-		content: [
-			{ type: "text" as const, text: "Structured output recorded successfully." },
-		],
-		details: data,
-	};
-}
-
-// ── Tool definition (shared between modes) ─────────────────────
-
-export function createToolDefinition() {
-	return {
-		name: TOOL_NAME,
-		label: "Structured Output",
-		description:
-			"Return structured output validated against a JSON Schema. "
-			+ "Call this tool to produce validated JSON data. "
-			+ "Pass `schema` (a JSON Schema draft-07 object) and `data` (the value to validate). "
-			+ "When the schema is system-enforced (workflow mode), pass ONLY `data` — "
-			+ "the `schema` parameter is ignored (the system validates `data` against the authoritative schema).\n\n"
-			+ "schema describes the shape; data fills the values; they must match.\n\n"
-			+ "✅ Correct (full call): structured_output({schema:{type:'object',properties:{name:{type:'string'},age:{type:'number'}},required:['name']}, data:{name:'Alice',age:30}})\n"
-			+ "✅ Correct: schema={type:'array',items:{type:'string'}}, data=['a','b','c']\n"
-			+ "✅ Correct: schema={type:'string',enum:['low','medium','high']}, data='medium'\n"
-			+ "✅ Correct: schema={type:'number',minimum:0,maximum:100}, data=42\n"
-			+ "✅ Correct: schema={type:'boolean'}, data=true\n\n"
-			+ "❌ Wrong: putting the answer in text instead of calling this tool\n"
-			+ "❌ Wrong: data not matching schema (e.g. schema requires number but data is string)\n"
-			+ "❌ Wrong: schema={type:'object'} with data='hello' (string ≠ object)\n"
-			+ "❌ Wrong: structured_output({name:'Alice'}) — missing the schema/data envelope. Wrap as {schema:{...}, data:{name:'Alice'}}.\n"
-			+ "❌ Wrong: swapping schema and data (passing the answer as schema). The tool detects this as 'likely swapped' and rejects it.\n"
-			+ "❌ Wrong: merging schema and data into one object.\n"
-			+ "❌ Wrong: schema with no recognized JSON Schema keyword (e.g. {} or {answer:42}). The schema must describe shape via draft-07 keywords (type/properties/items/if-then-else/enum/...); a keyword-less object is rejected to prevent silent accept-all compilation.",
-		promptSnippet:
-			"Use structured-output to return validated JSON data. "
-			+ "Pass schema (JSON Schema draft-07) and data (your output). "
-			+ "Example: {schema:{type:'object',properties:{score:{type:'number'}},required:['score']}, data:{score:8}}",
-		promptGuidelines: [
-			"schema must be a valid JSON Schema (draft-07). data must conform to it.",
-			"Both primitive types (string, number, boolean) and complex types (object, array) are valid schema roots.",
-			"Do not output JSON in text — call this tool instead.",
-		],
-		parameters: Type.Object({
-			schema: Type.Unknown({
-				description: "JSON Schema draft-07 object. Example: {type:'object',properties:{name:{type:'string'}},required:['name']}",
-			}),
-			data: Type.Unknown({
-				description: "The value to validate against schema. Example: {name:'Alice'}",
-			}),
-		}),
-		async execute(
-			_toolCallId: string,
-			params: { schema: unknown; data: unknown },
-		) {
-			// workflow 模式（PI_WORKFLOW_SCHEMA 存在）：权威 schema 成为唯一校验权威，
-			// LLM 传入的 params.schema 被降级为错误回显，无法影响校验结果。
-			//
-			// 运行假设：workflow 子进程是单 session 进程（由 applySchemaEnvToChildEnv 在
-			// session-runner 注入 PI_WORKFLOW_SCHEMA）。Pi extension 状态在 session_start 重建，
-			// 但 process.env 在进程级共享——这里依赖「workflow 子进程不会复用未注入 env 的 session」
-			// 的单 session 约定，故直接读 process.env 而非维护 per-session 缓存。
-			//
-			// 判空用 `|| undefined` 归一空串为 undefined（truthy 语义），与 entry 的 `if (schemaEnv)`
-			// 和 applySchemaEnvToChildEnv 的 `if (schemaEnv)` 统一：空串 env 视为未设置。
-			const authoritativeSchema = process.env[ENV_SCHEMA] || undefined;
-			return executeStructuredOutput(
-				authoritativeSchema !== undefined
-					? { ...params, authoritativeSchema }
-					: params,
-			);
-		},
-	};
-}
-
-// ── Workflow hook ──────────────────────────────────────────────
-
-/**
- * 从 tool 执行结果里提取错误文本。
- *
- * Pi 框架在 tool execute 抛错时，构造 `{ content: [{ type: "text", text }] }`
- * 塞进 result.content[0].text（见 extensions/unified-hooks 的 extractErrorText 及其
- * 文档：SDK 事件结构里没有独立 errorMessage 字段，错误文本只能从 result.content 里取）。
- * 这里防御性取多种结构，取不到就返回 undefined（调用方降级为通用提示）。
- */
-function extractToolErrorText(result: unknown): string | undefined {
-	// 常见结构：{ content: [{ type: "text", text: "..." }] }
-	if (typeof result === "object" && result !== null) {
-		const content = (result as Record<string, unknown>).content;
-		if (Array.isArray(content)) {
-			for (const item of content) {
-				if (typeof item === "object" && item !== null) {
-					const text = (item as Record<string, unknown>).text;
-					if (typeof text === "string" && text.length > 0) return text;
-				}
-			}
-		}
-		// 兜底：某些 tool 直接塞 { error: "..." }
-		const err = (result as Record<string, unknown>).error;
-		if (typeof err === "string" && err.length > 0) return err;
-	}
-	return undefined;
-}
-
-/**
- * 注册 turn_end hook，检查模型是否成功调用 structured-output 工具。
- * 未成功时通过 pi.sendUserMessage({deliverAs:"steer"}) 注入 steering message 重试。
- *
- * 两种失败形态都会触发 steer：
- * 1. 完全没调用（soCallCount === 0）→ 注入"必须调用"提示 + 正确 schema
- * 2. 调了但全是 isError（soCallCount > 0 && !soSucceededEver）→ 注入具体校验错误
- *    + 正确 schema。旧实现在此处撒手交给 Pi 自然修正，但模型遇到 "Invalid JSON Schema"
- *    时无法自行修正（它不知道正确 schema 长什么样），实测会放弃 → 子进程正常退出 →
- *    workflow 把单点失败放大成整批崩溃。故此处主动 steer 并回灌错误细节。
- *
- * 检测时序：Pi 保证同 turn 内所有 tool_execution_end 都在 turn_end 之前触发，
- * 故 turn_end 读取的状态已反映本 turn 全部 tool 调用结果。
- */
-function setupWorkflowHook(pi: PiAPI, schemaJson: string): void {
-	let soCallCount = 0;
-	let soSucceededEver = false;
-	let hookRetryCount = 0;
-	// 最近一次 structured-output 调用的错误文本（isError=true 时从 result.content 提取）。
-	// turn_end 据此决定 steer 消息是"必须调用"还是"修正后重试"。
-	let lastSchemaError = "";
-
-	// 追踪 structured-output 调用结果：
-	// 成功 → soSucceededEver=true（终态，后续不再干预）
-	// 失败 → soCallCount++，记录 lastSchemaError，由 turn_end 决定是否 steer 重试
-	pi.on("tool_execution_end", async (event: unknown) => {
-		if (!isToolExecutionEndEvent(event)) return;
-		if (event.toolName !== TOOL_NAME) return;
-		soCallCount++;
-		if (event.isError !== true) {
-			soSucceededEver = true;
-		} else {
-			lastSchemaError = extractToolErrorText(event.result) ?? "structured-output call failed";
-		}
-	});
-
-	pi.on("turn_end", async (event: unknown) => {
-		// 已经成功调用过 structured-output，不再干预
-		if (soSucceededEver) return;
-
-		// 完全没调用 OR 调了但全是失败 → 都需要 steer。两种情况共用重试上限与计数。
-		// stopReason="toolUse" → 模型还在调工具链，不需要干预
-		if (!isTurnEndEvent(event)) return;
-		if (event.message?.stopReason === "toolUse") return;
-
-		// 超过重试上限：放弃，让子进程自然结束（调用方据 result.error 判定失败）
-		if (hookRetryCount >= MAX_HOOK_RETRIES) return;
-
-		const calledButFailed = soCallCount > 0;
-		// 按本 turn 重置计数；lastSchemaError 在下次 steer 消息构造后自然覆盖
-		soCallCount = 0;
-		hookRetryCount++;
-
-		const reminder = calledButFailed
-			? [
-					"[MANDATORY] Your structured-output call FAILED validation:",
-					lastSchemaError,
-					"",
-					"The schema is enforced by the system (PI_WORKFLOW_SCHEMA) — do NOT pass your own `schema` parameter.",
-					`The required schema for your \`data\` is: ${schemaJson}`,
-					"Call the structured-output tool AGAIN with ONLY the `data` parameter conforming to this schema.",
-					"Do NOT output the result as text — call the tool.",
-				].join("\n")
-			: [
-					"[MANDATORY] You MUST call the structured-output tool now.",
-					"Your task requires a structured output. Do NOT respond with plain text.",
-					`The schema is enforced by the system. Call structured-output with ONLY \`data\` matching this shape: ${schemaJson}`,
-					"Do NOT pass a `schema` parameter — the system validates `data` against the authoritative schema automatically.",
-					"This is enforced by the workflow system. Just call the tool.",
-				].join("\n");
-
-		lastSchemaError = "";
-		pi.sendUserMessage(reminder, { deliverAs: "steer" });
-	});
-}
+// re-export 供测试与外部直接调用（import 路径 ../src/index.js 保持稳定）
+export { executeStructuredOutput, createToolDefinition, RetryState };
 
 // ── Extension entry ────────────────────────────────────────────
 

package/src/schema-guards.ts

@@ -0,0 +1,101 @@
+/**
+ * Schema 形态守卫 — 纯逻辑叶节点（零业务依赖，全导出）。
+ *
+ * 从 index.ts 拆出：swap 检测 + silent-corruption prevention 的一组纯函数。
+ *
+ * 核心问题：schema 和 data 参数都用 Type.Unknown()，结构无差别。弱模型常把答案
+ * 塞进 schema、把形状塞进 data。因 ajv strict:false 把无 keyword 的对象编译成
+ * "接受一切" 的 validator，互换后会校验通过、存垃圾、无报错（静默腐败）。
+ * 这组守卫在编译前拦截两类形态：互换（schema 像数据 + data 像 schema）和
+ * keyword-less schema（{} / {a:1} 这种会被 ajv 静默放行）。
+ */
+
+/** JSON Schema draft-07 识别 keyword。只要 schema 含其一就认为是"真 schema"。 */
+export const SCHEMA_KEYWORDS = [
+	// 核心类型
+	"type",
+	// object
+	"properties", "required", "additionalProperties", "patternProperties",
+	"minProperties", "maxProperties",
+	// array
+	"items", "additionalItems", "minItems", "maxItems", "uniqueItems",
+	// enum / const
+	"enum", "const",
+	// 组合
+	"allOf", "anyOf", "oneOf", "not",
+	// 条件验证（draft-07）
+	"if", "then", "else",
+	// 依赖与约束
+	"dependencies", "propertyNames", "contains",
+	// 引用与定义
+	"$ref", "$id", "$defs", "definitions",
+	// 数值
+	"minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf",
+	// 字符串
+	"minLength", "maxLength", "pattern", "format",
+] as const;
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function hasSchemaKeyword(obj: Record<string, unknown>): boolean {
+	return SCHEMA_KEYWORDS.some((keyword) => keyword in obj);
+}
+
+/** 错误回显长度上限（截断长 schema/data，避免错误消息爆炸）。 */
+const ECHO_MAX_CHARS = 200;
+
+export function echo(value: unknown): string {
+	let str: string;
+	try {
+		// JSON.stringify(undefined) 返回 undefined（不是 throw），需 ?? 兜底，
+		// 否则后续 str.length 会 "Cannot read properties of undefined"。
+		str = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
+	} catch {
+		str = String(value);
+	}
+	return str.length <= ECHO_MAX_CHARS ? str : `${str.slice(0, ECHO_MAX_CHARS)}...`;
+}
+
+/**
+ * 尝试 JSON.parse；失败（malformed JSON）时保留原值，让 Ajv 拒绝。
+ * 模型有时把 schema/data 当 JSON 字符串传；parse 失败不是错误，保持原样让下游校验拒绝。
+ * catch 里有实质处理（决定返回原值），满足 taste/no-silent-catch。
+ */
+export function tryParseJson(raw: unknown): unknown {
+	if (typeof raw !== "string") return raw;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw; // malformed JSON → 保留原字符串，Ajv 会拒绝
+	}
+}
+
+/**
+ * 把 authoritative schema 的 unknown 收窄为合法 JSON Schema 根类型（object | boolean）。
+ * draft-07 允许 boolean 根 schema（true=接受一切，false=拒绝一切）。
+ * 独立守卫使后续 getOrCompileValidator(authoritative) 在类型层面也成立，
+ * 避免在守卫块外直接用 unknown。非合法形态抛清晰错误。
+ */
+export function assertJsonSchemaRoot(value: unknown): asserts value is Record<string, unknown> | boolean {
+	if (!(isPlainObject(value) || typeof value === "boolean")) {
+		throw new Error(`authoritative schema must be a JSON Schema object or boolean, got ${typeof value}`);
+	}
+}
+
+/** turn_end event 是否可安全访问 message.stopReason（用于判断模型是否还在调工具链）。 */
+export function isTurnEndEvent(e: unknown): e is { message?: { stopReason?: string } } {
+	return typeof e === "object" && e !== null;
+}
+
+/** tool_execution_end event 结构守卫（替代直接 cast，配合 taste/no-unsafe-cast）。 */
+export function isToolExecutionEndEvent(
+	e: unknown,
+): e is { toolName: unknown; isError: unknown; result?: unknown } {
+	return typeof e === "object" && e !== null && "toolName" in e && "isError" in e;
+}
+
+/** swap 检测 + keyword-less schema 拒绝的纠错文案前缀，所有相关错误共用。 */
+export const CORRECT_USAGE_HINT =
+	"Correct: structured_output({schema:{type:'object',properties:{...}}, data:{...actual values}}). ";

package/src/tool-definition.ts

@@ -0,0 +1,81 @@
+/**
+ * structured-output tool 定义（两种模式共享）。
+ *
+ * env 桥接：execute 内读 process.env[PI_WORKFLOW_SCHEMA]，存在时注入
+ * authoritativeSchema（workflow 模式权威校验），否则走日常防御链。
+ * description/promptSnippet/promptGuidelines 文本被 prompt-quality.test.ts
+ * 文本断言锁定，逐字保留。
+ */
+
+import { Type } from "typebox";
+
+import { executeStructuredOutput } from "./execute.js";
+
+export const TOOL_NAME = "structured-output";
+export const ENV_SCHEMA = "PI_WORKFLOW_SCHEMA";
+
+// ── Tool definition (shared between modes) ─────────────────────
+
+export function createToolDefinition() {
+	return {
+		name: TOOL_NAME,
+		label: "Structured Output",
+		description:
+			"Return structured output validated against a JSON Schema. "
+			+ "Call this tool to produce validated JSON data. "
+			+ "Pass `schema` (a JSON Schema draft-07 object) and `data` (the value to validate). "
+			+ "When the schema is system-enforced (workflow mode), pass ONLY `data` — "
+			+ "the `schema` parameter is ignored (the system validates `data` against the authoritative schema).\n\n"
+			+ "schema describes the shape; data fills the values; they must match.\n\n"
+			+ "✅ Correct (full call): structured_output({schema:{type:'object',properties:{name:{type:'string'},age:{type:'number'}},required:['name']}, data:{name:'Alice',age:30}})\n"
+			+ "✅ Correct: schema={type:'array',items:{type:'string'}}, data=['a','b','c']\n"
+			+ "✅ Correct: schema={type:'string',enum:['low','medium','high']}, data='medium'\n"
+			+ "✅ Correct: schema={type:'number',minimum:0,maximum:100}, data=42\n"
+			+ "✅ Correct: schema={type:'boolean'}, data=true\n\n"
+			+ "❌ Wrong: putting the answer in text instead of calling this tool\n"
+			+ "❌ Wrong: data not matching schema (e.g. schema requires number but data is string)\n"
+			+ "❌ Wrong: schema={type:'object'} with data='hello' (string ≠ object)\n"
+			+ "❌ Wrong: structured_output({name:'Alice'}) — missing the schema/data envelope. Wrap as {schema:{...}, data:{name:'Alice'}}.\n"
+			+ "❌ Wrong: swapping schema and data (passing the answer as schema). The tool detects this as 'likely swapped' and rejects it.\n"
+			+ "❌ Wrong: merging schema and data into one object.\n"
+			+ "❌ Wrong: schema with no recognized JSON Schema keyword (e.g. {} or {answer:42}). The schema must describe shape via draft-07 keywords (type/properties/items/if-then-else/enum/...); a keyword-less object is rejected to prevent silent accept-all compilation.",
+		promptSnippet:
+			"Use structured-output to return validated JSON data. "
+			+ "Pass schema (JSON Schema draft-07) and data (your output). "
+			+ "Example: {schema:{type:'object',properties:{score:{type:'number'}},required:['score']}, data:{score:8}}",
+		promptGuidelines: [
+			"schema must be a valid JSON Schema (draft-07). data must conform to it.",
+			"Both primitive types (string, number, boolean) and complex types (object, array) are valid schema roots.",
+			"Do not output JSON in text — call this tool instead.",
+		],
+		parameters: Type.Object({
+			schema: Type.Unknown({
+				description: "JSON Schema draft-07 object. Example: {type:'object',properties:{name:{type:'string'}},required:['name']}",
+			}),
+			data: Type.Unknown({
+				description: "The value to validate against schema. Example: {name:'Alice'}",
+			}),
+		}),
+		async execute(
+			_toolCallId: string,
+			params: { schema: unknown; data: unknown },
+		) {
+			// workflow 模式（PI_WORKFLOW_SCHEMA 存在）：权威 schema 成为唯一校验权威，
+			// LLM 传入的 params.schema 被降级为错误回显，无法影响校验结果。
+			//
+			// 运行假设：workflow 子进程是单 session 进程（由 applySchemaEnvToChildEnv 在
+			// session-runner 注入 PI_WORKFLOW_SCHEMA）。Pi extension 状态在 session_start 重建，
+			// 但 process.env 在进程级共享——这里依赖「workflow 子进程不会复用未注入 env 的 session」
+			// 的单 session 约定，故直接读 process.env 而非维护 per-session 缓存。
+			//
+			// 判空用 `|| undefined` 归一空串为 undefined（truthy 语义），与 entry 的 `if (schemaEnv)`
+			// 和 applySchemaEnvToChildEnv 的 `if (schemaEnv)` 统一：空串 env 视为未设置。
+			const authoritativeSchema = process.env[ENV_SCHEMA] || undefined;
+			return executeStructuredOutput(
+				authoritativeSchema !== undefined
+					? { ...params, authoritativeSchema }
+					: params,
+			);
+		},
+	};
+}

package/src/workflow-hook.ts

@@ -0,0 +1,160 @@
+/**
+ * Workflow hook：turn_end 时检查模型是否成功调用 structured-output 工具。
+ * 未成功时通过 pi.sendUserMessage({deliverAs:"steer"}) 注入 steering message 重试。
+ * 最多重试 MAX_HOOK_RETRIES 次，防止无限循环。
+ *
+ * RetryState：从旧 4 个 mutable 闭包（soCallCount/soSucceededEver/hookRetryCount/
+ * lastSchemaError）显式化为类——per-turn reset 时机成为可单测的显式契约：
+ * onTurnEnd() 仅在「判定要 steer」时调用（守卫链 toolUse/超上限/成功短路均不调）。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { isToolExecutionEndEvent, isTurnEndEvent } from "./schema-guards.js";
+
+/** Pi Extension API — properly typed via ExtensionAPI from pi-coding-agent SDK */
+type PiAPI = ExtensionAPI;
+
+// 与 tool-definition.ts 的 TOOL_NAME 对应（本模块只监听该工具的 execution 事件；
+// 保持依赖图单向：workflow-hook → schema-guards，不 import tool-definition）。
+const TOOL_NAME = "structured-output";
+const MAX_HOOK_RETRIES = 2;
+
+/**
+ * structured-output 调用状态机（IF-7，export 契约——M5 从本模块 import）。
+ *
+ * 转移表（M4-TC-2 单测锁定）：
+ *   - onToolExecEnd(false)      → soCallCount++ / soSucceededEver=true（成功短路终态）
+ *   - onToolExecEnd(true, err)  → soCallCount++ / lastSchemaError=err ?? 通用提示
+ *   - onTurnEnd()               → soCallCount=0 / hookRetryCount++ / lastSchemaError=null
+ *     （仅当 workflow-hook 判定要 steer 时调用——toolUse/超上限/成功短路均不调，
+ *      故 toolUse 保留 soCallCount、超上限保留 lastSchemaError，与旧 4-closure 逐点一致）
+ */
+export class RetryState {
+	soCallCount = 0;
+	soSucceededEver = false;
+	hookRetryCount = 0;
+	lastSchemaError: string | null = null;
+
+	/** 记录一次 structured-output tool 执行结果。hasError = event.isError === true。 */
+	onToolExecEnd(hasError: boolean, errorMsg?: string): { shouldSteer: boolean } {
+		this.soCallCount++;
+		if (!hasError) {
+			this.soSucceededEver = true;
+			return { shouldSteer: false };
+		}
+		this.lastSchemaError = errorMsg ?? "structured-output call failed";
+		return { shouldSteer: true };
+	}
+
+	/** turn 收尾（仅当要 steer 时调用）：重置本 turn 计数、累计重试次数、清空错误。 */
+	onTurnEnd(): void {
+		this.soCallCount = 0;
+		this.hookRetryCount++;
+		this.lastSchemaError = null;
+	}
+
+	/** 四字段归零（当前无调用方；保留作状态机完整契约）。 */
+	reset(): void {
+		this.soCallCount = 0;
+		this.soSucceededEver = false;
+		this.hookRetryCount = 0;
+		this.lastSchemaError = null;
+	}
+}
+
+/**
+ * 从 tool 执行结果里提取错误文本。
+ *
+ * Pi 框架在 tool execute 抛错时，构造 `{ content: [{ type: "text", text }] }`
+ * 塞进 result.content[0].text（见 extensions/unified-hooks 的 extractErrorText 及其
+ * 文档：SDK 事件结构里没有独立 errorMessage 字段，错误文本只能从 result.content 里取）。
+ * 这里防御性取多种结构，取不到就返回 undefined（调用方降级为通用提示）。
+ */
+function extractToolErrorText(result: unknown): string | undefined {
+	// 常见结构：{ content: [{ type: "text", text: "..." }] }
+	if (typeof result === "object" && result !== null) {
+		const content = (result as Record<string, unknown>).content;
+		if (Array.isArray(content)) {
+			for (const item of content) {
+				if (typeof item === "object" && item !== null) {
+					const text = (item as Record<string, unknown>).text;
+					if (typeof text === "string" && text.length > 0) return text;
+				}
+			}
+		}
+		// 兜底：某些 tool 直接塞 { error: "..." }
+		const err = (result as Record<string, unknown>).error;
+		if (typeof err === "string" && err.length > 0) return err;
+	}
+	return undefined;
+}
+
+/**
+ * 注册 turn_end hook，检查模型是否成功调用 structured-output 工具。
+ * 未成功时通过 pi.sendUserMessage({deliverAs:"steer"}) 注入 steering message 重试。
+ *
+ * 两种失败形态都会触发 steer：
+ * 1. 完全没调用（soCallCount === 0）→ 注入"必须调用"提示 + 正确 schema
+ * 2. 调了但全是 isError（soCallCount > 0 && !soSucceededEver）→ 注入具体校验错误
+ *    + 正确 schema。旧实现在此处撒手交给 Pi 自然修正，但模型遇到 "Invalid JSON Schema"
+ *    时无法自行修正（它不知道正确 schema 长什么样），实测会放弃 → 子进程正常退出 →
+ *    workflow 把单点失败放大成整批崩溃。故此处主动 steer 并回灌错误细节。
+ *
+ * 检测时序：Pi 保证同 turn 内所有 tool_execution_end 都在 turn_end 之前触发，
+ * 故 turn_end 读取的状态已反映本 turn 全部 tool 调用结果。
+ */
+export function setupWorkflowHook(pi: PiAPI, schemaJson: string): void {
+	const state = new RetryState();
+
+	// 追踪 structured-output 调用结果：
+	// 成功 → soSucceededEver=true（终态，后续不再干预）
+	// 失败 → soCallCount++，记录 lastSchemaError，由 turn_end 决定是否 steer 重试
+	pi.on("tool_execution_end", async (event: unknown) => {
+		if (!isToolExecutionEndEvent(event)) return;
+		if (event.toolName !== TOOL_NAME) return;
+		state.onToolExecEnd(
+			event.isError === true,
+			extractToolErrorText(event.result) ?? "structured-output call failed",
+		);
+	});
+
+	pi.on("turn_end", async (event: unknown) => {
+		// 守卫链：以下情况均直接 return（不调 onTurnEnd——toolUse 保留 soCallCount、
+		// 超上限保留 lastSchemaError，与旧 4-closure 逐点一致）：
+		// 1. 已经成功调用过 structured-output，不再干预
+		// 2. 不是合法 turn_end 事件
+		// 3. stopReason="toolUse" → 模型还在调工具链，不需要干预
+		// 4. 超过重试上限：放弃，让子进程自然结束（调用方据 result.error 判定失败）
+		if (state.soSucceededEver) return;
+		if (!isTurnEndEvent(event)) return;
+		if (event.message?.stopReason === "toolUse") return;
+		if (state.hookRetryCount >= MAX_HOOK_RETRIES) return;
+
+		// 完全没调用 OR 调了但全是失败 → 都需要 steer。两种情况共用重试上限与计数。
+		const calledButFailed = state.soCallCount > 0;
+		// 构造 reminder 时 lastSchemaError 必须仍是本 turn 的错误文本，
+		// 故 onTurnEnd()（清空 lastSchemaError）必须在 reminder 构造之后调用。
+		const reminder = calledButFailed
+			? [
+					"[MANDATORY] Your structured-output call FAILED validation:",
+					state.lastSchemaError ?? "structured-output call failed",
+					"",
+					"The schema is enforced by the system (PI_WORKFLOW_SCHEMA) — do NOT pass your own `schema` parameter.",
+					`The required schema for your \`data\` is: ${schemaJson}`,
+					"Call the structured-output tool AGAIN with ONLY the `data` parameter conforming to this schema.",
+					"Do NOT output the result as text — call the tool.",
+				].join("\n")
+			: [
+					"[MANDATORY] You MUST call the structured-output tool now.",
+					"Your task requires a structured output. Do NOT respond with plain text.",
+					`The schema is enforced by the system. Call structured-output with ONLY \`data\` matching this shape: ${schemaJson}`,
+					"Do NOT pass a `schema` parameter — the system validates `data` against the authoritative schema automatically.",
+					"This is enforced by the workflow system. Just call the tool.",
+				].join("\n");
+
+		// 按本 turn 重置计数、累计重试次数、清空 lastSchemaError（steer 后本 turn 状态归零）
+		state.onTurnEnd();
+		pi.sendUserMessage(reminder, { deliverAs: "steer" });
+	});
+}