From e571bf964a6c1dfe6eb84b540da82642ff6af66e Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Tue, 30 Jun 2026 22:09:50 +0000
Subject: [PATCH 1/6] fix(agent): rejected stale yield labels

- Rejected unknown incremental yield labels when the active output schema is closed, so caller override schemas fail in-tool with retry feedback instead of post-mortem schema_violation.\n- Added regression coverage for reviewer-native labels under a caller override schema.\n\nFixes #3926
---
 packages/coding-agent/CHANGELOG.md            |  4 ++
 .../src/tools/output-schema-validator.ts      | 12 +++---
 packages/coding-agent/src/tools/yield.ts      | 27 +++++++++++---
 .../coding-agent/test/tools/yield.test.ts     | 37 +++++++++++++++++--
 4 files changed, 65 insertions(+), 15 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 8690c9aeb..a20807ec1 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed eval `agent()` subagents with caller-provided output schemas receiving stale native incremental `yield` labels by rejecting unknown labels for closed schemas with retry feedback naming the valid labels. ([#3926](https://github.com/can1357/oh-my-pi/issues/3926))
+
 ## [16.2.9] - 2026-06-30
 
 ### Breaking Changes
diff --git a/packages/coding-agent/src/tools/output-schema-validator.ts b/packages/coding-agent/src/tools/output-schema-validator.ts
index 21edc37e2..a08208d19 100644
--- a/packages/coding-agent/src/tools/output-schema-validator.ts
+++ b/packages/coding-agent/src/tools/output-schema-validator.ts
@@ -25,12 +25,11 @@ export interface OutputValidator {
 	 * Per-label validators for incremental yields (`type: ["<label>"]`). Each entry validates the
 	 * `data` payload of a single section against the matching top-level property's sub-schema —
 	 * array-typed properties (e.g. `findings`) use the items schema since each yield contributes
-	 * one element, while scalar properties use the property schema directly. Unknown labels (not
-	 * top-level properties) have no entry and skip per-call validation. Lets the yield tool give
-	 * the model retry feedback on a section as soon as it arrives, instead of deferring every
-	 * mismatch to the parent's post-mortem `schema_violation`.
+	 * one element, while scalar properties use the property schema directly.
 	 */
 	readonly validateSection: ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult>;
+	/** Whether top-level schema closure makes unknown incremental yield labels invalid. */
+	readonly rejectUnknownSections: boolean;
 }
 
 export interface BuildOutputValidatorResult {
@@ -83,6 +82,7 @@ export function buildOutputValidator(schema: unknown): BuildOutputValidatorResul
 			requiredFields: required,
 			validate: value => validateJsonSchemaValue(jsonSchemaRecord, value),
 			validateSection: buildSectionValidators(jsonSchemaRecord),
+			rejectUnknownSections: jsonSchemaRecord.additionalProperties === false,
 		},
 	};
 }
@@ -93,8 +93,8 @@ export function buildOutputValidator(schema: unknown): BuildOutputValidatorResul
  * Each entry validates the `data` payload of one `type: ["<label>"]` section against the
  * matching property's sub-schema — array-typed properties (e.g. `findings`, derived from JTD
  * `elements`) use the items schema since each yield contributes one element, while scalar
- * properties use the property schema directly. Unknown labels (anything not declared as a
- * top-level property) are deliberately omitted so user-defined section labels still pass.
+ * properties use the property schema directly. Closed top-level schemas reject labels that are
+ * not declared as properties.
  */
 function buildSectionValidators(
 	jsonSchema: Record<string, unknown>,
diff --git a/packages/coding-agent/src/tools/yield.ts b/packages/coding-agent/src/tools/yield.ts
index be5559b56..75743482d 100644
--- a/packages/coding-agent/src/tools/yield.ts
+++ b/packages/coding-agent/src/tools/yield.ts
@@ -213,11 +213,13 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 
 	readonly #validate?: (value: unknown) => JsonSchemaValidationResult;
 	readonly #validateSection?: ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult>;
+	#rejectUnknownSections = false;
 	#schemaValidationFailures = 0;
 
 	constructor(session: ToolSession) {
 		let validate: ((value: unknown) => JsonSchemaValidationResult) | undefined;
 		let validateSection: ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult> | undefined;
+		let rejectUnknownSections = false;
 		let parameters: TSchema;
 
 		try {
@@ -230,6 +232,7 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 			if (validator) {
 				validate = value => validator.validate(value);
 				validateSection = validator.validateSection;
+				rejectUnknownSections = validator.rejectUnknownSections;
 			}
 
 			const schemaHint = formatSchema(normalizedSchema ?? session.outputSchema);
@@ -280,6 +283,7 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 
 		this.#validate = validate;
 		this.#validateSection = validateSection;
+		this.#rejectUnknownSections = rejectUnknownSections;
 		this.parameters = parameters;
 	}
 
@@ -364,15 +368,26 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 
 	/**
 	 * Validate the `data` payload of an incremental yield (`type: ["<label>", …]`) against
-	 * the matching property's sub-validator. Returns the first failure across all known labels,
-	 * or `undefined` when no label is recognised (user-defined section labels stay loose) or
-	 * when all known labels accept the value. Lets the model see the same retry feedback that
-	 * the terminal-yield path already produces, instead of leaking the mismatch through to
-	 * the parent's post-mortem `schema_violation`.
+	 * the matching property's sub-validator. Closed schemas also reject unknown labels so stale
+	 * agent-native prompt sections receive retry feedback before parent-side finalization.
 	 */
 	#validateIncrementalSection(labels: string[], data: unknown): JsonSchemaValidationResult | undefined {
 		const subValidators = this.#validateSection;
-		if (!subValidators || subValidators.size === 0) return undefined;
+		if (!subValidators) return undefined;
+		const unknownLabels = labels.filter(label => !subValidators.has(label));
+		if (this.#rejectUnknownSections && unknownLabels.length > 0) {
+			const validLabels = subValidators.size > 0 ? formatYieldLabels([...subValidators.keys()]) : "none";
+			return {
+				success: false,
+				issues: [
+					{
+						path: ["type"],
+						message: `unknown incremental yield label(s): ${formatYieldLabels(unknownLabels)}; valid labels: ${validLabels}`,
+						keyword: "enum",
+					},
+				],
+			};
+		}
 		for (const label of labels) {
 			const sub = subValidators.get(label);
 			if (!sub) continue;
diff --git a/packages/coding-agent/test/tools/yield.test.ts b/packages/coding-agent/test/tools/yield.test.ts
index b05640ea1..1f1b73507 100644
--- a/packages/coding-agent/test/tools/yield.test.ts
+++ b/packages/coding-agent/test/tools/yield.test.ts
@@ -225,12 +225,13 @@ describe("YieldTool", () => {
 	});
 
 	it("leaves user-defined section labels unconstrained", async () => {
-		// Labels that are not top-level properties in the output schema have no per-call
-		// validator — they're scratchpad/streaming sections the agent invents at runtime and
-		// must not be rejected.
+		// Open JSON Schema output contracts can still use scratchpad/streaming
+		// sections that the agent invents at runtime, so unknown labels stay loose.
 		const tool = new YieldTool(
 			createSession({
 				outputSchema: {
+					type: "object",
+					additionalProperties: true,
 					properties: {
 						overall_correctness: { enum: ["correct", "incorrect"] },
 						explanation: { type: "string" },
@@ -246,6 +247,36 @@ describe("YieldTool", () => {
 		expect(result.details?.data).toEqual({ anything: "goes", n: 3 });
 	});
 
+	it("rejects unknown incremental labels for closed caller output schemas", async () => {
+		const tool = new YieldTool(
+			createSession({
+				outputSchema: {
+					properties: {
+						issue_key: { type: "string" },
+						verdict: { enum: ["clean", "blockers"] },
+					},
+					optionalProperties: {
+						blockers: {
+							elements: { properties: { title: { type: "string" } } },
+						},
+						non_blocking_notes: {
+							elements: { type: "string" },
+						},
+					},
+				},
+			}),
+		);
+
+		await expect(
+			tool.execute("call-native-reviewer-label", {
+				type: ["findings"],
+				result: { data: { title: "native reviewer finding" } },
+			} as never),
+		).rejects.toThrow(
+			/Section "findings" does not match schema: type: unknown incremental yield label\(s\): "findings"; valid labels: "issue_key", "verdict", "blockers", "non_blocking_notes"/,
+		);
+	});
+
 	it("rejects missing success data unless a yield type requests last-turn mode", async () => {
 		const tool = new YieldTool(createSession());
 		await expect(tool.execute("call-untyped-empty", { result: {} } as never)).rejects.toThrow(

From ef9c5ab5215337497a3ed1c6d53175808e15563d Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Tue, 30 Jun 2026 22:15:36 +0000
Subject: [PATCH 2/6] fix(agent): hard-failed unknown yield labels

- Made unknown incremental yield labels under a closed caller schema throw on every call without consuming MAX_SCHEMA_RETRIES, so the post-mortem override no longer accepts the stale-label payload.\n- Strengthened the regression test to assert the hard failure repeats and the schema-retry budget stays intact for legitimate shape mismatches.\n\nRefs #3926
---
 packages/coding-agent/src/tools/yield.ts      | 51 ++++++++++++-------
 .../coding-agent/test/tools/yield.test.ts     | 30 ++++++++---
 2 files changed, 57 insertions(+), 24 deletions(-)

diff --git a/packages/coding-agent/src/tools/yield.ts b/packages/coding-agent/src/tools/yield.ts
index 75743482d..f03b0dc7f 100644
--- a/packages/coding-agent/src/tools/yield.ts
+++ b/packages/coding-agent/src/tools/yield.ts
@@ -325,6 +325,22 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 			if (data === null) {
 				throw new Error("data is required when yield indicates success");
 			}
+			// Unknown incremental labels are a hard contract mismatch with the closed
+			// caller schema, not a shape error a retry can fix. Reject them every time
+			// without touching the schema-retry counter so the override path never
+			// accepts a stale agent-native section name.
+			if (isIncremental) {
+				const unknownLabels = this.#unknownIncrementalLabels(yieldType as string[]);
+				if (unknownLabels.length > 0) {
+					const validLabels =
+						this.#validateSection && this.#validateSection.size > 0
+							? formatYieldLabels([...this.#validateSection.keys()])
+							: "none";
+					throw new Error(
+						`Section ${formatYieldLabels(yieldType as string[])} uses unknown incremental yield label(s): ${formatYieldLabels(unknownLabels)}. Resubmit with one of the schema's labels: ${validLabels}.`,
+					);
+				}
+			}
 			const sectionFailure = isIncremental
 				? this.#validateIncrementalSection(yieldType as string[], data)
 				: this.#validate
@@ -366,28 +382,29 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 		};
 	}
 
+	/**
+	 * Return incremental yield labels that are not declared as top-level properties of a closed
+	 * caller schema. Open schemas (no `additionalProperties: false`) accept any label.
+	 */
+	#unknownIncrementalLabels(labels: string[]): string[] {
+		if (!this.#rejectUnknownSections) return [];
+		const subValidators = this.#validateSection;
+		if (!subValidators) return [];
+		return labels.filter(label => !subValidators.has(label));
+	}
+
 	/**
 	 * Validate the `data` payload of an incremental yield (`type: ["<label>", …]`) against
-	 * the matching property's sub-validator. Closed schemas also reject unknown labels so stale
-	 * agent-native prompt sections receive retry feedback before parent-side finalization.
+	 * the matching property's sub-validator. Returns the first failure across all known labels,
+	 * or `undefined` when no label is recognised (user-defined section labels stay loose) or
+	 * when all known labels accept the value. Lets the model see the same retry feedback that
+	 * the terminal-yield path already produces, instead of leaking the mismatch through to
+	 * the parent's post-mortem `schema_violation`. Unknown labels under a closed schema are
+	 * handled separately by `#unknownIncrementalLabels` and never reach this validator.
 	 */
 	#validateIncrementalSection(labels: string[], data: unknown): JsonSchemaValidationResult | undefined {
 		const subValidators = this.#validateSection;
-		if (!subValidators) return undefined;
-		const unknownLabels = labels.filter(label => !subValidators.has(label));
-		if (this.#rejectUnknownSections && unknownLabels.length > 0) {
-			const validLabels = subValidators.size > 0 ? formatYieldLabels([...subValidators.keys()]) : "none";
-			return {
-				success: false,
-				issues: [
-					{
-						path: ["type"],
-						message: `unknown incremental yield label(s): ${formatYieldLabels(unknownLabels)}; valid labels: ${validLabels}`,
-						keyword: "enum",
-					},
-				],
-			};
-		}
+		if (!subValidators || subValidators.size === 0) return undefined;
 		for (const label of labels) {
 			const sub = subValidators.get(label);
 			if (!sub) continue;
diff --git a/packages/coding-agent/test/tools/yield.test.ts b/packages/coding-agent/test/tools/yield.test.ts
index 1f1b73507..6363af92b 100644
--- a/packages/coding-agent/test/tools/yield.test.ts
+++ b/packages/coding-agent/test/tools/yield.test.ts
@@ -247,7 +247,7 @@ describe("YieldTool", () => {
 		expect(result.details?.data).toEqual({ anything: "goes", n: 3 });
 	});
 
-	it("rejects unknown incremental labels for closed caller output schemas", async () => {
+	it("rejects unknown incremental labels for closed caller output schemas without consuming retries", async () => {
 		const tool = new YieldTool(
 			createSession({
 				outputSchema: {
@@ -267,14 +267,30 @@ describe("YieldTool", () => {
 			}),
 		);
 
+		// Unknown labels are a hard contract mismatch with the caller schema. They MUST
+		// reject every time with the schema's labels listed and never bump the retry
+		// counter — otherwise the MAX_SCHEMA_RETRIES override accepts the stale-label
+		// payload and the post-mortem finalizer takes it as success (issue #3927 review).
+		for (let attempt = 1; attempt <= 5; attempt++) {
+			await expect(
+				tool.execute(`call-native-reviewer-label-${attempt}`, {
+					type: ["findings"],
+					result: { data: { title: "native reviewer finding" } },
+				} as never),
+			).rejects.toThrow(
+				/Section "findings" uses unknown incremental yield label\(s\): "findings"\. Resubmit with one of the schema's labels: "issue_key", "verdict", "blockers", "non_blocking_notes"\./,
+			);
+		}
+
+		// Schema-retry budget intact: a separate, shape-only mismatch still fires the
+		// first-attempt retry hint (`2 retry attempt(s) remain`), proving the unknown-label
+		// path didn't burn the override.
 		await expect(
-			tool.execute("call-native-reviewer-label", {
-				type: ["findings"],
-				result: { data: { title: "native reviewer finding" } },
+			tool.execute("call-shape-error", {
+				type: ["verdict"],
+				result: { data: "approved" },
 			} as never),
-		).rejects.toThrow(
-			/Section "findings" does not match schema: type: unknown incremental yield label\(s\): "findings"; valid labels: "issue_key", "verdict", "blockers", "non_blocking_notes"/,
-		);
+		).rejects.toThrow(/Section "verdict" does not match schema.*2 retry attempt\(s\) remain/);
 	});
 
 	it("rejects missing success data unless a yield type requests last-turn mode", async () => {

From ca3acaa61a28811eab7e5adc9615b980d1c175c0 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Tue, 30 Jun 2026 22:20:09 +0000
Subject: [PATCH 3/6] fix(agent): blocked stale labels in last-turn yields

- Lifted the unknown-incremental-label check above the !useLastTurn guard so type: [findings], result: {} also rejects, preventing a sibling section's MAX_SCHEMA_RETRIES override from sneaking the stale section through finalization.\n- Extended the regression test with the last-turn payload case.\n\nRefs #3926
---
 packages/coding-agent/src/tools/yield.ts      | 33 ++++++++++---------
 .../coding-agent/test/tools/yield.test.ts     | 13 ++++++++
 2 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/packages/coding-agent/src/tools/yield.ts b/packages/coding-agent/src/tools/yield.ts
index f03b0dc7f..8b8049fc7 100644
--- a/packages/coding-agent/src/tools/yield.ts
+++ b/packages/coding-agent/src/tools/yield.ts
@@ -321,26 +321,27 @@ export class YieldTool implements AgentTool<TSchema, YieldDetails> {
 
 		const status = errorMessage !== undefined ? "aborted" : "success";
 		let schemaValidationOverridden = false;
+		// Unknown incremental labels are a hard contract mismatch with the closed caller
+		// schema. Reject before the last-turn short-circuit too: `type: ["findings"], result: {}`
+		// would otherwise be accepted as a typed last-turn incremental yield, then a sibling
+		// section's MAX_SCHEMA_RETRIES override flips schemaOverridden in finalization and the
+		// stale section rides along untouched.
+		if (status === "success" && isIncremental) {
+			const unknownLabels = this.#unknownIncrementalLabels(yieldType as string[]);
+			if (unknownLabels.length > 0) {
+				const validLabels =
+					this.#validateSection && this.#validateSection.size > 0
+						? formatYieldLabels([...this.#validateSection.keys()])
+						: "none";
+				throw new Error(
+					`Section ${formatYieldLabels(yieldType as string[])} uses unknown incremental yield label(s): ${formatYieldLabels(unknownLabels)}. Resubmit with one of the schema's labels: ${validLabels}.`,
+				);
+			}
+		}
 		if (status === "success" && !useLastTurn) {
 			if (data === null) {
 				throw new Error("data is required when yield indicates success");
 			}
-			// Unknown incremental labels are a hard contract mismatch with the closed
-			// caller schema, not a shape error a retry can fix. Reject them every time
-			// without touching the schema-retry counter so the override path never
-			// accepts a stale agent-native section name.
-			if (isIncremental) {
-				const unknownLabels = this.#unknownIncrementalLabels(yieldType as string[]);
-				if (unknownLabels.length > 0) {
-					const validLabels =
-						this.#validateSection && this.#validateSection.size > 0
-							? formatYieldLabels([...this.#validateSection.keys()])
-							: "none";
-					throw new Error(
-						`Section ${formatYieldLabels(yieldType as string[])} uses unknown incremental yield label(s): ${formatYieldLabels(unknownLabels)}. Resubmit with one of the schema's labels: ${validLabels}.`,
-					);
-				}
-			}
 			const sectionFailure = isIncremental
 				? this.#validateIncrementalSection(yieldType as string[], data)
 				: this.#validate
diff --git a/packages/coding-agent/test/tools/yield.test.ts b/packages/coding-agent/test/tools/yield.test.ts
index 6363af92b..653bf96b0 100644
--- a/packages/coding-agent/test/tools/yield.test.ts
+++ b/packages/coding-agent/test/tools/yield.test.ts
@@ -282,6 +282,19 @@ describe("YieldTool", () => {
 			);
 		}
 
+		// The last-turn short-circuit (`type: ["findings"], result: {}`) MUST also reject
+		// the unknown label. Otherwise the stale section silently accepts the last assistant
+		// text and rides along when a sibling section trips MAX_SCHEMA_RETRIES and
+		// schemaOverridden in finalization (issue #3927 follow-up review).
+		await expect(
+			tool.execute("call-native-reviewer-label-last-turn", {
+				type: ["findings"],
+				result: {},
+			} as never),
+		).rejects.toThrow(
+			/Section "findings" uses unknown incremental yield label\(s\): "findings"\. Resubmit with one of the schema's labels: "issue_key", "verdict", "blockers", "non_blocking_notes"\./,
+		);
+
 		// Schema-retry budget intact: a separate, shape-only mismatch still fires the
 		// first-attempt retry hint (`2 retry attempt(s) remain`), proving the unknown-label
 		// path didn't burn the override.

From 00ef58f843052bb02e5d608e20e41a55fc3ed3e7 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Tue, 30 Jun 2026 22:30:15 +0000
Subject: [PATCH 4/6] fix(agent): steered override-schema subagents

- Marked eval agent schema calls as caller overrides so subagent prompts can revoke native output/yield instructions.\n- Added override-schema prompt guidance telling agents to ignore conflicting native output labels and terminal-yield the caller schema object.\n- Added prompt coverage for the override notice.\n\nRefs #3926
---
 .../src/eval/__tests__/agent-bridge.test.ts   |  2 ++
 .../coding-agent/src/eval/agent-bridge.ts     |  1 +
 .../prompts/system/subagent-system-prompt.md  |  4 ++++
 packages/coding-agent/src/task/executor.ts    |  6 +++++
 .../test/task/subagent-system-prompt.test.ts  | 23 +++++++++++++++++++
 5 files changed, 36 insertions(+)
 create mode 100644 packages/coding-agent/test/task/subagent-system-prompt.test.ts

diff --git a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
index 30c4678c1..3db8b33b1 100644
--- a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
+++ b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
@@ -235,10 +235,12 @@ describe("runEvalAgent", () => {
 		expect(firstOptions.signal).toBe(abortController.signal);
 		expect(firstOptions.parentActiveModelPattern).toBe("p/current");
 		expect(firstOptions.outputSchema).toBe(schema);
+		expect(firstOptions.outputSchemaOverridesAgent).toBe(true);
 		expect(firstOptions.assignment).toBe("hello");
 		expect(firstOptions.description).toBe("My Agent");
 		expect(firstOptions.modelOverride).toEqual(["p/override"]);
 		expect(secondOptions.outputSchema).toBeUndefined();
+		expect(secondOptions.outputSchemaOverridesAgent).toBeUndefined();
 	});
 
 	it("forces LSP off for bridge subagents even when task.enableLsp is on", async () => {
diff --git a/packages/coding-agent/src/eval/agent-bridge.ts b/packages/coding-agent/src/eval/agent-bridge.ts
index 301709281..b27068b69 100644
--- a/packages/coding-agent/src/eval/agent-bridge.ts
+++ b/packages/coding-agent/src/eval/agent-bridge.ts
@@ -371,6 +371,7 @@ export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOption
 		parentActiveModelPattern,
 		thinkingLevel: effectiveAgent.thinkingLevel,
 		outputSchema: structured ? parsed.schema : undefined,
+		outputSchemaOverridesAgent: structured,
 		sessionFile,
 		persistArtifacts: Boolean(sessionFile),
 		artifactsDir,
diff --git a/packages/coding-agent/src/prompts/system/subagent-system-prompt.md b/packages/coding-agent/src/prompts/system/subagent-system-prompt.md
index daebdad7b..295f0b29c 100644
--- a/packages/coding-agent/src/prompts/system/subagent-system-prompt.md
+++ b/packages/coding-agent/src/prompts/system/subagent-system-prompt.md
@@ -61,6 +61,10 @@ Yield protocol:
 
 This is your only way to return a final result. For structured results, you NEVER put JSON in plain text or substitute a text summary for `result.data`.
 
+{{#if outputSchemaOverridesAgent}}
+Caller schema overrides agent-native output instructions. Ignore ROLE-provided output/yield labels, field names, examples, and procedures that conflict with the interface below. Use ONLY labels/fields from the caller schema; safest path: omit `type` and terminal-yield the full `result.data` object.
+
+{{/if}}
 {{#if outputSchema}}
 Your result MUST match this TypeScript interface:
 ```ts
diff --git a/packages/coding-agent/src/task/executor.ts b/packages/coding-agent/src/task/executor.ts
index d0f718f00..d4cd31d0d 100644
--- a/packages/coding-agent/src/task/executor.ts
+++ b/packages/coding-agent/src/task/executor.ts
@@ -295,6 +295,11 @@ export interface ExecutorOptions {
 	parentActiveModelPattern?: string;
 	thinkingLevel?: ThinkingLevel;
 	outputSchema?: unknown;
+	/**
+	 * Caller supplied a schema that supersedes the agent's native output prompt.
+	 * Eval `agent(..., schema=...)` sets this so built-in agents ignore stale yield labels.
+	 */
+	outputSchemaOverridesAgent?: boolean;
 	/** Parent task recursion depth (0 = top-level, 1 = first child, etc.) */
 	taskDepth?: number;
 	/**
@@ -2141,6 +2146,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 						planReferencePath: options.planReference?.path ?? "",
 						worktree: worktree ?? "",
 						outputSchema: normalizedOutputSchema,
+						outputSchemaOverridesAgent: options.outputSchemaOverridesAgent === true,
 						ircPeers: ircEnabled ? renderIrcPeerRoster(id) : "",
 						ircSelfId: ircEnabled ? id : "",
 					});
diff --git a/packages/coding-agent/test/task/subagent-system-prompt.test.ts b/packages/coding-agent/test/task/subagent-system-prompt.test.ts
new file mode 100644
index 000000000..47bf37b18
--- /dev/null
+++ b/packages/coding-agent/test/task/subagent-system-prompt.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from "bun:test";
+import { prompt } from "@oh-my-pi/pi-utils";
+import "../../src/config/prompt-templates";
+import subagentSystemPromptTemplate from "../../src/prompts/system/subagent-system-prompt.md" with { type: "text" };
+
+describe("subagent system prompt", () => {
+	it("revokes native output labels when caller schema overrides the agent", () => {
+		const out = prompt.render(subagentSystemPromptTemplate, {
+			agent: 'Use incremental yield with type: ["findings"].',
+			outputSchemaOverridesAgent: true,
+			outputSchema: {
+				properties: {
+					issue_key: { type: "string" },
+					verdict: { enum: ["clean", "blockers"] },
+				},
+			},
+		});
+
+		expect(out).toContain("Caller schema overrides agent-native output instructions");
+		expect(out).toContain("Ignore ROLE-provided output/yield labels");
+		expect(out).toContain("omit `type` and terminal-yield the full `result.data` object");
+	});
+});

From 418e300b40ae11dabe45e8b811b9df185e50065c Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Tue, 30 Jun 2026 22:30:25 +0000
Subject: [PATCH 5/6] style: bun run fix

---
 .../coding-agent/src/prompts/system/subagent-system-prompt.md    | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/coding-agent/src/prompts/system/subagent-system-prompt.md b/packages/coding-agent/src/prompts/system/subagent-system-prompt.md
index 295f0b29c..722ff92e6 100644
--- a/packages/coding-agent/src/prompts/system/subagent-system-prompt.md
+++ b/packages/coding-agent/src/prompts/system/subagent-system-prompt.md
@@ -63,7 +63,6 @@ This is your only way to return a final result. For structured results, you NEVE
 
 {{#if outputSchemaOverridesAgent}}
 Caller schema overrides agent-native output instructions. Ignore ROLE-provided output/yield labels, field names, examples, and procedures that conflict with the interface below. Use ONLY labels/fields from the caller schema; safest path: omit `type` and terminal-yield the full `result.data` object.
-
 {{/if}}
 {{#if outputSchema}}
 Your result MUST match this TypeScript interface:

From 7ee0779fb3e0c0530d919bd0a3d072c1c1fcb2d6 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Tue, 30 Jun 2026 22:32:23 +0000
Subject: [PATCH 6/6] fix(agent): dereferenced root $ref for yield labels

- Resolved a root-level `$ref` before deriving the incremental-label map and the closed-schema flag, so caller schemas exported as `{$ref: '#/$defs/Closed', $defs: {...}}` reject unknown labels at the yield gate instead of leaking through to parent-side schema_violation.\n- Added a regression test using a top-level `$ref` into `$defs.Closed`.\n\nRefs #3926
---
 .../src/tools/output-schema-validator.ts      | 15 ++++++--
 .../coding-agent/test/tools/yield.test.ts     | 34 +++++++++++++++++++
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/packages/coding-agent/src/tools/output-schema-validator.ts b/packages/coding-agent/src/tools/output-schema-validator.ts
index a08208d19..2e8b9175c 100644
--- a/packages/coding-agent/src/tools/output-schema-validator.ts
+++ b/packages/coding-agent/src/tools/output-schema-validator.ts
@@ -8,6 +8,7 @@
  * cannot be rejected post-mortem (or vice versa).
  */
 import {
+	dereferenceJsonSchema,
 	isValidJsonSchema,
 	type JsonSchemaValidationIssue,
 	type JsonSchemaValidationResult,
@@ -75,14 +76,24 @@ export function buildOutputValidator(schema: unknown): BuildOutputValidatorResul
 
 	const jsonSchemaRecord = jsonSchema as Record<string, unknown>;
 	const required = extractRequiredFields(jsonSchemaRecord);
+	// Resolve a root `$ref` (e.g. caller schemas exported as `{ $ref: "#/$defs/Closed", $defs: ... }`)
+	// before deriving incremental-label metadata. AJV-style validation chases the ref at runtime, so
+	// `validate()` accepts the resolved object — but `properties` and `additionalProperties` live on
+	// the inlined node, not the wrapper. Without this, unknown labels slipped past the yield gate and
+	// only fired as parent-side schema_violations.
+	const dereferenced = dereferenceJsonSchema(jsonSchemaRecord);
+	const labelSchema =
+		dereferenced && typeof dereferenced === "object" && !Array.isArray(dereferenced)
+			? (dereferenced as Record<string, unknown>)
+			: jsonSchemaRecord;
 	return {
 		normalized,
 		jsonSchema: jsonSchemaRecord,
 		validator: {
 			requiredFields: required,
 			validate: value => validateJsonSchemaValue(jsonSchemaRecord, value),
-			validateSection: buildSectionValidators(jsonSchemaRecord),
-			rejectUnknownSections: jsonSchemaRecord.additionalProperties === false,
+			validateSection: buildSectionValidators(labelSchema),
+			rejectUnknownSections: labelSchema.additionalProperties === false,
 		},
 	};
 }
diff --git a/packages/coding-agent/test/tools/yield.test.ts b/packages/coding-agent/test/tools/yield.test.ts
index 653bf96b0..e1b80f3fb 100644
--- a/packages/coding-agent/test/tools/yield.test.ts
+++ b/packages/coding-agent/test/tools/yield.test.ts
@@ -306,6 +306,40 @@ describe("YieldTool", () => {
 		).rejects.toThrow(/Section "verdict" does not match schema.*2 retry attempt\(s\) remain/);
 	});
 
+	it("rejects unknown incremental labels when the closed caller schema is a root $ref into $defs", async () => {
+		// Caller schemas exported as `{ $ref: "#/$defs/Closed", $defs: { Closed: ... } }` MUST
+		// resolve the root ref before the yield tool derives the valid-label set and the
+		// closed-schema flag. Otherwise stale labels slip past the yield gate and only fail
+		// later as a parent-side schema_violation (#3927 follow-up review).
+		const tool = new YieldTool(
+			createSession({
+				outputSchema: {
+					$ref: "#/$defs/Closed",
+					$defs: {
+						Closed: {
+							type: "object",
+							properties: {
+								issue_key: { type: "string" },
+								verdict: { enum: ["clean", "blockers"] },
+							},
+							required: ["issue_key", "verdict"],
+							additionalProperties: false,
+						},
+					},
+				},
+			}),
+		);
+
+		await expect(
+			tool.execute("call-rooted-ref-stale-label", {
+				type: ["findings"],
+				result: { data: { title: "native reviewer finding" } },
+			} as never),
+		).rejects.toThrow(
+			/Section "findings" uses unknown incremental yield label\(s\): "findings"\. Resubmit with one of the schema's labels: "issue_key", "verdict"\./,
+		);
+	});
+
 	it("rejects missing success data unless a yield type requests last-turn mode", async () => {
 		const tool = new YieldTool(createSession());
 		await expect(tool.execute("call-untyped-empty", { result: {} } as never)).rejects.toThrow(