@zhushanwen/pi-structured-output 5.0.2 → 5.1.1

package/src/tool-definition.ts

@@ -1,22 +1,191 @@
 /**
- * structured-output tool 定义（两种模式共享）。
+ * structured-output tool 定义（D1 双变体分岔）。
  *
- * env 桥接：execute 内读 process.env[PI_WORKFLOW_SCHEMA]，存在时注入
- * authoritativeSchema（workflow 模式权威校验），否则走日常防御链。
- * description/promptSnippet/promptGuidelines 文本被 prompt-quality.test.ts
- * 文本断言锁定，逐字保留。
+ * - createWorkflowToolDefinition(envSchema)：PI_WORKFLOW_SCHEMA 存在时注册。
+ *   parameters 即权威 schema 本身（object 根直接用 + 根级 additionalProperties
+ *   未声明时注入 false（D4）；非 object 根包装 {value}（P6：tool call arguments
+ *   必须是 object，execute 侧对称解包））。「模型不携带 schema」从文案约束升级为
+ *   结构约束——pi-ai 参数层直接按权威 schema 校验，不存在可以传错的地方（G1/G3）。
+ *   description 按注册期已知的根类型条件化：object 根口径「arguments ARE the
+ *   data」；非 object 根参数层实际是 {value} 包装（模型直传裸值必首调失败），
+ *   文案明确告知包装契约与 value. 错误路径前缀。裸 object（D4 后只接受空对象）
+ *   追加显式警示。文案判定与包装判定同源（isObjectRootSchema），无漂移。
+ *   注册期 fail-fast 防御：keyword-less 拒绝（原 ERR-3）与 boolean true 拦截
+ *   （原 ERR-7）从 execute 权威分支上移，非法 schema 在子进程加载期终止。
+ * - createDailyToolDefinition()：无 env 时注册。双参数自报形态逐字节保留（G4），
+ *   仅移除描述文本中的 workflow 语句（D5：workflow 语义只属于 workflow 变体）。
+ *
+ * 两变体的描述文本均被 prompt-quality.test.ts 文本断言锁定。
  */
 
 import { Type } from "typebox";
 
-import { executeStructuredOutput } from "./execute.js";
+import { executeStructuredOutput, isObjectRootSchema } from "./execute.js";
+import {
+	assertJsonSchemaRoot,
+	echo,
+	hasSchemaKeyword,
+	isPlainObject,
+	tryParseJson,
+} from "./schema-guards.js";
 
 export const TOOL_NAME = "structured-output";
 export const ENV_SCHEMA = "PI_WORKFLOW_SCHEMA";
 
-// ── Tool definition (shared between modes) ─────────────────────
+/**
+ * schema env 值的可见性提示阈值（256 KiB，SO-DATA-4）。
+ *
+ * 背景：PI_WORKFLOW_SCHEMA 经 spawn childEnv 注入子进程，env 块受 ARG_MAX 约束
+ *（Linux E2BIG）——超大 schema 会在 spawn 调用点报难归因的失败。硬拒绝在
+ * subagent-workflow 侧（session-runner 的 applySchemaEnvToChildEnv，同值上限
+ * SCHEMA_ENV_MAX_BYTES = 256 * 1024，见其 src/shared/schema-env.ts [跨包契约 SSOT]
+ * 注释）；本包独立 npm 不能直接 import（isObjectRootSchema 本地副本同例），常量
+ * 各自保留、跨包契约测试锁字节相等（tests/cross-package-contract.test.ts）。
+ * 本侧职责仅可见性：注册时超限 logger.warn（无 logger API，stderr 直出惯例）提示
+ * env 通道有上限，建议拆分 schema 或精简——不拒绝注册（子进程能收到 env 说明 SW
+ * 侧闸门已放行，此处拒绝只会把可诊断的降级变成无法启动）。
+ *
+ * [跨包契约] 任一端改值必须同步另一端，否则 SW 侧硬拒绝线与 SO 侧提示线漂移。
+ */
+const SCHEMA_SIZE_WARN_KIB = 256;
+const BYTES_PER_KIB = 1024;
+export const SO_SCHEMA_SIZE_WARN_BYTES = SCHEMA_SIZE_WARN_KIB * BYTES_PER_KIB;
+
+/**
+ * 注册期 schema 体积可见性提示（SO-DATA-4 的 SO 侧职责：提示，不拒绝）。
+ * stderr 直出（本包惯例：ExtensionContext 无 logger 成员，pi 0.84.1 types.d.ts
+ * 核实；与 writeTerminatedLog 同通道）。
+ */
+function warnIfSchemaOversized(envSchema: string): void {
+	const bytes = Buffer.byteLength(envSchema, "utf8");
+	if (bytes <= SO_SCHEMA_SIZE_WARN_BYTES) return;
+	process.stderr.write(
+		`[structured-output] PI_WORKFLOW_SCHEMA is ${bytes} bytes (> ${SO_SCHEMA_SIZE_WARN_BYTES} bytes / `
+			+ `${SO_SCHEMA_SIZE_WARN_BYTES / BYTES_PER_KIB} KiB). The env channel has a size ceiling: the workflow runner `
+			+ "rejects injection above its own limit (spawn fails, hard to attribute), and oversized values can "
+			+ "hit E2BIG (ARG_MAX) at spawn. "
+			+ "👉 精简 outputSchema（删冗余 description / 收敛深嵌套）或拆分为多个小 schema 步骤。\n",
+	);
+}
+
+// ── Workflow variant (parameters = authoritative schema) ─────────────
+
+/**
+ * 合成 workflow 单参数工具（D1）。
+ *
+ * @param envSchema PI_WORKFLOW_SCHEMA env 原值（JSON 字符串；tryParseJson 兼容已解析对象）。
+ * @throws 权威 schema 非法（非 object/boolean 根、boolean true、keyword-less object）
+ *   时在注册期 fail-fast——错误指回 workflow 脚本的 schema 定义（§5.2 形态 d）。
+ */
+export function createWorkflowToolDefinition(envSchema: string) {
+	// SO-DATA-4：注册期体积可见性提示（超 256KiB 提示精简/拆分；硬拒绝在 SW 侧注入点）
+	warnIfSchemaOversized(envSchema);
+
+	// ── 注册期 fail-fast 防御（上移自 execute 权威分支）──
+	const schema = tryParseJson(envSchema);
+	assertJsonSchemaRoot(schema);
+
+	if (schema === true) {
+		// ERR-7 上移：boolean true（accept-all）不提供任何形状约束，workflow 用它等于没校验。
+		throw new Error(
+			"Authoritative schema (PI_WORKFLOW_SCHEMA) is boolean true (accept-all), "
+				+ "provides no shape constraint. 👉 改为带 type/properties/items 的 object schema。",
+		);
+	}
+
+	if (isPlainObject(schema) && !hasSchemaKeyword(schema)) {
+		// ERR-3 上移：keyword-less 对象会被编译成 accept-all，workflow 声明的约束静默失效。
+		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(schema)}`,
+		);
+	}
+
+	const isObjectRoot = isObjectRootSchema(schema);
+	const isBareObjectRoot = isBareObjectRootSchema(schema);
+
+	// D4：根级 additionalProperties 未声明时注入 false；作者显式声明（true / 子 schema）
+	// 尊重不动。堵输出污染：旧双参数 envelope 把模型习惯携带的 schema 隔离在专用参数里，
+	// 单参数后该习惯会直接混进 arguments（事故证明 deepseek 类模型有强烈携带倾向），
+	// 参数层显式拒绝并让模型自修正，优于静默剥离。嵌套层级宽严完全由作者 schema 自治。
+	// P6：非 object 根（array / string / boolean / 组合根等）包一层 {value}——tool call
+	// arguments 协议上必须是 object。包装/解包判定与 execute 同源（isObjectRootSchema）。
+	const parameters = isObjectRoot
+		? Type.Unsafe<Record<string, unknown>>({
+				...schema,
+				// type 数组根（如 ["object","null"]）收敛为字符串 "object"：顶层 type 序列化为
+				// 数组会被严格 OpenAI 兼容网关按 C-ext-03 立约动机整会话 400；且 arguments
+				// 协议上恒为 object，"null" 成员本就不可达，含 object 成员时收敛语义无损。
+				...(Array.isArray(schema.type) && schema.type.includes("object") ? { type: "object" } : {}),
+				additionalProperties: schema.additionalProperties ?? false,
+			})
+		: Type.Unsafe<{ value: unknown }>({
+				type: "object",
+				properties: { value: schema },
+				required: ["value"],
+				additionalProperties: false,
+			});
+
+	return {
+		name: TOOL_NAME,
+		label: "Structured Output",
+		// 根类型条件化（与上方 parameters 包装判定同一 isObjectRootSchema，天然同源）。
+		// 保持内联 ternary + 公共尾部：prompt-quality.test.ts 按源码拼接文本断言，
+		// object 根口径字面量被逐字锁定，抽出辅助函数会破坏提取与锁定。
+		description:
+			(isObjectRoot
+				// object 根：arguments 即 data。
+				? "Return the structured result for this task. Your arguments ARE the data; "
+					+ "they are validated against this schema — this tool's parameter schema IS the required shape of your result."
+				// 非 object 根：参数层实际是 {value} 包装（P6），直传裸值必首调失败，
+				// 必须显式告知包装契约；value. 错误路径前缀一并在首读时说明（参数层
+				// 错误文案无改写通道，指引只能前置携带）。
+				: "Return the structured result for this task. Your single argument must be an object "
+					+ "`{value: <data>}` — put the result itself in `value`, and it must conform to this schema. "
+					+ "Non-object schemas are wrapped in a `value` field because tool call arguments must be objects. "
+					+ "Validation errors may reference paths starting with `value.` (e.g. `value.0`, `value.name`): "
+					+ "that prefix addresses the wrapper, not your data — strip it to locate the offending field.")
+			// 裸 object：D4 注入后 parameters 只接受空对象，首读即警示，避免模型
+			// 携带字段反复撞校验。
+			+ (isBareObjectRoot
+				? "\n\nNote: this schema accepts only an empty object {}; any fields will be rejected."
+				: "")
+			+ "\n\nDo not output the result as text — call this tool instead.\n"
+			+ "If validation fails, the error names the fields that failed: "
+			+ "fix those fields to match this tool's parameter schema and call the tool again.",
+		parameters,
+		async execute(_toolCallId: string, params: unknown) {
+			// D2 透传：pi-ai 参数层已按上面的 parameters（= 权威 schema）校验 + 类型矫正过
+			// arguments，execute 不做第二校验（第二校验权威是方案 A 明令禁止的形态）。
+			// 非 object 根的 {value} 解包由 executeStructuredOutput 的 workflow 分支按
+			// 「根是否 object」对称完成（与注册期包装判定同一函数 isObjectRootSchema）。
+			return executeStructuredOutput({ data: params, authoritativeSchema: schema });
+		},
+	};
+}
+
+/**
+ * 裸 object 根检测：object 形态但无任何属性约束（无 properties/patternProperties/
+ * required/minProperties/maxProperties，且未显式声明 additionalProperties）。该形态经
+ * D4 注入 false 后 parameters 只接受空对象 {}。注册期静态可判定 → description 显式警示。
+ * minProperties/maxProperties 也构成约束（F2）：{type:object,minProperties:1} 连空对象
+ * 都拒绝，警示「只接受空对象」反而误导——同 required 一样交由参数层校验错误自然暴露。
+ */
+function isBareObjectRootSchema(schema: unknown): boolean {
+	if (!isObjectRootSchema(schema)) return false;
+	return !("properties" in schema)
+		&& !("patternProperties" in schema)
+		&& !("required" in schema)
+		&& !("minProperties" in schema)
+		&& !("maxProperties" in schema)
+		&& !("additionalProperties" in schema);
+}
+
+// ── Daily variant (self-reported {schema, data}, unchanged behavior) ──
 
-export function createToolDefinition() {
+export function createDailyToolDefinition() {
 	return {
 		name: TOOL_NAME,
 		label: "Structured Output",
@@ -24,8 +193,6 @@ export function createToolDefinition() {
 			"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"
@@ -60,16 +227,12 @@ export function createToolDefinition() {
 			_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 视为未设置。
+			// session-runner 注入 PI_WORKFLOW_SCHEMA）。装配分岔下日常变体注册时 env 为空，
+			// 但桥接判定保留（ENV_SCHEMA 存在 = workflow 模式）：env 有值时注入
+			// authoritativeSchema 走 execute 的 workflow 透传分支。
+			// 判空用 `|| undefined` 归一空串为 undefined（truthy 语义），与 entry 的
+			// `if (schemaEnv)` 统一：空串 env 视为未设置。
 			const authoritativeSchema = process.env[ENV_SCHEMA] || undefined;
 			return executeStructuredOutput(
 				authoritativeSchema !== undefined

package/src/workflow-hook.ts

@@ -10,7 +10,17 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { isToolExecutionEndEvent, isTurnEndEvent } from "./schema-guards.js";
+// 截断原语与错误块预算来自 text-primitives（共享叶节点，导出复用勿复制）。原
+// 「反向依赖（环）」已破除：本模块不再 import loop-gate，依赖图单向
+// （loop-gate → text-primitives ← workflow-hook）。
+import {
+	extractToolErrorText,
+	STEER_ERROR_MAX_CHARS,
+	truncateText,
+} from "./text-primitives.js";
+
+import { isToolExecutionEndEvent, isTurnEndEvent, tryParseJson } from "./schema-guards.js";
+import { isObjectRootSchema } from "./execute.js";
 
 /** Pi Extension API — properly typed via ExtensionAPI from pi-coding-agent SDK */
 type PiAPI = ExtensionAPI;
@@ -27,14 +37,26 @@ const MAX_HOOK_RETRIES = 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 逐点一致）
+ *     （仅当「判定要 steer 且发送成功」时调用——守卫链 toolUse/error/aborted/超上限/
+ *      成功短路/发送失败均不调，故 toolUse 保留 soCallCount、超上限保留
+ *      lastSchemaError，与旧 4-closure 逐点一致）
+ *
+ * terminal 态（D3/U2）：由 loop-gate 在同签名失败达 3 次时经 markTerminal() 置位，
+ * turn_end hook 据此不再 steer——防御性保留：shutdown 正常生效时进程已终止，
+ * 此分支是 shutdown 失败路径下的保险。terminal 不影响 onToolExecEnd 记录
+ * （闸门自身幂等，重复事件无害）。
  */
 export class RetryState {
 	soCallCount = 0;
 	soSucceededEver = false;
 	hookRetryCount = 0;
 	lastSchemaError: string | null = null;
+	terminal = false;
+
+	/** 闸门 terminal 置位（loop-gate 经 index.ts 回调调用；不可逆，仅 reset() 可清）。 */
+	markTerminal(): void {
+		this.terminal = true;
+	}
 
 	/** 记录一次 structured-output tool 执行结果。hasError = event.isError === true。 */
 	onToolExecEnd(hasError: boolean, errorMsg?: string): { shouldSteer: boolean } {
@@ -54,45 +76,127 @@ export class RetryState {
 		this.lastSchemaError = null;
 	}
 
-	/** 四字段归零（当前无调用方；保留作状态机完整契约）。 */
+	/** 五字段归零（当前无调用方；保留作状态机完整契约——含 U2 新增 terminal 态）。 */
 	reset(): void {
 		this.soCallCount = 0;
 		this.soSucceededEver = false;
 		this.hookRetryCount = 0;
 		this.lastSchemaError = null;
+		this.terminal = false;
+	}
+}
+
+/** steer 发送失败告警的 appendEntry customType（session JSONL 持久化，不进 LLM 上下文）。 */
+export const HOOK_ENTRY_TYPE = "structured-output:hook";
+
+/**
+ * steer 发送失败告警（审查项#8 失败路径）：双通道落盘（同 loop-gate writeTerminatedLog
+ * 惯例）——stderr 直出 + appendEntry 持久化。预算未扣减由「不调 onTurnEnd」结构保证，
+ * 下一个正常收尾的轮仍会重试 steer，不产生静默哑火。
+ */
+function writeSteerFailedLog(pi: PiAPI, hookRetryCount: number, err: unknown): void {
+	const message = err instanceof Error ? err.message : String(err);
+	process.stderr.write(
+		`[structured-output hook] steer send failed (retry budget NOT consumed, will retry at next turn end): ${message}\n`,
+	);
+	try {
+		pi.appendEntry(HOOK_ENTRY_TYPE, {
+			event: "steer_send_failed",
+			hookRetryCount,
+			error: message,
+			guidance:
+				"The steering message could not be delivered (e.g. compaction in progress or extension deactivated); the retry budget was preserved and the hook will retry at the next turn end.",
+		});
+	} catch (appendErr) {
+		// appendEntry 失败不阻断 hook——stderr 通道已落，此处补诊断（同 cache-probe 惯例）
+		process.stderr.write(
+			`[structured-output hook] appendEntry failed: ${appendErr instanceof Error ? appendErr.message : String(appendErr)}\n`,
+		);
 	}
 }
 
 /**
- * 从 tool 执行结果里提取错误文本。
+ * steer 守卫链（原 turn_end handler 内联守卫提取，判定顺序与旧实现逐条一致）。
+ * 命中任一守卫即跳过 steer，且调用方不调 onTurnEnd（toolUse/error/aborted 保留
+ * soCallCount、超上限保留 lastSchemaError，与旧 4-closure 逐点一致）：
+ *   0. 闸门 terminal（D3/U2）：同签名失败已满 3 次、shutdown 已发——不再 steer，
+ *      让进程终止（防御性保留：shutdown 正常生效时进程已死，到不了这里）
+ *   1. 已经成功调用过 structured-output，不再干预
+ *   2. 不是合法 turn_end 事件
+ *   3. stopReason="toolUse" → 模型还在调工具链，不需要干预
+ *   4. stopReason="error"/"aborted"（审查项#9）/"deferred"（F4：pi-ai StopReason
+ *      枚举成员，types.d.ts:275——provider 延迟响应挂起，本轮没有可消费 steer 的
+ *      收尾点）→ 本轮异常/未收尾终止：此刻注入的 steer 在本轮不会被消费，
+ *      chatMode 复用子进程时会泄漏成下一轮的陈旧指令——不发送
+ *   5. 超过重试上限：放弃，让子进程自然结束（调用方据 result.error 判定失败）
+ */
+function shouldSkipSteer(state: RetryState, event: unknown): boolean {
+	if (state.terminal) return true;
+	if (state.soSucceededEver) return true;
+	if (!isTurnEndEvent(event)) return true;
+	const stopReason = event.message?.stopReason;
+	if (stopReason === "toolUse") return true;
+	if (stopReason === "error" || stopReason === "aborted" || stopReason === "deferred") return true;
+	return state.hookRetryCount >= MAX_HOOK_RETRIES;
+}
+
+/**
+ * 构造 steer reminder（原 turn_end handler 内联三元提取）。两种失败形态：
+ *   - calledButFailed（调了但全是 isError）→ 注入具体校验错误 + 正确 schema
+ *   - 否则（完全没调用）→ 注入"必须调用"提示 + schema 形状；文案按参数层实际契约
+ *     （根类型）条件化：object 根 arguments 即 data；非 object 根参数层实际是 {value}
+ *     包装（P6）——固定 "arguments ARE the data" 会指导模型直传裸值，必被包装层
+ *     required:["value"] 拒绝，系统性浪费重试预算。判定与包装判定同源
+ *     （isObjectRootSchema），与工具 description / ASP 同语汇。
  *
- * Pi 框架在 tool execute 抛错时，构造 `{ content: [{ type: "text", text }] }`
- * 塞进 result.content[0].text（见 extensions/universal/unified-hooks 的 extractErrorText 及其
- * 文档：SDK 事件结构里没有独立 errorMessage 字段，错误文本只能从 result.content 里取）。
- * 这里防御性取多种结构，取不到就返回 undefined（调用方降级为通用提示）。
+ * 错误块经 truncateText 截断（审查项#1，上限 = STEER_ERROR_MAX_CHARS，与 loop-gate
+ * 签名上限语义独立——见 F5 拆分）：pi-ai validation.js 的实参回显无截断，
+ * 大 payload 失败时原始错误 ≈11K chars。如实口径：截断保留首部 = 错误类型 +
+ * 靠前的字段名，列表靠后的字段名可能被截掉；完整 schema 形状由 reminder 内
+ * schemaJson 全文另行完整携带，模型修正不依赖错误块的截断尾部。
  */
-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;
+function buildSteerReminder(
+	calledButFailed: boolean,
+	lastSchemaError: string | null,
+	schemaJson: string,
+	isObjectRoot: boolean,
+): string {
+	if (calledButFailed) {
+		return [
+			"[MANDATORY] Your structured-output call FAILED validation:",
+			truncateText(lastSchemaError ?? "structured-output call failed", STEER_ERROR_MAX_CHARS),
+			"",
+			"The schema is enforced by the system (PI_WORKFLOW_SCHEMA) — this tool's parameter schema IS the required shape of your result.",
+			`The required schema for your result is: ${schemaJson}`,
+			"Fix your arguments to conform to this schema and call the structured-output tool AGAIN.",
+			"Do NOT output the result as text — call the tool.",
+		].join("\n");
 	}
-	return undefined;
+	return isObjectRoot
+		? [
+				"[MANDATORY] You MUST call the structured-output tool now.",
+				"Your task requires a structured output. Do NOT respond with plain text.",
+				`Your arguments ARE the data — call structured-output with your result as the tool's arguments, matching this shape: ${schemaJson}`,
+				"The schema is enforced by the system; your arguments are validated against the authoritative schema automatically.",
+				"This is enforced by the workflow system. Just 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.",
+				`Call structured-output with a single argument \`{value: <data>}\` — put the result itself in \`value\`, and it must conform to this shape: ${schemaJson}`,
+				"Non-object schemas are wrapped in a `value` field because tool call arguments must be objects.",
+				"Validation errors may reference paths starting with `value.` (e.g. `value.0`, `value.name`): that prefix addresses the wrapper, not your data — strip it to locate the offending field.",
+				"The schema is enforced by the system; the `value` field is validated against the authoritative schema automatically.",
+				"This is enforced by the workflow system. Just call the tool.",
+			].join("\n");
 }
 
 /**
  * 注册 turn_end hook，检查模型是否成功调用 structured-output 工具。
  * 未成功时通过 pi.sendUserMessage({deliverAs:"steer"}) 注入 steering message 重试。
+ * 最多重试 MAX_HOOK_RETRIES 次，防止无限循环。
+ *
+ * @returns 共享的 RetryState（U2：index.ts 拿它接线 loop-gate 的 onTerminal 回调）。
  *
  * 两种失败形态都会触发 steer：
  * 1. 完全没调用（soCallCount === 0）→ 注入"必须调用"提示 + 正确 schema
@@ -104,9 +208,14 @@ function extractToolErrorText(result: unknown): string | undefined {
  * 检测时序：Pi 保证同 turn 内所有 tool_execution_end 都在 turn_end 之前触发，
  * 故 turn_end 读取的状态已反映本 turn 全部 tool 调用结果。
  */
-export function setupWorkflowHook(pi: PiAPI, schemaJson: string): void {
+export function setupWorkflowHook(pi: PiAPI, schemaJson: string): RetryState {
 	const state = new RetryState();
 
+	// 根类型判定与 {value} 包装判定同源（isObjectRootSchema，P6）：注册期
+	// createWorkflowToolDefinition 已对同一 schema 完成 assertJsonSchemaRoot fail-fast，
+	// 此处解析失败不可能到达；真失败时判定为非 object 根 → 包装契约文案（保守方向）。
+	const isObjectRoot = isObjectRootSchema(tryParseJson(schemaJson));
+
 	// 追踪 structured-output 调用结果：
 	// 成功 → soSucceededEver=true（终态，后续不再干预）
 	// 失败 → soCallCount++，记录 lastSchemaError，由 turn_end 决定是否 steer 重试
@@ -120,41 +229,32 @@ export function setupWorkflowHook(pi: PiAPI, schemaJson: string): void {
 	});
 
 	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;
+		// 守卫链（判定明细见 shouldSkipSteer 注释）：命中即直接 return，不调
+		// onTurnEnd——预算不扣减，状态保留到下一个正常收尾的轮再判定 steer。
+		if (shouldSkipSteer(state, event)) 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 状态归零）
+		// 故 onTurnEnd()（清空 lastSchemaError）必须在发送成功之后调用。
+		const reminder = buildSteerReminder(calledButFailed, state.lastSchemaError, schemaJson, isObjectRoot);
+
+		// 审查项#8：await 发送结果——发送失败（如 compaction 中 prompt() 抛错 / 扩展已
+		// 被 assertActive 拒绝）不扣减重试预算（不调 onTurnEnd），否则 fire-and-forget
+		// 丢一份 steer + 白扣一次预算，两次即永久哑火。
+		// pi 0.84.1 实装（loader.js）：extension 侧 sendUserMessage 同步转发且吞掉异步
+		// rejection（转 emitError）返回 void——await 对 undefined 立即解析；此处的
+		// try/catch 兜住同步 throw（assertActive）与未来 pi 返回真 Promise 的形态。
+		try {
+			await pi.sendUserMessage(reminder, { deliverAs: "steer" });
+		} catch (err) {
+			writeSteerFailedLog(pi, state.hookRetryCount, err);
+			return;
+		}
+		// 发送成功才按本 turn 重置计数、累计重试次数、清空 lastSchemaError
 		state.onTurnEnd();
-		pi.sendUserMessage(reminder, { deliverAs: "steer" });
 	});
+
+	// U2：暴露共享状态——index.ts 接线 loop-gate 的 onTerminal 回调（markTerminal）
+	return state;
 }