fix(run): output-schema review follow-ups and provider constraint hints

EVENTS.md

@@ -538,12 +538,20 @@ These events are additive in schema version `"1"` and emitted only when
 The schema is validated before any model request, with Ajv defaults and
 `allErrors: true` (draft-07, or Ajv2020 for a declared draft 2020-12). Validation
 does not coerce types, insert defaults or remove extra properties.
-
-`--output-schema-retries <n>` permits N additional corrective attempts (default 2).
-Zero permits exactly one attempt. `--output-result <file>` writes only accepted
-JSON using two-space indentation and a trailing newline, with a temporary file
-in the destination directory followed by an atomic rename. Failures preserve the
-file. Both flags require `--output-schema`; the destination directory must exist and be writable at configuration time.
+Serialized schemas are limited to 64 KiB, depth 64 and 10,000 nested objects.
+The schema file is trusted instruction input: annotations (`description`, `title`,
+`examples`) are shown to the model in the StructuredOutput tool description.
+
+`--output-schema-retries <n>` permits N additional corrective turns (0–10, default 2).
+Zero permits only the initial turn; N permits the initial turn and at most N
+corrective turns. A step can contain multiple StructuredOutput
+calls; every rejected call is reported and counted even after the budget is spent.
+`--output-result <file>` writes only accepted JSON using two-space indentation and
+a trailing newline, with a temporary file in the destination directory followed
+by an atomic rename. Failures preserve the file. Both flags require
+`--output-schema`; the destination directory must exist and be writable at
+configuration time. Relative paths resolve against `--dir` when it is given, and
+configuration errors name the resolved path after the reason.
 Without `--output-result`, formatted mode prints final JSON; NDJSON includes the
 value in the terminal event below.
 
@@ -562,7 +570,8 @@ and a model turn that finishes in prose without a final tool call:
 ```
 
 The usual event envelope fields also apply. `attempt` is one-based;
-`maxAttempts` equals `retryCount + 1`. Diagnostics include at most ten errors,
+`maxAttempts` equals `retryCount + 1`, the corrective turn budget; `attempt` can
+exceed it when a step contains multiple calls. Diagnostics include at most ten errors,
 with bounded JSON-pointer paths, keywords and messages. Their encoded payload
 is under 2 KB and never includes submitted values or raw JSON arguments. A `path`
 can contain property names submitted by the model (for example, in map or
@@ -578,7 +587,8 @@ validation always uses the canonical schema.
 
 ### `structured_output`
 
-Exactly one terminal event per schema-enabled session, before `session_complete`:
+Exactly one terminal event per schema-enabled prompt run, before `session_complete`.
+A headless `aictrl run` has one prompt run:
 
 ```json
 { "type": "structured_output", "status": "accepted", "attempts": 2, "value": { "result": "ok" } }
@@ -595,8 +605,9 @@ and prose-only finishes without a final call. Other tool calls do not count.
 Compaction turns do not consume a missing-result attempt. Discarded provider
 streams restore the budget and captured result; their rejection events remain
 as telemetry. A valid call in a parallel step wins regardless of call order if
-that step started with budget remaining, and its attempt count stays within the
-configured maximum.
+that step started with budget remaining. The attempt count includes every call
+in that step and can exceed `maxAttempts`; the N+1 bound applies to corrective
+turns.
 When the budget is spent, the last rejection determines the reason: `missing`
 for a prose-only finish, otherwise `exhausted`. Failure reasons are:
 

README.md

@@ -52,8 +52,13 @@ aictrl run --format json "review this PR" | jq '.type'
 ### Validated Final Results
 
 `aictrl run --output-schema <file>` validates the final JSON result.
-Use `--output-schema-retries <n>` for additional corrective attempts (default 2)
+Use `--output-schema-retries <n>` for additional corrective turns (0–10, default 2)
 and `--output-result <file>` to atomically write the accepted value.
+Zero retries permits only the initial turn; N permits the initial turn and at
+most N corrective turns. Serialized schemas are limited to 64 KiB, depth 64 and 10,000
+nested objects.
+Schema mode emits exactly one terminal `structured_output` event per prompt run;
+a headless `aictrl run` has one prompt run.
 Exit codes: **0** accepted, **2** configuration error, **3** missing or invalid result;
 provider failures and stream timeouts use **1**, signals use **130**/**143**.
 See the [full contract](packages/cli/README.md#validated-final-results)

packages/cli/README.md

@@ -34,34 +34,43 @@ aictrl run --format json "scan for secrets" | jq '.properties.part.text'
 while the agent can continue using tools. The schema root must be `type: "object"`.
 Schemas use Ajv defaults (strict validation, draft-07); a declared draft 2020-12
 schema uses Ajv2020. Invalid configuration exits before any model request.
+Serialized schemas are limited to 64 KiB, depth 64 and 10,000 nested objects.
 
 ```bash
 aictrl run --output-schema result.schema.json --output-schema-retries 2 \
   --output-result result.json "review this change"
 ```
 
 - `--output-schema <file>`: JSON Schema file, forwarded in local and `--attach` runs.
-- `--output-schema-retries <n>`: additional corrective attempts, integer >= 0,
-  default 2. Zero permits one attempt; N permits at most N+1 attempts.
+  The file is trusted instruction input: annotations (`description`, `title`,
+  `examples`) are shown to the model in the StructuredOutput tool description.
+- `--output-schema-retries <n>`: additional corrective turns, integer from 0 to 10,
+  default 2. Zero permits only the initial turn; N permits the initial turn and
+  at most N corrective turns. Each rejected call is counted, including multiple
+  calls in one step.
 - `--output-result <file>`: atomically write only the validated JSON value,
   indented with two spaces and a trailing newline. Failures preserve an existing
   file and leave an absent file absent. The destination directory must exist.
 
+Relative `--output-schema` and `--output-result` paths resolve against `--dir` when
+it is given (as `--file` paths do); configuration errors print the resolved path.
+
 Ajv strict mode rejects unknown schema keywords and unregistered `format`
 values such as `date-time` and `uri` as configuration errors (exit **2**).
 The result parent directory must exist and be writable at configuration time.
 
 The retries and result flags require `--output-schema`. Without a result file,
 formatted mode prints validated JSON at the end; `--format json` emits it in a
-terminal `structured_output` event. Rejections emit `structured_output_rejected`
+terminal `structured_output` event, exactly one per prompt run. A headless
+`aictrl run` has one prompt run. Rejections emit `structured_output_rejected`
 with bounded JSON-pointer diagnostics. See [EVENTS.md](../../EVENTS.md) for the contract.
 No valid result means failure, including missing output and the agent step limit;
 there is no prose fallback. A prose-only finish consumes one attempt and receives
 a reminder to call StructuredOutput while retries remain. Earlier tools are not
-replayed for corrective attempts.
+replayed for corrective turns.
 
 Exit codes: **0** for accepted results, **2** for schema configuration errors,
-**3** for exhausted attempts, missing output or a step limit without a result.
+**3** for exhausted corrective turns, missing output or a step limit without a result.
 Provider failures and stream timeouts retain **1**; SIGINT/SIGTERM retain
 **130**/**143**. Invocations without `--output-schema` keep their existing output.
 

packages/cli/src/cli/cmd/run.output.ts

@@ -1,4 +1,5 @@
 import path from "path"
+// Bun content I/O preserves createPath: false; fs/promises supplies metadata and atomic rename/removal.
 import fs from "fs/promises"
 import { OutputSchema } from "@/session/output-schema"
 
@@ -12,32 +13,37 @@ export async function outputSchema(input: { schema?: string; retries?: number; r
       throw new Error("--output-schema-retries and --output-result require --output-schema")
     return
   }
-  if (input.retries !== undefined && (!Number.isSafeInteger(input.retries) || input.retries < 0))
-    throw new Error("--output-schema-retries must be an integer >= 0")
-  const text = await Bun.file(input.schema)
+  if (input.retries !== undefined && (!Number.isSafeInteger(input.retries) || input.retries < 0 || input.retries > 10))
+    throw new Error("--output-schema-retries must be an integer between 0 and 10")
+  // Relative paths resolve against --dir (run changes into it first), like --file.
+  // Report the resolved path after the reason, so clipping (300 chars) drops path
+  // text rather than the cause.
+  const file = path.resolve(input.schema)
+  const text = await Bun.file(file)
     .text()
     .catch(() => {
-      throw new Error(`${input.schema}: cannot read schema file`)
+      throw new Error(`cannot read schema file (${file})`)
     })
   const schema: unknown = (() => {
     try {
       return JSON.parse(text)
     } catch {
-      throw new Error(`${input.schema}: invalid JSON`)
+      throw new Error(`invalid JSON (${file})`)
     }
   })()
   if (!schema || typeof schema !== "object" || Array.isArray(schema))
-    throw new Error(`${input.schema}: schema root must have type "object"`)
+    throw new Error(`schema root must be a JSON object (${file})`)
   const canonical = schema as Record<string, unknown>
   const validate = (() => {
     try {
       return OutputSchema.compile(canonical)
     } catch (error) {
-      throw new Error(`${input.schema}: ${error instanceof Error ? error.message : "cannot compile schema"}`)
+      throw new Error(`${error instanceof Error ? error.message : "cannot compile schema"} (${file})`)
     }
   })()
   if (input.result) {
-    const directory = path.dirname(input.result)
+    const result = path.resolve(input.result)
+    const directory = path.dirname(result)
     const writable = await fs
       .stat(directory)
       .then(async (stat) => {
@@ -46,7 +52,7 @@ export async function outputSchema(input: { schema?: string; retries?: number; r
         return true
       })
       .catch(() => false)
-    if (!writable) throw new Error(`${input.result}: output-result parent directory must exist and be writable`)
+    if (!writable) throw new Error(`output-result parent directory must exist and be writable (${result})`)
   }
   return { format: { type: "json_schema" as const, schema: canonical, retryCount: input.retries ?? 2 }, validate }
 }

packages/cli/src/cli/cmd/run.ts

@@ -350,7 +350,7 @@ export const RunCommand = cmd({
         describe: "format: default (formatted) or json (raw JSON events)",
       })
       .option("output-schema", { type: "string", describe: "JSON Schema file for the final result (object root)" })
-      .option("output-schema-retries", { type: "number", describe: "additional corrective attempts (default: 2)" })
+      .option("output-schema-retries", { type: "number", describe: "additional corrective turns (0-10, default: 2)" })
       .option("output-result", {
         type: "string",
         describe: "atomically write only the validated JSON result to this file",
@@ -561,7 +561,8 @@ export const RunCommand = cmd({
         return false
       }
 
-      const events = await sdk.event.subscribe()
+      const subscriptionAbort = new AbortController()
+      const events = await sdk.event.subscribe({ signal: subscriptionAbort.signal })
       let error: string | undefined
       const startTime = Date.now()
       const childSessions = new Set<string>()
@@ -1014,12 +1015,21 @@ export const RunCommand = cmd({
           })
       }
 
-      const loopDone = loop()
-        .then(() => complete())
-        .catch(reject)
+      const loopDone = loop().then(
+        () => ({ ok: true as const }),
+        (cause: unknown) => ({ ok: false as const, cause }),
+      )
+      const finish = async (result: Awaited<typeof loopDone>) => {
+        if (result.ok) return complete()
+        return reject(result.cause)
+      }
+      let failure: { cause: unknown } | undefined
+      const failed = (cause: unknown) => {
+        failure = { cause }
+      }
 
       if (control.current) {
-        await loopDone
+        await finish(await loopDone)
         await Shutdown.flush()
         return
       }
@@ -1034,7 +1044,7 @@ export const RunCommand = cmd({
           ...(schema ? { format: schema.format } : {}),
         }
         const request = sdk.session.command(input(sessionID, opts))
-        await (schema ? request.catch(reject) : request)
+        await (schema ? request.catch(failed) : request)
       } else {
         const model = args.model ? Provider.parseModel(args.model) : undefined
         const opts = {
@@ -1045,11 +1055,15 @@ export const RunCommand = cmd({
           ...(schema ? { format: schema.format } : {}),
         }
         const request = sdk.session.prompt(input(sessionID, opts))
-        await (schema ? request.catch(reject) : request)
+        await (schema ? request.catch(failed) : request)
       }
 
-      if (schema && error) {
+      if (schema && (failure || error)) {
         abort()
+        subscriptionAbort.abort()
+        const result = await loopDone
+        if (failure) await reject(failure.cause)
+        if (!failure) await finish(result)
         await Shutdown.flush()
         return
       }
@@ -1059,7 +1073,19 @@ export const RunCommand = cmd({
       // (e.g., Session.get() fails, model not found), no session.status idle event
       // is emitted, so loopDone would hang forever. Racing ensures we surface
       // the error and exit.
-      await Promise.race([loopDone, promptResult.then(() => loopDone, reject)])
+      const result = await Promise.race([
+        loopDone,
+        promptResult.then(
+          () => loopDone,
+          (cause: unknown) => ({ ok: false as const, cause }),
+        ),
+      ])
+      if (schema && !result.ok) {
+        abort()
+        subscriptionAbort.abort()
+        await loopDone
+      }
+      await finish(result)
       await Shutdown.flush()
     }
 
@@ -1124,27 +1150,34 @@ export const RunCommand = cmd({
           },
         },
         event: {
-          async subscribe() {
+          async subscribe(opts: { signal: AbortSignal }) {
             const queue: any[] = []
             let resolve: (() => void) | null = null
             const handler = (event: { payload: any }) => {
               queue.push(event.payload)
               resolve?.()
             }
             GlobalBus.on("event", handler)
+            const stop = () => {
+              GlobalBus.off("event", handler)
+              resolve?.()
+            }
+            opts.signal.addEventListener("abort", stop)
 
             const stream = (async function* () {
               try {
                 while (true) {
                   while (queue.length > 0) {
                     yield queue.shift()
                   }
+                  if (opts.signal.aborted) break
                   await new Promise<void>((r) => {
                     resolve = r
                   })
                 }
               } finally {
                 GlobalBus.off("event", handler)
+                opts.signal.removeEventListener("abort", stop)
               }
             })()
             return { stream }

packages/cli/src/session/llm.ts

@@ -9,6 +9,7 @@ import {
   type StreamTextResult,
   type Tool,
   type ToolSet,
+  type ToolChoice,
   tool,
   jsonSchema,
 } from "ai"
@@ -40,7 +41,7 @@ export namespace LLM {
     small?: boolean
     tools: Record<string, Tool>
     retries?: number
-    toolChoice?: "auto" | "required" | "none"
+    toolChoice?: ToolChoice<ToolSet>
     structured?: { reject: (input: string) => Promise<string>; checkpoint: () => () => void; repairs: Set<string> }
   }
 

packages/cli/src/session/message-v2.ts

@@ -83,7 +83,12 @@ export namespace MessageV2 {
     .object({
       type: z.literal("json_schema"),
       schema: z.record(z.string(), z.any()).meta({ ref: "JSONSchema" }),
-      retryCount: z.number().int().min(0).default(2),
+      retryCount: z
+        .number()
+        .int()
+        .min(0)
+        .transform((n) => Math.min(n, 10))
+        .default(2),
     })
     .meta({
       ref: "OutputFormatJsonSchema",

packages/cli/src/session/output-schema.ts

@@ -1,6 +1,7 @@
 import Ajv, { type ErrorObject } from "ajv"
 import Ajv2020 from "ajv/dist/2020"
 import z from "zod"
+import { createHash } from "crypto"
 
 export namespace OutputSchema {
   export const Diagnostic = z.object({ path: z.string(), keyword: z.string(), message: z.string() })
@@ -19,9 +20,34 @@ export namespace OutputSchema {
   // acceptance, including schemas cloned by Zod or loaded from session storage.
   const cache = new Map<string, ReturnType<Ajv["compile"]>>()
 
+  // Ajv codegen recurses per nesting level: ~2,000 levels fit in 16 KB yet overflow
+  // the stack, so bound structure as well as bytes. Iterative, so the check itself
+  // cannot overflow.
+  const MAX_DEPTH = 64
+  const MAX_NODES = 10_000
+  function bound(schema: unknown) {
+    const stack: [unknown, number][] = [[schema, 0]]
+    let nodes = 0
+    while (stack.length) {
+      const [value, depth] = stack.pop()!
+      if (!value || typeof value !== "object") continue
+      if (depth > MAX_DEPTH) throw new Error(`schema nesting must not exceed ${MAX_DEPTH} levels`)
+      if (++nodes > MAX_NODES) throw new Error(`schema must not exceed ${MAX_NODES} nested objects`)
+      for (const child of Object.values(value)) stack.push([child, depth + 1])
+    }
+  }
+
+  export function canonical(schema: Record<string, unknown>) {
+    bound(schema)
+    const text = JSON.stringify(schema)
+    const bytes = Buffer.byteLength(text)
+    if (bytes > 64 * 1024) throw new Error("serialized schema must not exceed 64 KiB")
+    return { text, bytes }
+  }
+
   export function compile(schema: Record<string, unknown>) {
     if (schema.type !== "object") throw new Error('schema root must have type "object"')
-    const key = JSON.stringify(schema)
+    const key = createHash("sha256").update(canonical(schema).text).digest("hex")
     const cached = cache.get(key)
     if (cached) return cached
     const ajv =