Add submit_result typed reporting channel for Tier 3 leaves

Mounts on leaf-tier workers only (existing authority.ts/tier gate).
DirectorPackage.reportContract.outputSchema is an optional JSON Schema;
an invalid submit_result payload returns a correction (non-terminal,
capped at 3 rounds) instead of failing the run. Requires a per-turn
token generated at dispatch and echoed back, rejecting stale/superseded
turns. Purely additive — the markdown report envelope path is untouched.

Author: TheGreatAxios

CHANGELOG.md

@@ -15,6 +15,10 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ### Agent
 
+- Tier 3 leaf workers can now report via `submit_result`, a typed channel alongside
+  the markdown envelope: a director package may declare a JSON Schema on
+  `DirectorPackage.reportContract.outputSchema`, and an invalid submission returns
+  a correction (capped at 3 rounds) instead of failing the run.
 - **Fleet authority tiers are now runtime-enforced, not documented in a prompt.**
   Every director package carries a required `tier` (`orchestrator` /
   `nested-orchestrator` / `leaf`): skywalker gets full fleet control, greybeard

src/agent/directors/types.ts

@@ -60,6 +60,18 @@ export interface NudgePolicy {
   readonly stallMs?: number;
 }
 
+/**
+ * Optional structured-output contract for a director's worker (CL-6946).
+ * Additive alongside the markdown envelope (Summary/Findings/Blockers/Paths,
+ * see subagent/report.ts) — declaring `outputSchema` lets a Tier 3 leaf also
+ * submit a JSON payload via `submit_result`, validated against this schema.
+ * Omit entirely to keep a director on the markdown-only path.
+ */
+export interface ReportContract {
+  /** JSON Schema (draft-07 subset, see subagent/json-schema-lite.ts) for submit_result's payload. */
+  readonly outputSchema?: Record<string, unknown>;
+}
+
 /**
  * One shipped director: hard primary intent + package fields.
  * Packages land in later levels; registry holds the closed set.
@@ -81,6 +93,8 @@ export interface DirectorPackage {
   readonly modelRole: ModelRole;
   /** Fleet authority tier — data on the package, gated at mount, not prose. */
   readonly tier: SubagentTier;
+  /** Optional typed output contract (CL-6946); Tier 3 leaves only. */
+  readonly reportContract?: ReportContract;
 }
 
 export interface ResolveDirectorInput {

src/subagent/json-schema-lite.ts

@@ -0,0 +1,105 @@
+/**
+ * Minimal JSON Schema (draft-07 subset) validator for submit_result payloads
+ * (CL-6946). No JSON-Schema validation library is in the dependency tree
+ * (arktype validates its own type language, not arbitrary JSON Schema
+ * documents) — this covers the subset director packages need to declare a
+ * structured output shape: type, required, properties, items, enum, and the
+ * common string/number bounds. Not a general-purpose validator.
+ */
+
+export type JsonSchema = Record<string, unknown>;
+
+function typeOf(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function matchesType(value: unknown, expected: string): boolean {
+  if (expected === "integer") return typeof value === "number" && Number.isInteger(value);
+  return typeOf(value) === expected;
+}
+
+/** Validate `value` against `schema`, returning human-readable error strings (empty = valid). */
+export function validateJsonSchema(schema: JsonSchema, value: unknown, path = "result"): string[] {
+  const errors: string[] = [];
+
+  const expectedType = schema.type;
+  if (typeof expectedType === "string" && !matchesType(value, expectedType)) {
+    errors.push(`${path}: expected type "${expectedType}", got "${typeOf(value)}"`);
+    return errors; // further checks are meaningless on the wrong type
+  }
+
+  const enumValues = schema.enum;
+  if (Array.isArray(enumValues) && !enumValues.some((v) => deepEqual(v, value))) {
+    errors.push(`${path}: value is not one of the allowed enum values`);
+  }
+
+  if (typeOf(value) === "object" && value !== null) {
+    const obj = value as Record<string, unknown>;
+    const required = schema.required;
+    if (Array.isArray(required)) {
+      for (const key of required) {
+        if (typeof key === "string" && !(key in obj)) {
+          errors.push(`${path}: missing required property "${key}"`);
+        }
+      }
+    }
+    const properties = schema.properties;
+    if (properties !== null && typeof properties === "object") {
+      for (const [key, subSchema] of Object.entries(properties as Record<string, unknown>)) {
+        if (key in obj && subSchema !== null && typeof subSchema === "object") {
+          errors.push(...validateJsonSchema(subSchema as JsonSchema, obj[key], `${path}.${key}`));
+        }
+      }
+    }
+    if (schema.additionalProperties === false) {
+      const allowed = new Set(
+        properties !== null && typeof properties === "object"
+          ? Object.keys(properties as Record<string, unknown>)
+          : [],
+      );
+      for (const key of Object.keys(obj)) {
+        if (!allowed.has(key)) {
+          errors.push(`${path}: unexpected property "${key}" (additionalProperties: false)`);
+        }
+      }
+    }
+  }
+
+  if (typeOf(value) === "array" && Array.isArray(value)) {
+    const items = schema.items;
+    if (items !== null && typeof items === "object") {
+      value.forEach((item, i) => {
+        errors.push(...validateJsonSchema(items as JsonSchema, item, `${path}[${i}]`));
+      });
+    }
+  }
+
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+      errors.push(`${path}: length ${value.length} is below minLength ${schema.minLength}`);
+    }
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+      errors.push(`${path}: length ${value.length} exceeds maxLength ${schema.maxLength}`);
+    }
+  }
+
+  if (typeof value === "number") {
+    if (typeof schema.minimum === "number" && value < schema.minimum) {
+      errors.push(`${path}: ${value} is below minimum ${schema.minimum}`);
+    }
+    if (typeof schema.maximum === "number" && value > schema.maximum) {
+      errors.push(`${path}: ${value} exceeds maximum ${schema.maximum}`);
+    }
+  }
+
+  return errors;
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object" || a === null || b === null) return false;
+  return JSON.stringify(a) === JSON.stringify(b);
+}

src/subagent/report.ts

@@ -47,6 +47,8 @@ export interface DispatchBrief {
   successCriteria?: readonly string[];
   doNot?: readonly string[];
   reportFocus?: string;
+  /** Turn token (CL-6946) a leaf must echo back to `submit_result`. Leaf-tier dispatches only. */
+  turnToken?: string;
 }
 
 export function buildDispatchBrief(brief: DispatchBrief): string {
@@ -85,6 +87,14 @@ export function buildDispatchBrief(brief: DispatchBrief): string {
     reportLines.push(`Focus Findings on: ${brief.reportFocus.trim()}`);
   }
   parts.push("", "## Report shape", ...reportLines);
+  if (brief.turnToken !== undefined && brief.turnToken.length > 0) {
+    parts.push(
+      "",
+      "## Turn token",
+      brief.turnToken,
+      `If you call submit_result, pass turn_token="${brief.turnToken}" exactly. A mismatched token means this turn was superseded — do not resubmit under it.`,
+    );
+  }
   return parts.join("\n");
 }
 

src/subagent/run.ts

@@ -23,7 +23,7 @@ import { type } from "arktype";
 import { createPosixTools } from "@intx/tools-posix";
 import { createDynamicToolRunner } from "../tui/dynamic-tool-runner.js";
 import type { ReactorEmittedEvent } from "@intx/inference";
-import type { BlobReader, InboundMessage } from "@intx/types/runtime";
+import type { BlobReader, InboundMessage, ToolDefinition } from "@intx/types/runtime";
 
 import { seedPricingMetadataFromCache } from "../cost/pricing-metadata.js";
 import { defaultPricingCachePath } from "../cost/pricing-fetcher.js";
@@ -105,6 +105,11 @@ import {
 } from "./stop-policy.js";
 import { SubAgentDirector } from "./nudge-director.js";
 import { assertTierMayMountFleetVerb } from "./authority.js";
+import {
+  createSubmitResultState,
+  evaluateSubmitResult,
+  SUBMIT_RESULT_MAX_CORRECTIONS,
+} from "./submit-result.js";
 import {
   abortError,
   createSubAgentSpawnRegistryPlugin,
@@ -295,6 +300,24 @@ export function shouldRequireEvidence(input: {
   return input.directorId === "critique";
 }
 
+const submitResultDefinition: ToolDefinition = {
+  name: "submit_result",
+  description:
+    "Submit your structured result for this turn. Requires the turn_token from your dispatch " +
+    "brief's Turn token section. If a JSON Schema is declared for this job, result is validated " +
+    "against it; an invalid submission returns a correction so you can fix and resubmit (capped " +
+    `at ${SUBMIT_RESULT_MAX_CORRECTIONS} corrections). This does not replace the markdown report ` +
+    "envelope — still finish with it.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      turn_token: { type: "string", description: "Turn token from the dispatch brief." },
+      result: { description: "The structured result payload." },
+    },
+    required: ["turn_token", "result"],
+  },
+};
+
 // Spin up an isolated, autonomous agent loop, hand it one task, and return
 // its final report. `params.cwd` is either the dispatcher's own cwd (shared
 // mode) or a worktree snapshotted from the dispatcher's last commit
@@ -307,6 +330,12 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<string> {
   });
 
   const permissionGate = params.permissionGate;
+  // Turn token (CL-6946): identifies this dispatch to submit_result so a
+  // submission survives only for the turn it was spawned under — if the
+  // orchestrator redirects/steers away, a stale submit_result call (echoing
+  // an old token) is rejected rather than silently accepted.
+  const turnToken = params.tier === "leaf" ? generateSessionId() : undefined;
+  const submitResultState = createSubmitResultState();
   const spawnRegistry = createSubAgentSpawnRegistryPlugin();
   // Child tools resolve spills against the child's own store first, then the
   // parent's (CL-4323): parent tool-output:// URIs handed in the brief must
@@ -422,6 +451,27 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<string> {
       }),
     ];
 
+    // submit_result (CL-6946): typed reporting channel, Tier 3 leaves only.
+    // Gated by the existing tier machinery — never invent a parallel check.
+    if (params.tier === "leaf") {
+      tools = [
+        ...tools,
+        stringTool({
+          definition: submitResultDefinition,
+          handler: async (rawArgs: Record<string, unknown>): Promise<string> => {
+            const outcome = evaluateSubmitResult({
+              turnToken: turnToken!,
+              submittedToken: rawArgs.turn_token,
+              result: rawArgs.result,
+              ...(params.reportSchema !== undefined ? { schema: params.reportSchema } : {}),
+              state: submitResultState,
+            });
+            return outcome.message;
+          },
+        }),
+      ];
+    }
+
     // Orchestrators need task + search_agents installed, not just mentioned in
     // the prompt. Nested dispatch always forbids further orchestration so the
     // tree bottoms out after one hop.
@@ -825,6 +875,7 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<string> {
       ...(params.reportFocus !== undefined && params.reportFocus.trim().length > 0
         ? { reportFocus: params.reportFocus }
         : {}),
+      ...(turnToken !== undefined ? { turnToken } : {}),
     });
     const ensureNotAborted = (): void => {
       // Re-read .aborted after await — control-flow narrowing would wrongly

src/subagent/submit-result.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+
+import { createSubmitResultState, evaluateSubmitResult } from "./submit-result.js";
+
+const TOKEN = "turn-abc123";
+
+describe("evaluateSubmitResult", () => {
+  test("a valid submission against a declared schema succeeds", () => {
+    const state = createSubmitResultState();
+    const outcome = evaluateSubmitResult({
+      turnToken: TOKEN,
+      submittedToken: TOKEN,
+      result: { verdict: "pass", score: 5 },
+      schema: {
+        type: "object",
+        required: ["verdict", "score"],
+        properties: {
+          verdict: { type: "string", enum: ["pass", "fail"] },
+          score: { type: "number", minimum: 0, maximum: 10 },
+        },
+      },
+      state,
+    });
+    expect(outcome.ok).toBe(true);
+    expect(outcome.message).toBe("Result accepted.");
+    expect(state.corrections).toBe(0);
+  });
+
+  test("an invalid submission returns a correction and a resubmit then succeeds", () => {
+    const state = createSubmitResultState();
+    const schema = {
+      type: "object" as const,
+      required: ["verdict"],
+      properties: { verdict: { type: "string", enum: ["pass", "fail"] } },
+    };
+
+    const first = evaluateSubmitResult({
+      turnToken: TOKEN,
+      submittedToken: TOKEN,
+      result: { verdict: "maybe" },
+      schema,
+      state,
+    });
+    expect(first.ok).toBe(false);
+    expect(first.message).toContain("Invalid submission");
+    expect(state.corrections).toBe(1);
+
+    const second = evaluateSubmitResult({
+      turnToken: TOKEN,
+      submittedToken: TOKEN,
+      result: { verdict: "pass" },
+      schema,
+      state,
+    });
+    expect(second.ok).toBe(true);
+    expect(second.message).toBe("Result accepted.");
+  });
+
+  test("a stale/mismatched turn token is rejected", () => {
+    const state = createSubmitResultState();
+    const outcome = evaluateSubmitResult({
+      turnToken: TOKEN,
+      submittedToken: "some-other-turn-token",
+      result: { verdict: "pass" },
+      state,
+    });
+    expect(outcome.ok).toBe(false);
+    expect(outcome.message).toContain("turn_token does not match");
+    expect(state.corrections).toBe(0);
+  });
+
+  test("correction cap refuses further attempts once reached", () => {
+    const state = createSubmitResultState();
+    const schema = { type: "object" as const, required: ["x"] };
+    for (let i = 0; i < 3; i++) {
+      evaluateSubmitResult({
+        turnToken: TOKEN,
+        submittedToken: TOKEN,
+        result: {},
+        schema,
+        state,
+      });
+    }
+    const capped = evaluateSubmitResult({
+      turnToken: TOKEN,
+      submittedToken: TOKEN,
+      result: { x: 1 },
+      schema,
+      state,
+    });
+    expect(capped.ok).toBe(false);
+    expect(capped.message).toContain("correction cap");
+  });
+});