@dtlabs/ai-toolkit 0.14.1 → 0.14.3

package/CHANGELOG.md

@@ -1,4 +1,23 @@
 ## 0.1.4 (2026-07-21)
+## [0.14.3](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.2...v0.14.3) (2026-10-01)
+
+
+### Bug Fixes
+
+* **workflows:** accept a schema-valid <structured_output> text block when the CLI field is empty ([6814d96](https://github.com/dtlab-tech/ai-toolkit/commit/6814d96dd10dc5807b8c20417c5a2767cce05216))
+* **workflows:** handle multiple model-chosen delimiters for the structured-output text fallback ([7d97758](https://github.com/dtlab-tech/ai-toolkit/commit/7d977589e10480e6bce66a4ca68a5dbc89b372b1))
+* **workflows:** schema-validated text fallback for empty structured_output ([f2bd76f](https://github.com/dtlab-tech/ai-toolkit/commit/f2bd76fcba554c1b30a2c84629bfd2224a721d13))
+* **workflows:** schema-validated text fallback for empty structured_output ([daa1411](https://github.com/dtlab-tech/ai-toolkit/commit/daa1411d15c919254ce948a785b31d56e6e4468c))
+
+## [0.14.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.1...v0.14.2) (2026-10-01)
+
+
+### Bug Fixes
+
+* **workflows:** host persists worker-declared outputs, no Write tool on the agent ([1109fc0](https://github.com/dtlab-tech/ai-toolkit/commit/1109fc0943ad21eedbbf859a185e3a49c654c06d))
+* **workflows:** host persists worker-declared outputs, no Write tool on the agent ([56f062c](https://github.com/dtlab-tech/ai-toolkit/commit/56f062c232110d2399d88ee011fa165b43336d12))
+* **workflows:** host persists worker-declared outputs, no Write tool on the agent ([7c1b8dc](https://github.com/dtlab-tech/ai-toolkit/commit/7c1b8dca4ba9715809b6417f5081bcca0edb09e3))
+
 ## [0.14.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.0...v0.14.1) (2026-09-30)
 
 

package/docs/workflow-control-plane.md

@@ -91,11 +91,23 @@ negative semantic verdict, unknown scopes, paths with spaces and explicit approv
 The live paid Claude model/permission flow has not been exercised by these tests.
 Document validation requires both a written Validation Report and a structured
 verdict (`valid: boolean`, `findings: string[]`). The validator performs one pass;
-the host owns revisions. A report or JSON in the plain-text result cannot replace
-`structured_output` from `--json-schema`. Missing structured output stops the
-workflow with an error naming the worker and required fields. Regression tests
-cover missing/malformed verdicts, a clean verdict without a report, and a negative
-verdict followed by host revision and a clean result; model responses are mocked.
+the host owns revisions. Bare plain-text JSON, with no delimiter, never substitutes
+for `structured_output` from `--json-schema`. However, the CLI's own structured-output
+extraction is turn-bound: it only populates `structured_output` when the model's final
+turn ends in a tool call carrying the schema payload, and a long multi-phase agent
+response (full report text, then a closing JSON object) ends that same turn in plain
+text instead — so `structured_output` can come back empty even though the model
+emitted a schema-valid payload in a `<structured_output>...</structured_output>`
+block, exactly as its own agent definition instructs. The host falls back to
+extracting and schema-validating that one delimited block from the plain-text result
+when `structured_output` is absent; this is a deterministic, strictly-delimited parse
+(never "guess the JSON somewhere in the text"), so it does not reintroduce LLM-driven
+I/O. A missing field, a missing/malformed delimited block, or a block that fails
+schema validation all still stop the workflow with the original error naming the
+worker and required fields. Regression tests cover missing/malformed verdicts, a
+clean verdict without a report, the delimited-text fallback (both the accepted and
+the schema-rejected case), and a negative verdict followed by host revision and a
+clean result; model responses are mocked.
 The subprocess adapter reuses FTR-018's existing qualification; no new cross-platform
 process-supervision guarantee is claimed. On Windows, the full executor test suite
 requires Git Bash ahead of the WSL launcher in PATH. User-level installations are

package/lib/workflow-control.js

@@ -8,6 +8,8 @@ const { spawnSync } = require('child_process');
 const registry = require('./agent-registry');
 const ledger = require('./execution-ledger');
 const { spawnClaudeAgent } = require('./task-executor/claude-process');
+const { createEvidence } = require('./workflow-worker-evidence');
+const { resolveOutputPath } = require('./workflow-worker-outputs');
 const CLI = path.join(__dirname, '..', 'bin', 'cli.js');
 
 
@@ -66,7 +68,16 @@ function deriveFeatureDir(featurePath) {
 }
 
 function createControl(options) {
-  const root = path.resolve(options.projectDir);
+  if (options.workerMaxBudgetUsd != null && (!Number.isFinite(options.workerMaxBudgetUsd) || options.workerMaxBudgetUsd <= 0)) throw new Error('Worker budget must be a positive finite number');
+  // Windows can alias any long/dotted path segment to an 8.3 short name (e.g. the
+  // TEMP env var itself is often short-form: C:\Users\TOMADA~1\...). The spawned
+  // CLI resolves a tool call's absolute path in long form regardless, so an
+  // --allowedTools pattern built from a short-form root would silently never
+  // match — confirmed empirically (tests/manual/workflow-worker-smoke.js) against
+  // a real CLI run under a short-form TEMP path. realpath.native (unlike the pure-JS
+  // fs.realpathSync) resolves 8.3 aliases on Windows, and is a harmless plain
+  // symlink-resolving realpath on every other platform.
+  const root = fs.realpathSync.native(path.resolve(options.projectDir));
   const runId = crypto.randomUUID();
   let context, spent = 0, sequence = 0;
   const tokenLedger = [];
@@ -81,6 +92,13 @@ function createControl(options) {
     try { fs.writeFileSync(tmp, content, 'utf8'); fs.renameSync(tmp, dest); }
     finally { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); }
   };
+  // Validates a worker-declared (or, for a dynamic multi-file deliverable like
+  // intervention-documentation-standard, model-declared) output path the same way
+  // worker()'s single-output contract does — inside the project, outside any tool-config
+  // directory, never through a symlink — then writes it. The one path through which any
+  // LLM response ever reaches disk in this workflow runtime; see worker()'s own comment
+  // for why that's the host's job and never the agent's.
+  const writeOutput = (p, content) => write(resolveOutputPath(root, { path: p }), content);
   async function resolve(id, kind = 'agent') {
     const record = await registry.resolveAgent({ projectDir: root, homeDir: options.home,
       agentId: id, requireVerified: true });
@@ -123,13 +141,70 @@ function createControl(options) {
     return activity(opts.label || id, async () => {
       const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName];
       if (opts.schema) cliArgs.push('--json-schema', JSON.stringify(opts.schema));
+      if (options.workerMaxBudgetUsd != null) cliArgs.push('--max-budget-usd', String(options.workerMaxBudgetUsd));
+      const outputs = opts.outputs || [];
+      for (const output of outputs) {
+        if (!output || typeof output.path !== 'string' || !Array.isArray(output.inputs || [])) throw new Error('Invalid worker output contract');
+      }
+      // Never ask an LLM to do I/O: a worker with a declared output has no Write tool at
+      // all (see its agent frontmatter) and returns the document as plain response text
+      // (or, under --json-schema, as a `report` field) instead. The host resolves and
+      // validates the real target path up front — fail before dispatch, not after paying
+      // for a model turn — and writes the file itself once the response is in hand. This
+      // sidesteps the CLI's own permission system for Write entirely, which empirically
+      // (tests/manual/workflow-worker-smoke.js) does not support a non-interactive mode
+      // that both skips prompting AND honors a scoped, per-file allow pattern: `dontAsk`
+      // ignores runtime-supplied allow rules for paths with no pre-existing persisted
+      // grant, while `acceptEdits`/`auto` grant Write (and every other tool, unscoped)
+      // anywhere in the project regardless of any allowlist passed alongside them.
+      if (outputs.length > 1) throw new Error('Worker output contract supports exactly one output today: ' + id);
+      const outputTarget = outputs.length ? resolveOutputPath(root, outputs[0]) : null;
+      const evidence = createEvidence(options, runId, identity, {
+        executable: options.claudePath || null, cwd: root, args: cliArgs, outputs,
+      });
+      (options.log || (() => {}))('Worker evidence: ' + evidence.file);
+      try {
       const result = await (options.dispatch || spawnClaudeAgent)({
         claudePath: options.claudePath, cwd: root, args: cliArgs, prompt,
         taskTimeoutMs: options.taskTimeoutMs || 1800000,
       });
+      // Count usage before any business/protocol check, including denied tools.
+      const usage = result.result?.usage;
+      const counts = usage && [usage.input_tokens, usage.output_tokens,
+        usage.cache_read_input_tokens ?? 0, usage.cache_creation_input_tokens ?? 0];
+      const tokens = counts && counts.every(n => Number.isInteger(n) && n >= 0)
+        ? counts.reduce((a, b) => a + b, 0) : null;
+      measuredTokens = Number.isSafeInteger(tokens) && tokens > 0 ? tokens : null;
+      spent += measuredTokens || 0;
+      tokenLedger.push({ agent: identity.nativeName, model: definition.model,
+        phase_delta_tokens: measuredTokens, usage: usage || null, evidence_path: evidence.file });
+      evidence.save({ response: result });
+      const denials = result.result?.permission_denials;
+      if (Array.isArray(denials) && denials.length) {
+        const tools = [...new Set(denials.map(d => d.tool_name || 'unknown'))].join(', ');
+        throw new Error('Worker permission denied: ' + id + '; tools: ' + tools);
+      }
       if (result.exitCode !== 0 || result.parseError || result.timedOut ||
           !result.result || result.result.is_error !== false) throw new Error('Worker failed: ' + id);
-      const payload = opts.schema ? result.result.structured_output : result.result.result;
+      let payload = opts.schema ? result.result.structured_output : result.result.result;
+      let usedTextFallback = false;
+      // The CLI's structured-output extraction is turn-bound: it only populates
+      // `structured_output` when the model's final turn ends in a tool call carrying the
+      // schema payload. A long, multi-phase agent response (visible report text, then a
+      // closing JSON object) ends that same turn in plain text instead, so `structured_output`
+      // comes back empty even though the model faithfully emitted a schema-valid payload in
+      // the plain-text result. Observed empirically (not a transient flake) with
+      // gaia-validate-feature-docs across multiple toolkit versions and multiple runs: the
+      // model never misses or mangles the payload, only the CLI's own field never gets
+      // populated — but the model is NOT consistent about how it delimits that payload inside
+      // its text (an `<structured_output>` tag one run, a ```json fence the next, same agent,
+      // same schema). Falling back to a strictly-delimited, schema-validated extraction that
+      // tries each known convention — never a bare "parse the whole result as JSON" guess —
+      // keeps the host's parse deterministic rather than asking the LLM to do I/O.
+      if (opts.schema && payload == null && typeof result.result.result === 'string') {
+        const candidate = extractDelimitedStructuredOutput(result.result.result, opts.schema);
+        if (candidate != null) { payload = candidate; usedTextFallback = true; }
+      }
       if (payload == null || (typeof payload === 'string' && !payload.trim())) {
         if (opts.schema) {
           const fields = (opts.schema.required || []).join(', ') || '(see requested schema)';
@@ -138,13 +213,18 @@ function createControl(options) {
         throw new Error('Worker returned no result: ' + id);
       }
       if (opts.schema) validateSchema(payload, opts.schema);
-      const usage = result.result.usage;
-      const tokens = usage && [usage.input_tokens, usage.output_tokens].every(Number.isFinite)
-        ? usage.input_tokens + usage.output_tokens + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0) : null;
-      measuredTokens = Number.isInteger(tokens) && tokens > 0 ? tokens : null;
-      spent += measuredTokens || 0;
-      tokenLedger.push({ agent: identity.nativeName, model: definition.model, phase_delta_tokens: measuredTokens });
+      if (usedTextFallback) evidence.save({ usedTextFallback: true });
+      if (outputTarget) {
+        const content = opts.schema ? payload.report : payload;
+        if (typeof content !== 'string' || !content.trim()) throw new Error('Worker output content missing or empty: ' + id);
+        writeOutput(outputTarget, content);
+      }
+      evidence.save({ outcome: 'done', completedAt: new Date().toISOString() });
       return payload;
+      } catch (error) {
+        evidence.save({ outcome: 'failed', error: String(error), completedAt: new Date().toISOString() });
+        throw new Error(error.message + '; evidence: ' + evidence.file, { cause: error });
+      }
     }, definition.model, () => measuredTokens, { agentId: id, nativeAgentName: identity.nativeName, platform: 'claude', definitionHash: identity.sha256, resolutionScope: identity.scope, toolkitVersion: identity.toolkitVersion });
   }
   async function parallel(fns) {
@@ -189,13 +269,20 @@ function createControl(options) {
   }
   function feature(p) {
     if (!p) throw new Error('Feature path required');
-    const file = full(p), dir = deriveFeatureDir(file);
+    const file = full(p);
+    read(file); // confirms existence (with a clear error) before realpath.native requires it
+    // Canonicalize once, here, so every output path derived from featureDir downstream
+    // (pm-phase1.js/pm-phase2.js's `file()` helpers) shares the same 8.3-alias-free form
+    // as `root` — resolveOutputPath() can then do a plain, non-realpath string comparison
+    // instead of reconciling mismatched forms (which would have to silently follow
+    // symlinks to do so, defeating its own symlink-escape check).
+    const canonicalFile = fs.realpathSync.native(file);
+    const dir = deriveFeatureDir(canonicalFile);
     const match = path.basename(dir).match(/^([A-Z]+-\d+)(?:-|$)/);
     if (!match) throw new Error('Cannot derive canonical feature prefix');
-    read(file);
-    return { featurePath: file, featureDir: dir, prefix: match[1] };
+    return { featurePath: canonicalFile, featureDir: dir, prefix: match[1] };
   }
-  const api = { root, runId, read, exists, write, resolve, worker, parallel, run, command, activity,
+  const api = { root, runId, read, exists, write, writeOutput, resolve, worker, parallel, run, command, activity,
     feature, parseArgs, tokenLedger, spent: () => spent,
     mtime: p => fs.statSync(full(p)).mtimeMs,
     json: p => JSON.parse(read(p)),
@@ -209,6 +296,27 @@ function createControl(options) {
   return api;
 }
 
+// Tries each known convention a model has been observed using to delimit its final
+// structured answer inside otherwise-free text, in order of explicitness, and returns the
+// first candidate that is both valid JSON and schema-conformant. Returns null (never throws)
+// if no candidate qualifies, so the caller's original "no structured output" error still fires
+// unchanged when the text holds nothing usable.
+function extractDelimitedStructuredOutput(text, schema) {
+  const candidates = [];
+  const tagMatch = text.match(/<structured_output>([\s\S]*?)<\/structured_output>/);
+  if (tagMatch) candidates.push(tagMatch[1]);
+  const fenceMatches = [...text.matchAll(/```json\s*([\s\S]*?)```/gi)];
+  if (fenceMatches.length) candidates.push(fenceMatches[fenceMatches.length - 1][1]);
+  for (const raw of candidates) {
+    try {
+      const parsed = JSON.parse(raw.trim());
+      validateSchema(parsed, schema);
+      return parsed;
+    } catch (e) { /* try the next candidate, or fall through to null */ }
+  }
+  return null;
+}
+
 function validateSchema(value, schema) {
   if (schema.type === 'object') {
     if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid structured object');

package/lib/workflow-runner.js

@@ -26,11 +26,13 @@ async function main(argv) {
   const split = argv.indexOf('--');
   if (split < 0) throw new Error('Workflow arguments must follow --');
   const options = { projectDir: process.cwd(), log: s => process.stderr.write(s + '\n') };
-  const keys = { '--project': 'projectDir', '--home': 'home', '--claude-path': 'claudePath' };
+  const keys = { '--project': 'projectDir', '--home': 'home', '--claude-path': 'claudePath',
+    '--diagnostics-dir': 'diagnosticsDir', '--worker-max-budget-usd': 'workerMaxBudgetUsd' };
   for (let i = 2; i < split; i += 2) {
     if (!keys[argv[i]] || !argv[i + 1] || argv[i + 1].startsWith('--')) throw new Error('Invalid workflow option: ' + argv[i]);
     options[keys[argv[i]]] = argv[i + 1];
   }
+  if (options.workerMaxBudgetUsd != null) options.workerMaxBudgetUsd = Number(options.workerMaxBudgetUsd);
   if (!options.claudePath && argv[1] !== 'am-phase2') throw new Error('--claude-path is required');
   const result = await runWorkflow(argv[1], argv.slice(split + 1), options);
   process.stdout.write(JSON.stringify(result) + '\n');

package/lib/workflow-worker-evidence.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+// Do not capture the parent environment or stdin prompt. Diagnostic responses
+// can contain document text; redact common credential forms before persistence.
+function redact(value) {
+  const secretKey = /^(?:authorization|proxy.authorization|.*(?:api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret|credential))$/i;
+  const secrets = Object.entries(process.env)
+    .filter(([key, val]) => secretKey.test(key) && val && val.length >= 8)
+    .map(([, val]) => val);
+  function cleanString(text) {
+    for (const secret of secrets) text = text.split(secret).join('[REDACTED]');
+    return text
+      .replace(/\b(Bearer\s+)[^\s"'<>]+/gi, '$1[REDACTED]')
+      .replace(/\b((?:api[_-]?key|token|password|secret)\s*[=:]\s*)[^\s,"'<>]+/gi, '$1[REDACTED]')
+      .replace(/\bsk-[A-Za-z0-9_-]+/g, '[REDACTED]');
+  }
+  function walk(item) {
+    if (typeof item === 'string') {
+      // stdout is often a JSON string: redact credential keys there too.
+      try { return JSON.stringify(walk(JSON.parse(item))); } catch (_) { return cleanString(item); }
+    }
+    if (Array.isArray(item)) return item.map(walk);
+    if (item && typeof item === 'object') return Object.fromEntries(Object.entries(item)
+      .map(([key, val]) => [key, secretKey.test(key) ? '[REDACTED]' : walk(val)]));
+    return item;
+  }
+  return walk(value);
+}
+
+function createEvidence(options, runId, identity, invocation) {
+  const dir = path.join(path.resolve(options.diagnosticsDir || path.join(os.tmpdir(), 'ai-toolkit-workflows')), runId);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, crypto.randomUUID() + '.json');
+  const record = { version: 1, runId, agentId: identity.agentId, definitionPath: identity.path,
+    definitionHash: identity.sha256, invocation, startedAt: new Date().toISOString(), outcome: 'running' };
+  function save(patch) {
+    Object.assign(record, patch);
+    const temp = file + '.tmp';
+    try {
+      fs.writeFileSync(temp, JSON.stringify(redact(record), null, 2) + '\n', { mode: 0o600 });
+      fs.renameSync(temp, file);
+    } finally { if (fs.existsSync(temp)) fs.unlinkSync(temp); }
+  }
+  save({});
+  return { file, save };
+}
+
+module.exports = { createEvidence, redact };

package/lib/workflow-worker-outputs.js

@@ -0,0 +1,37 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+// Validates that a worker's declared output stays inside the project, outside any
+// tool-config directory, and is never reached through a symlink/junction — then
+// returns its canonical absolute path. The workflow host (never the LLM) writes the
+// worker's returned content to this path with fs.writeFileSync; there is no CLI
+// permission surface to construct here ("Never ask an LLM to do I/O").
+//
+// Assumes `root` and `output.path` already share the same 8.3-alias form (createControl
+// realpath.native's `root` once at startup; feature() realpath.native's featurePath/
+// featureDir the same way, and every output.path in this codebase is built from
+// featureDir) — do NOT realpath-resolve anything in here to "reconcile" a mismatch: that
+// would have to follow symlinks to do it, silently defeating the symlink check below.
+function resolveOutputPath(root, output) {
+  const target = path.resolve(root, output.path);
+  const relative = path.relative(root, target);
+  if (!relative || path.isAbsolute(relative) || relative === '..' || relative.startsWith('..' + path.sep)) {
+    throw new Error('Worker output must be inside the project: ' + target);
+  }
+  const segments = relative.split(path.sep);
+  if (segments.some(s => ['.git', '.claude', '.codex'].includes(s.toLowerCase()))) {
+    throw new Error('Unsupported worker output path: ' + target);
+  }
+  // Never automatically write a target reached through a symlink/junction.
+  let cursor = root;
+  for (const segment of segments) {
+    cursor = path.join(cursor, segment);
+    try {
+      if (fs.lstatSync(cursor).isSymbolicLink()) throw new Error('Worker output traverses a symlink: ' + cursor);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return target;
+}
+
+module.exports = { resolveOutputPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/agents/gaia-concurrency-safety-assessment.md

@@ -1,7 +1,7 @@
 ---
 name: gaia-concurrency-safety-assessment
 description: "Concurrency Safety Assessment — identifies race conditions, shared mutable state corruption, and non-deterministic behaviour in concurrent or event-driven systems. Language-agnostic; produces structured findings with severity, evidence, and mitigation patterns. Output: {ASSESS_PREFIX}-Concurrency-Assessment.md"
-tools: Read, Grep, Glob, Bash, Write
+tools: Read, Grep, Glob, Bash
 model: haiku
 ---
 
@@ -120,7 +120,7 @@ Blocking: Yes / No
 
 ## Output
 
-Write to `{ASSESS_PREFIX}-Concurrency-Assessment.md`:
+Return the assessment as your final response — you do not have a Write tool; the host persists your response verbatim to `{ASSESS_PREFIX}-Concurrency-Assessment.md`. Your entire final response must be this document's content, and nothing else (no preamble, no Markdown code fence wrapping the whole thing):
 
 ```markdown
 # Concurrency Safety Assessment — {ASSESS_PREFIX}

package/src/claude/agents/gaia-generate-requirements.md

@@ -2,7 +2,7 @@
 name: gaia-generate-requirements
 description: "Generates a functional requirements document from a feature description. Input: path to feature.md"
 model: haiku
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep
 ---
 
 # Generate Functional Requirements Document
@@ -20,21 +20,19 @@ The user provides the path to a `feature.md` file. Read it in full before procee
 3. **Identify** all functional areas described
 3. **Extract** actors, use cases, business rules, acceptance criteria
 4. **Organize** into a structured requirements document
-5. **Write** the output to a requirements file in the same directory as the input feature file
+5. **Return** the complete document as your final response — you do not have a Write tool; the host persists your response to `{PREFIX}-Requirements.md` verbatim. Do not attempt to write any file yourself.
 
-## Output Filename
+## Output Filename (for your reference only — you do not write this file)
 
 Extract the **feature prefix** from the folder name containing `feature.md`:
 - Folder: `FTR-001-user-management` → prefix: `FTR-001`
 - Folder: `FTR-042-Search-Engine` → prefix: `FTR-042`
 
-The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`).
-
-Output file: `{PREFIX}-Requirements.md` in the same directory as `feature.md`.
+The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`). Use it in the document's own "Document Info" section; the host, not you, decides the actual output filename.
 
 ## Output Structure
 
-Generate the document in **English** following this template:
+Generate the document in **English** following this template. Your entire final response must be this document's content, and nothing else (no preamble, no "here is the document", no Markdown code fence wrapping the whole thing) — the host writes your response verbatim to disk:
 
 ```markdown
 # Functional Requirements — [Feature Title]

package/src/claude/agents/gaia-generate-tech-spec.md

@@ -2,7 +2,7 @@
 name: gaia-generate-tech-spec
 description: "Generates a technical specification document from a feature description and requirements. Input: path to feature.md"
 model: haiku
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep
 ---
 
 # Generate Technical Specification
@@ -37,21 +37,19 @@ The tech spec MUST use the project's actual stack and patterns. Do not assume an
 3. **Read** `docs/features/REGISTRY.md` if it exists — identify features that touch the same entities, endpoints, or services as this feature. Note architectural dependencies and integration points in Section 5 (External Integrations) or Section 12 (Risks & Mitigations) of the output document. If a prior feature introduced shared infrastructure this feature reuses (e.g. auth middleware, base service, shared DTO), reference it explicitly.
 4. **Explore** the existing codebase areas affected (models, controllers/handlers, pages, services)
 4. **Design** the technical solution aligned with existing patterns from AGENTS.md
-5. **Write** the output to a tech-spec file in the same directory as the input feature file
+5. **Return** the complete document as your final response — you do not have a Write tool; the host persists your response to `{PREFIX}-Tech-Spec.md` verbatim. Do not attempt to write any file yourself.
 
-## Output Filename
+## Output Filename (for your reference only — you do not write this file)
 
 Extract the **feature prefix** from the folder name containing `feature.md`:
 - Folder: `FTR-001-user-management` → prefix: `FTR-001`
 - Folder: `FTR-042-Search-Engine` → prefix: `FTR-042`
 
-The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`).
-
-Output file: `{PREFIX}-Tech-Spec.md` in the same directory as `feature.md`.
+The prefix is everything up to and including the second hyphen-separated segment (pattern: `[A-Z]+-[0-9]+`). Use it in the document's own "Document Info" section; the host, not you, decides the actual output filename.
 
 ## Output Structure
 
-Generate the document in **English** following this template. Adapt section content to the project's actual tech stack (from AGENTS.md):
+Generate the document in **English** following this template. Adapt section content to the project's actual tech stack (from AGENTS.md). Your entire final response must be this document's content, and nothing else (no preamble, no "here is the spec", no Markdown code fence wrapping the whole thing) — the host writes your response verbatim to disk:
 
 ```markdown
 # Technical Specification — [Feature Title]

package/src/claude/agents/gaia-generate-work-breakdown.md

@@ -2,7 +2,7 @@
 name: gaia-generate-work-breakdown
 description: "Generates a structured work breakdown (User Stories + Tasks) from validated and approved Requirements and Tech-Spec. Input: path to feature.md"
 model: haiku
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep
 ---
 
 # Generate Work Breakdown
@@ -186,9 +186,9 @@ Duration guidance:
 
 - `estimate.tokens`: integer; rough estimate of token consumption (input + output) for the agent invocation; use project norms if available, otherwise estimate based on task complexity (small: 10 000–25 000, medium: 25 000–60 000)
 
-### Step 7 — Write the JSON Output
+### Step 7 — Return the JSON Output
 
-Write `{PREFIX}-Work-Breakdown.json` in the same directory as `feature.md`. The file must be:
+Return `{PREFIX}-Work-Breakdown.json`'s content as your final response, and nothing else (no preamble, no explanatory prose, no Markdown code fence wrapping it) — you do not have a Write tool; the host persists your response verbatim to disk. The content must be:
 - Valid JSON
 - UTF-8 encoded
 - 2-space indentation

package/src/claude/agents/gaia-generic-software-assessment.md

@@ -1,7 +1,7 @@
 ---
 name: gaia-generic-software-assessment
 description: "Generic Software Assessment — performs a broad quality analysis across architecture, code quality, security, testability, observability, and DevOps. Reads AGENTS.md for project conventions. Output: {ASSESS_PREFIX}-Generic-Assessment.md"
-tools: Read, Grep, Glob, Bash, Write
+tools: Read, Grep, Glob, Bash
 model: haiku
 ---
 
@@ -112,7 +112,7 @@ Report a score (1–5) for each KPI, where 5 = excellent, 1 = critical issues:
 
 ## Output
 
-Write the assessment to `{ASSESS_PREFIX}-Generic-Assessment.md` in the assessment directory.
+Return the assessment as your final response — you do not have a Write tool; the host persists your response verbatim to `{ASSESS_PREFIX}-Generic-Assessment.md` in the assessment directory. Your entire final response must be this document's content, and nothing else (no preamble, no "here is the assessment", no Markdown code fence wrapping the whole thing):
 
 ```markdown
 # Generic Software Assessment — {ASSESS_PREFIX}

package/src/claude/agents/gaia-intervention-documentation-standard.md

@@ -2,7 +2,7 @@
 name: gaia-intervention-documentation-standard
 description: "Intervention Documentation Standard — generates structured, self-contained intervention documents from assessment findings. Each document is independently actionable by an architect or developer agent. Input: assessment findings; Output: {ASSESS_PREFIX}-INT-NNN-{slug}.md per finding + Interventions-Index.md"
 model: sonnet
-tools: Read, Grep, Glob, Bash, Write
+tools: Read, Grep, Glob, Bash
 ---
 
 # Intervention Documentation Standard
@@ -117,7 +117,7 @@ References to assessment findings (`{ASSESS_PREFIX}-G-NNN`), related ADRs, relat
 
 ## Interventions Index
 
-After writing all intervention documents, produce `{ASSESS_PREFIX}-Interventions-Index.md`:
+Alongside the intervention documents, compose one more file, `{ASSESS_PREFIX}-Interventions-Index.md`:
 
 ```markdown
 # Interventions Index — {ASSESS_PREFIX}
@@ -130,3 +130,26 @@ After writing all intervention documents, produce `{ASSESS_PREFIX}-Interventions
 ```
 
 Order by criticality (CRITICAL first), then by dependency (prerequisites before dependents).
+
+---
+
+## Output Contract (MANDATORY — your final response)
+
+You do not have a Write tool. You produce a **variable number of files** (one per intervention, plus the index) whose names you yourself decide (the `{area-slug}` in each filename), so the host cannot know their paths in advance the way it does for a single fixed deliverable — you must declare each file's path and content yourself, and the host validates and persists every one of them.
+
+Return a single JSON object with exactly this shape, without Markdown fences or explanatory prose:
+
+```json
+{
+  "files": [
+    { "path": "{ASSESS_PREFIX}-INT-001-sql-injection-hardening.md", "content": "# ...full document content..." },
+    { "path": "{ASSESS_PREFIX}-INT-002-god-class-decomposition.md", "content": "# ...full document content..." },
+    { "path": "{ASSESS_PREFIX}-Interventions-Index.md", "content": "# Interventions Index — {ASSESS_PREFIX}\n\n| ID | ... |\n..." }
+  ]
+}
+```
+
+- `files` is a non-empty array. Every intervention document you decided to write, plus the index, must appear here — there is no separate Write step and nothing you do not include in this array reaches disk.
+- Each `path` is a bare filename (no directory components) — the host resolves it against the assessment output directory itself; never include `docs/`, `..`, or an absolute path.
+- Each `content` is that file's complete, final content, verbatim — exactly as the host will write it byte-for-byte.
+- The caller supplies `--json-schema`; use the runtime's structured-output mechanism to return this object in `structured_output`. Plain-text JSON alone does not satisfy that contract.

package/src/claude/agents/gaia-layered-architecture-assessment.md

@@ -1,7 +1,7 @@
 ---
 name: gaia-layered-architecture-assessment
 description: "Layered Architecture Assessment — audits a codebase for layer boundary violations, missing separation of concerns, and namespace/package misalignment. Produces a violation inventory and a recommended layer model. Language-agnostic; reads AGENTS.md for project conventions. Output: {ASSESS_PREFIX}-Layer-Assessment.md"
-tools: Read, Grep, Glob, Bash, Write
+tools: Read, Grep, Glob, Bash
 model: haiku
 ---
 
@@ -135,7 +135,7 @@ Report the current state and recommend the appropriate option based on team size
 
 ## Output
 
-Write to `{ASSESS_PREFIX}-Layer-Assessment.md`:
+Return the assessment as your final response — you do not have a Write tool; the host persists your response verbatim to `{ASSESS_PREFIX}-Layer-Assessment.md`. Your entire final response must be this document's content, and nothing else (no preamble, no Markdown code fence wrapping the whole thing):
 
 ```markdown
 # Layered Architecture Assessment — {ASSESS_PREFIX}

package/src/claude/agents/gaia-validate-feature-docs.md

@@ -1,8 +1,8 @@
 ---
 name: gaia-validate-feature-docs
-description: "Validates Requirements and Tech-Spec documents against feature.md. Writes a validation report and returns a structured verdict; the host owns revisions. Input: path to feature.md"
+description: "Validates Requirements and Tech-Spec documents against feature.md. Returns the validation report content and a structured verdict; the host persists the report and owns revisions. Input: path to feature.md"
 model: haiku
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep
 ---
 
 # Validate Feature Docs
@@ -111,13 +111,13 @@ Use the same remaining gaps in the report and the structured verdict. Record a g
 
 ---
 
-## Phase 6 — Write Validation Report (MANDATORY — before returning the verdict)
+## Phase 6 — Compose the Validation Report Content (MANDATORY — before returning the verdict)
 
-**This is not optional and not the same as the Phase 4 gap report.** The coverage report you produced in Phase 4 is on-screen text; it is NOT the deliverable. Your job is not complete until the file `{PREFIX}-Validation-Report.md` exists **on disk**. You MUST call the `Write` tool to create it — even when validation is clean and zero gaps were found. Returning a summary without having called `Write` is a failure.
+**This is not optional and not the same as the Phase 4 gap report.** The coverage report you produced in Phase 4 is on-screen text; it is NOT the deliverable. You do not have a Write tool — the deliverable is the `report` field of your Phase 7 structured output, which the host persists to `{PREFIX}-Validation-Report.md` verbatim. Returning a verdict without a complete `report` field is a failure.
 
-Execute this phase regardless of the validation outcome, then complete Phase 7. Downstream agents read this file as a hard precondition; if it is missing, the entire pipeline aborts.
+Execute this phase regardless of the validation outcome, then complete Phase 7. Downstream agents read the persisted file as a hard precondition; if the `report` field is missing or empty, the entire pipeline aborts.
 
-Write `{PREFIX}-Validation-Report.md` in the same directory:
+Compose `{PREFIX}-Validation-Report.md`'s full content following this template:
 
 ```markdown
 # Validation Report — {PREFIX}
@@ -146,22 +146,23 @@ Write `{PREFIX}-Validation-Report.md` in the same directory:
 
 ## Phase 7 — Structured Completion (MANDATORY — your final response)
 
-After writing the report, return a single JSON object with exactly these fields, without Markdown fences or explanatory prose:
+Return a single JSON object with exactly these fields, without Markdown fences or explanatory prose:
 
 ```json
-{"valid": true, "findings": []}
+{"valid": true, "findings": [], "report": "# Validation Report — FTR-001\n\n## Summary\n..."}
 ```
 
 For remaining gaps:
 
 ```json
-{"valid": false, "findings": ["Requirements: UC-01 lacks an acceptance criterion", "Tech-Spec: POST /api/users lacks a response definition"]}
+{"valid": false, "findings": ["Requirements: UC-01 lacks an acceptance criterion", "Tech-Spec: POST /api/users lacks a response definition"], "report": "# Validation Report — FTR-001\n\n## Summary\n..."}
 ```
 
 - `valid` is a boolean: `true` only when all required inputs were read, coverage is complete, and no unresolved gaps remain.
 - `findings` is an array of strings, empty only for a clean validation. Missing inputs and ambiguous claims are unresolved findings.
-- When the caller supplies `--json-schema`, use the runtime's structured-output mechanism to return this object in `structured_output`. Plain-text JSON alone does not satisfy that contract.
-- Both deliverables are required: the report on disk **and** the structured verdict. Writing the report does not finish the task.
+- `report` is a non-empty string: the complete Phase 6 document content, verbatim, as the host will write it byte-for-byte to `{PREFIX}-Validation-Report.md`.
+- The caller supplies `--json-schema`; use the runtime's structured-output mechanism to return this object in `structured_output`. Plain-text JSON alone does not satisfy that contract.
+- There is only one deliverable now: the structured verdict, with `report` inside it. There is no separate Write step.
 
 ## Clarification Protocol
 
@@ -171,7 +172,7 @@ If a claim is contradictory or its correct resolution is ambiguous, do not guess
 
 ## Guidelines
 
-- **Always call `Write` for the Validation Report before returning the structured verdict** (Phases 6 and 7), clean or not.
+- **Always include the complete report content in the `report` field of your structured verdict** (Phases 6 and 7), clean or not — there is no Write tool to fall back on.
 - **Validate only** — the host owns document revisions and agent dispatch
 - **Be specific about gaps** — point to the exact section, claim, and what is missing
 - **Perform one validation pass per invocation** — return remaining gaps to the host

package/src/claude/workflows/am-phase1.js

@@ -29,20 +29,35 @@ return c.run(meta.name, outputDir, prefix, async () => {
     const id = SCOPE_AGENT_MAP[area]
     groups.set(id, [...(groups.get(id) || []), area])
   }
+  // Neither assessor below has a Write tool: each returns its report as plain response
+  // text, which the host persists to its declared `outputs` path (see worker()'s own
+  // comment in lib/workflow-control.js for why — "Never ask an LLM to do I/O").
   const assessmentResults = await c.parallel([...groups].map(([id, areas]) => async () => {
+    const suffix = { 'gaia.agent.assessment.generic': 'Generic', 'gaia.agent.assessment.layered-architecture': 'Layer', 'gaia.agent.assessment.concurrency': 'Concurrency' }[id]
+    const output_file = `${outputDir}/${prefix}-${suffix}-Assessment.md`
     const result = await c.worker(id,
       `${targetPath} --prefix ${prefix} --output-dir ${outputDir}\n` +
       `Read-only assessment. Explicit scope: ${areas.join(', ')}. Inspect risks, evidence, severity and recommendations for EACH listed scope. ` +
       'For security inspect trust boundaries and authorization; devops: build/deploy/observability; domain-model: invariants and ownership; dependencies: versions, provenance and supply-chain risks. ' +
-      'Do not remediate code or dispatch remediation agents. Write your assessment report in the output directory.')
-    const suffix = { 'gaia.agent.assessment.generic': 'Generic', 'gaia.agent.assessment.layered-architecture': 'Layer', 'gaia.agent.assessment.concurrency': 'Concurrency' }[id]
-    const output_file = `${outputDir}/${prefix}-${suffix}-Assessment.md`
-    if (!c.read(output_file).trim()) throw new Error('Assessment report empty: ' + output_file)
+      'Do not remediate code or dispatch remediation agents. Return your assessment report as your final response.',
+      { outputs: [{ path: output_file }] })
     return { agent: id, scopes: areas, result, output_file }
   }))
-  await c.worker('gaia.agent.assessment.intervention-documentation',
+  // intervention-documentation-standard writes a variable number of files (one per
+  // intervention plus an index) whose names it decides itself, so it cannot use the
+  // single static `outputs` contract above — it declares each {path, content} pair in
+  // its own structured_output, and the host validates and persists every one of them.
+  const docs = await c.worker('gaia.agent.assessment.intervention-documentation',
     `--prefix ${prefix} --output-dir ${outputDir} --target ${targetPath}\nUse only the reports from these assessors: ${[...groups.keys()].join(', ')}.\n` +
-    assessmentResults.map(r => `${r.agent}: ${typeof r.result === 'string' ? r.result : JSON.stringify(r.result)}`).join('\n'))
+    assessmentResults.map(r => `${r.agent}: ${typeof r.result === 'string' ? r.result : JSON.stringify(r.result)}`).join('\n'),
+    { schema: { type: 'object', properties: { files: { type: 'array', items: { type: 'object',
+      properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] } } }, required: ['files'] } })
+  if (!docs.files.length) throw new Error('Intervention documentation produced no files')
+  for (const f of docs.files) {
+    if (!f.path || /[\\/]/.test(f.path) || f.path.includes('..')) throw new Error('Invalid intervention document path: ' + f.path)
+    if (!f.content || !f.content.trim()) throw new Error('Empty intervention document: ' + f.path)
+    c.writeOutput(`${outputDir}/${f.path}`, f.content)
+  }
   const metrics = c.assessmentEstimates(outputDir, prefix)
   return { prefix, output_dir: outputDir, target_path: targetPath,
     assessment_summaries: assessmentResults.map(({ agent, scopes, output_file }) => ({ agent, scopes, output_file })),

package/src/claude/workflows/pm-phase1.js

@@ -14,21 +14,24 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const reqId = 'gaia.agent.planner.requirements'
   const specId = 'gaia.agent.planner.tech-spec'
   const valId = 'gaia.agent.planner.validate-feature-docs'
+  const output = (suffix, inputs = [featurePath]) => ({ path: file(suffix), inputs })
+  const requirements = () => c.worker(reqId, featurePath, { outputs: [output('Requirements')] })
+  const techSpec = () => c.worker(specId, featurePath, { outputs: [output('Tech-Spec', [featurePath, file('Requirements')])] })
   let changed = false
   if (force || !fresh(file('Requirements'))) {
-    await c.worker(reqId, featurePath)
+    await requirements()
     if (!c.exists(file('Requirements'))) throw new Error('Requirements output missing')
     changed = true
   }
   if (force || changed || !fresh(file('Tech-Spec'), [featurePath, file('Requirements')])) {
-    await c.worker(specId, featurePath)
+    await techSpec()
     if (!c.exists(file('Tech-Spec'))) throw new Error('Tech-Spec output missing')
     changed = true
   }
   let validationSummary = 'skipped (fresh)'
   if (force || changed || !fresh(file('Validation-Report'), [featurePath, file('Requirements'), file('Tech-Spec')])) {
     for (let cycle = 1; cycle <= 3; cycle++) {
-      const result = await c.worker(valId, featurePath + '\nValidate only; the host owns the revision loop. Write the validation report and return valid plus a findings array (one string per remaining gap). Do not dispatch other agents.', { label: `validation:${cycle}`, schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } } }, required: ['valid', 'findings'] } })
+      const result = await c.worker(valId, featurePath + '\nValidate only; the host owns the revision loop. Return valid, a findings array (one string per remaining gap), and the full validation report content. Do not dispatch other agents.', { label: `validation:${cycle}`, outputs: [output('Validation-Report', [featurePath, file('Requirements'), file('Tech-Spec')])], schema: { type: 'object', properties: { valid: { type: 'boolean' }, findings: { type: 'array', items: { type: 'string' } }, report: { type: 'string' } }, required: ['valid', 'findings', 'report'] } })
       const text = result.findings.join('\n')
       if (result.valid && result.findings.length === 0) {
         if (!fresh(file('Validation-Report'), [featurePath, file('Requirements'), file('Tech-Spec')])) throw new Error('Validation agent did not produce its report')
@@ -36,8 +39,8 @@ return c.run(meta.name, featureDir, prefix, async () => {
         break
       }
       if (cycle === 3) throw new Error('Validation gaps remain after 3 cycles')
-      if (!text.includes('Tech-Spec') || text.includes('Requirements')) await c.worker(reqId, featurePath)
-      if (!text.includes('Requirements') || text.includes('Tech-Spec')) await c.worker(specId, featurePath)
+      if (!text.includes('Tech-Spec') || text.includes('Requirements')) await requirements()
+      if (!text.includes('Requirements') || text.includes('Tech-Spec')) await techSpec()
     }
   }
   c.append(`${featureDir}/${prefix}-process-log.txt`, `[${new Date().toISOString()}] pm-phase1: ${validationSummary}; Gate 1 approval requested\n`)

package/src/claude/workflows/pm-phase2.js

@@ -14,8 +14,10 @@ return c.run(meta.name, featureDir, prefix, async () => {
   const approvals = c.read(file('Approvals.md'))
   const gate = approvals.match(/^## Gate 1\b[^\n]*\n([\s\S]*?)(?=^## |$(?![\s\S]))/m)
   if (!gate || !/✅\s*Approved/.test(gate[1])) throw new Error('Gate 1 approval evidence missing')
-  await c.worker('gaia.agent.planner.work-breakdown', featurePath)
   const jsonPath = file('Work-Breakdown.json')
+  await c.worker('gaia.agent.planner.work-breakdown', featurePath, {
+    outputs: [{ path: jsonPath, inputs: [featurePath, file('Requirements.md'), file('Tech-Spec.md')] }],
+  })
   const report = await c.activity('wb-validate', async () => {
     const res = c.command(['run-asset', 'scripts/wb-validate.js', '--project', c.root,
       '--', jsonPath, file('Requirements.md')], [0, 1])