@bastani/atomic 0.8.29-alpha.3 → 0.8.29

package/dist/builtin/subagents/src/runs/shared/subagent-prompt-runtime.ts

@@ -11,13 +11,6 @@ import type { JsonSchemaObject } from "../../shared/types.ts";
 
 export { SUBAGENT_INTERCOM_SESSION_NAME_ENV } from "./pi-args.ts";
 
-const STRUCTURED_OUTPUT_INSTRUCTIONS = [
-	"This subagent step has a strict structured output contract.",
-	"Your final action must be to call the `structured_output` tool with JSON matching the provided schema.",
-	"Pass the schema fields directly as the tool arguments; do not wrap them in `{ value: ... }` unless the schema explicitly defines a top-level `value` field.",
-	"Do not rely on prose-only completion; if you do not call `structured_output`, the parent will fail this step.",
-].join("\n");
-
 export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
 	"You are a child subagent, not the parent orchestrator.",
 	"The parent session owns delegation, orchestration, review fanout, and follow-up worker launches.",
@@ -107,8 +100,7 @@ export function rewriteSubagentPrompt(
 	rewritten = stripSubagentOrchestrationSkill(rewritten);
 	rewritten = stripChildBoundaryInstructions(rewritten);
 	const boundary = options.fanoutChild ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
-	const structured = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV] ? `\n\n${STRUCTURED_OUTPUT_INSTRUCTIONS}` : "";
-	return `${boundary}${structured}\n\n${rewritten}`;
+	return `${boundary}\n\n${rewritten}`;
 }
 
 function isParentOnlySubagentMessage(message: unknown): boolean {

package/dist/builtin/subagents/src/shared/types.ts

@@ -803,7 +803,6 @@ export interface RunSyncOptions {
 		schema: JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
-		metadataPath: string;
 	};
 	acceptance?: AcceptanceInput;
 	acceptanceContext?: {

package/dist/builtin/subagents/src/slash/saved-chain-mapping.ts

@@ -1,36 +1,22 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ChainConfig } from "../agents/agents.ts";
-import { assertJsonSchemaDescriptor, assertStructuredOutputParameterSchema } from "../runs/shared/structured-output.ts";
 import { isDynamicParallelStep, isParallelStep, type ChainStep } from "../shared/settings.ts";
 import type { JsonSchemaObject } from "../shared/types.ts";
 
 function loadSavedOutputSchema(
 	chain: ChainConfig,
-	stepAgent: string,
+	_stepAgent: string,
 	outputSchema: unknown,
-	options: { schemaRole: "tool-parameters" | "collection" } = { schemaRole: "tool-parameters" },
 ): JsonSchemaObject | undefined {
 	if (outputSchema === undefined) return undefined;
-	const labelForSchema = (schemaPath?: string): string => schemaPath
-		? `outputSchema for chain '${chain.name}' step '${stepAgent}' (${schemaPath})`
-		: `outputSchema for chain '${chain.name}' step '${stepAgent}'`;
-	const validateSavedSchema = (schema: unknown, label: string): JsonSchemaObject => {
-		if (options.schemaRole === "collection") {
-			assertJsonSchemaDescriptor(schema, label);
-		} else {
-			assertStructuredOutputParameterSchema(schema, label);
-		}
-		return schema;
-	};
 	if (typeof outputSchema === "string") {
 		const schemaPath = path.isAbsolute(outputSchema)
 			? outputSchema
 			: path.join(path.dirname(chain.filePath), outputSchema);
-		const parsed = JSON.parse(fs.readFileSync(schemaPath, "utf-8")) as unknown;
-		return validateSavedSchema(parsed, labelForSchema(schemaPath));
+		return JSON.parse(fs.readFileSync(schemaPath, "utf-8")) as JsonSchemaObject;
 	}
-	return validateSavedSchema(outputSchema, labelForSchema());
+	return outputSchema as JsonSchemaObject;
 }
 
 export function mapSavedChainSteps(chain: ChainConfig, worktree = false): ChainStep[] {
@@ -50,7 +36,6 @@ export function mapSavedChainSteps(chain: ChainConfig, worktree = false): ChainS
 				chain,
 				`${step.collect.as} collection`,
 				step.collect.outputSchema,
-				{ schemaRole: "collection" },
 			);
 			return {
 				...step,

package/dist/builtin/web-access/CHANGELOG.md

@@ -4,9 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.29] - 2026-06-15
+
 ### Changed
 
-- Published a synchronized Atomic 0.8.29-alpha.1 prerelease with the upstream pi TUI dependency aligned to `^0.79.3`; no functional changes were made in the web-access extension.
+- Published a synchronized Atomic 0.8.29 stable release with the upstream pi TUI dependency aligned to `^0.79.3`; no functional changes were made in the web-access extension.
 
 ## [0.8.28] - 2026-06-11
 

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.29-alpha.3",
+  "version": "0.8.29",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,9 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.8.29] - 2026-06-15
+
 ### Added
 
-- Added opt-in schema-backed workflow item results: `ctx.stage(..., { schema })`, `ctx.task(..., { schema })`, `ctx.chain` items, and `ctx.parallel` items now receive a schema-specific `structured_output` tool only for that item, require the final tool call, return the parsed value from `ctx.stage().prompt(...)`, and expose parsed task values as `result.structured` while preserving formatted JSON handoff text ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Added opt-in schema-backed workflow item results: `ctx.stage(..., { schema })`, `ctx.task(..., { schema })`, `ctx.chain` items, and `ctx.parallel` items now receive a schema-specific `structured_output` tool only for that item, return the captured value from `ctx.stage().prompt(...)`, and expose parsed task values as `result.structured` while preserving formatted JSON handoff text ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 
 ### Changed
 
@@ -17,13 +19,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Changed the builtin `ralph` prompt-engineering stage to disable all tools while relying on the `/skill:prompt-engineer` skill prompt, keeping that first-pass rewrite focused and tool-free.
 - Changed builtin `goal` worker/reviewer prompts and `ralph` orchestrator/reviewer prompts to request end-to-end verification when practical, using browser-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios.
 - Aligned the workflows extension with upstream pi TUI `^0.79.3` so workflow graph, custom UI, and prompt-broker integrations inherit the latest shared TUI compatibility fixes.
-- Documented the opt-in `structured_output` workflow path and clarified that ordinary workflow stages do not receive `structured_output` from the default tool registry; schema-enabled items auto-add the runtime tool to explicit `tools` allowlists ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
-- Clarified that workflow `structured_output` gate schemas must be top-level object tool-argument schemas, with arrays and primitives wrapped in object fields before being returned through the terminating tool, and documented the one-`prompt()` limit for schema-backed `StageContext` result contracts ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
-- Documented that terminating workflow-stage `structured_output` JSON stays inline even when large, while artifact-sized handoffs should still be saved to files when downstream stages do not need the full payload in context ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Documented the opt-in `structured_output` workflow path and clarified that ordinary workflow stages do not receive `structured_output` from the default tool registry; schema-enabled items auto-add the runtime tool to explicit `tools` allowlists without adding extra workflow prompt text about the tool ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Removed top-level-object restrictions from workflow `structured_output` gate schemas; Atomic now passes any plain JSON Schema object directly to the tool and documents the one-`prompt()` limit for schema-backed `StageContext` result contracts ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 
 ### Fixed
 
-- Fixed direct workflow tool validation so schema-enabled `task`, `tasks`, `chain`, and `parallel` items reject array or primitive structured-output schemas at argument-validation time while accepting the same object-root contracts as runtime validation, including object-only `allOf` schemas ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed direct workflow tool validation so schema-enabled `task`, `tasks`, `chain`, and `parallel` items accept plain JSON Schema objects without additional object-root constraints ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 - Fixed schema-backed workflow stages to fail with a clear stage-level error when `prompt()` is called more than once on the same `StageContext`, rather than surfacing the lower-level structured-output single-use guard ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 - Fixed schema-backed workflow model fallback so an attempt that already captured a valid terminating `structured_output` result is treated as successful instead of retrying against fallback models and tripping the single-use result guard ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 - Fixed the workflow graph overlay remaining interactive when the parent/main-chat agent opens `ask_user_question`: the graph keeps focus, the parent question stays pending behind it with a clear “Main chat needs input — exit graph to answer.” status hint, hiding/exiting the graph focuses the pending question, and host custom-UI state changes no longer hide, restore, remount, or repaint the overlay ([#1353](https://github.com/bastani-inc/atomic/issues/1353)).

package/dist/builtin/workflows/README.md

@@ -280,7 +280,7 @@ const decision = await ctx.stage("review-gate", { schema: Decision }).prompt(
 // decision.approved is typed from the schema.
 ```
 
-Atomic registers the canonical `structured_output` tool only for schema-enabled items, automatically adds it to explicit `tools` allowlists, and fails the item if the model completes without the final tool call. The schema is used directly as the tool argument contract, so wrap arrays or primitives in an object field such as `{ items: [...] }` or `{ value: ... }`. A schema-backed `StageContext` supports one `prompt()` call because the final-answer tool is an exact-once result contract; create another `ctx.stage(..., { schema })` for another structured prompt. `ctx.task`/`ctx.chain`/`ctx.parallel` results expose the parsed value as `result.structured` and keep `result.text` as formatted JSON for handoffs.
+Atomic registers the canonical `structured_output` tool only for schema-enabled items and automatically adds it to explicit `tools` allowlists. The schema is used directly as the tool argument contract. A schema-backed `StageContext` supports one `prompt()` call because the final-answer tool is a single result contract; create another `ctx.stage(..., { schema })` for another structured prompt. `ctx.task`/`ctx.chain`/`ctx.parallel` results expose the captured value as `result.structured` and keep `result.text` as formatted JSON for handoffs.
 
 `subagent` is available as a default workflow-stage tool with the same default two-hop nesting budget as main chat: a stage can launch a subagent, and that child can launch one nested subagent before the guard blocks further delegation. `tools` allowlists apply to bundled extension tools as well as built-ins; if a stage sets `tools`, list every tool it should see. Workflow stages can explicitly list `subagent`, `web_search`, `fetch_content`, `intercom`, and other loaded extension tools, while `excludedTools` and `noTools: "all"` still win. Bundled `@bastani/subagents` agent definitions are available to the `subagent` tool in workflow stages, including workflows launched from a subagent child process.
 

package/dist/builtin/workflows/builtin/goal.ts

@@ -314,26 +314,8 @@ function normalizeBranchInput(
   return looksLikeSafeGitRef ? trimmed : fallback;
 }
 
-function parseReviewDecision(text: string): ReviewDecision | undefined {
-  try {
-    const parsed = JSON.parse(text) as Partial<ReviewDecision>;
-    if (
-      parsed.overall_correctness !== "patch is correct" &&
-      parsed.overall_correctness !== "patch is incorrect"
-    ) {
-      return undefined;
-    }
-    if (!Array.isArray(parsed.findings)) return undefined;
-    if (typeof parsed.stop_review_loop !== "boolean") return undefined;
-    if (typeof parsed.overall_explanation !== "string") return undefined;
-    if (typeof parsed.overall_confidence_score !== "number") return undefined;
-    if (typeof parsed.goal_oracle_satisfied !== "boolean") return undefined;
-    if (typeof parsed.receipt_assessment !== "string") return undefined;
-    if (typeof parsed.verification_remaining !== "string") return undefined;
-    return parsed as ReviewDecision;
-  } catch {
-    return undefined;
-  }
+function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDecision | undefined {
+  return result.structured as ReviewDecision | undefined;
 }
 
 function reviewApproved(decision: ReviewDecision): boolean {
@@ -872,37 +854,9 @@ function renderReviewerPrompt(args: {
     [
       "output_format",
       [
-        "Use the schema-backed structured_output tool after your investigation and validation attempts.",
-        "The tool terminates the turn and provides the structured data; do not emit a separate final assistant response after calling it.",
-        "The review gate decides completion only from the JSON object captured by structured_output; invalid JSON, missing fields, reviewer_error, or stop_review_loop=false are treated as not approved for safety.",
         "Set stop_review_loop=true only when there are no P0/P1/P2 findings, overall_correctness is patch is correct, goal_oracle_satisfied is true, no objective-relevant verification remains, and reviewer_error is null/omitted.",
         "P3 nice-to-have findings are non-blocking when the rest of the approval contract is satisfied; do not use P3 for work required by the objective or verification oracle.",
-        "If you hit a reviewer/tool/validation error, still return the object with stop_review_loop=false and reviewer_error populated instead of pretending the patch is approved.",
-        [
-          "The structured_output schema is authoritative; do not copy a hand-written JSON blob into the final response. Here is an example output:",
-          "{",
-          '  "findings": [',
-          "    {",
-          '      "title": "<≤ 80 chars, imperative, starts with [P0]/[P1]/[P2]/[P3]>",',
-          '      "body": "<one paragraph of valid Markdown explaining why this is a problem; cite files/lines/functions>",',
-          '      "confidence_score": <float 0.0-1.0>,',
-          '      "priority": <int 0-3 or null>,',
-          '      "code_location": {',
-          '        "absolute_file_path": "<absolute file path>",',
-          '        "line_range": {"start": <int>, "end": <int>}',
-          "      }",
-          "    }",
-          "  ],",
-          '  "overall_correctness": "patch is correct" | "patch is incorrect",',
-          '  "overall_explanation": "<1-3 sentence explanation justifying the verdict>",',
-          '  "overall_confidence_score": <float 0.0-1.0>,',
-          '  "goal_oracle_satisfied": <boolean>,',
-          '  "receipt_assessment": "<how receipts/current evidence map to the verification oracle>",',
-          '  "verification_remaining": "<oracle-relevant verification still missing, or none>",',
-          '  "stop_review_loop": <boolean>,',
-          '  "reviewer_error": null | {"kind": "validation_unavailable" | "dependency_unavailable" | "tool_failure" | "reviewer_failure", "message": "<what failed>", "attempted_recovery": "<what you tried>"}',
-          "}",
-        ].join("\n"),
+        "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved.",
       ].join("\n"),
     ],
   ]);
@@ -1169,20 +1123,22 @@ export default defineWorkflow("goal")
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        const structured = reviewerErrorDecision(message);
         reviewResults = [
           {
             name: `reviewer-error-${turn}`,
             stageName: `reviewer-error-${turn}`,
-            text: JSON.stringify(reviewerErrorDecision(message), null, 2),
+            text: JSON.stringify(structured, null, 2),
+            structured,
           },
         ];
       }
 
       latestReviews = await Promise.all(reviewResults.map(async (result) => {
         const reviewerName = result.name ?? result.stageName;
-        const parsed = parseReviewDecision(result.text) ??
+        const parsed = reviewDecisionFromResult(result) ??
           reviewerErrorDecision(
-            `Reviewer ${reviewerName} returned invalid structured JSON.`,
+            `Reviewer ${reviewerName} returned no structured decision.`,
           );
         const reviewArtifactPath = await writeReviewArtifact(
           artifactDir,

package/dist/builtin/workflows/builtin/open-claude-design.ts

@@ -144,41 +144,20 @@ const exportGateDecisionSchema = Type.Object(
   { additionalProperties: false },
 );
 
-function parseRefinementDecision(text: string): RefinementDecision {
-  const parsed = JSON.parse(text) as Partial<RefinementDecision>;
-  if (typeof parsed.ready_for_export !== "boolean") {
-    throw new Error("open-claude-design refinement decision missing ready_for_export.");
+function refinementDecisionFromResult(result: WorkflowTaskResult): RefinementDecision {
+  const decision = result.structured as RefinementDecision | undefined;
+  if (!decision) {
+    throw new Error("open-claude-design refinement decision missing structured result.");
   }
-  return {
-    ready_for_export: parsed.ready_for_export,
-    rationale: typeof parsed.rationale === "string" ? parsed.rationale : "",
-    required_changes: Array.isArray(parsed.required_changes)
-      ? parsed.required_changes.filter((item): item is string => typeof item === "string")
-      : [],
-  };
+  return decision;
 }
 
-function parseExportGateDecision(text: string): ExportGateDecision {
-  const parsed = JSON.parse(text) as Partial<ExportGateDecision>;
-  if (typeof parsed.has_blocking_findings !== "boolean") {
-    throw new Error("open-claude-design export gate decision missing has_blocking_findings.");
+function exportGateDecisionFromResult(result: WorkflowTaskResult): ExportGateDecision {
+  const decision = result.structured as ExportGateDecision | undefined;
+  if (!decision) {
+    throw new Error("open-claude-design export gate decision missing structured result.");
   }
-  return {
-    has_blocking_findings: parsed.has_blocking_findings,
-    rationale: typeof parsed.rationale === "string" ? parsed.rationale : "",
-    blocking_findings: Array.isArray(parsed.blocking_findings)
-      ? parsed.blocking_findings.filter(
-          (item): item is ExportGateFinding =>
-            typeof item === "object" &&
-            item !== null &&
-            "finding" in item &&
-            "evidence" in item &&
-            "why_blocking" in item &&
-            "must_fix_action" in item &&
-            "severity" in item,
-        )
-      : [],
-  };
+  return decision;
 }
 
 function joinResults(results: readonly WorkflowTaskResult[]): string {
@@ -805,7 +784,7 @@ export default defineWorkflow("open-claude-design")
             [
               "1. If a previous `preview-display-*` step captured annotated user feedback or notes, honor them as the primary signal.",
               "2. Otherwise, you may inspect the HTML file at preview_path directly (read it from disk) and run an impeccable `critique` against it.",
-              "3. Decide whether the current design is ready for export using the schema-backed structured_output tool.",
+              "3. Decide whether the current design is ready for export.",
               "4. If refinement is still needed, put specific changes in required_changes ordered by user value and implementation risk.",
               "5. Never request changes that contradict DESIGN.md unless you explicitly identify and explain the conflict.",
             ].join("\n"),
@@ -813,7 +792,6 @@ export default defineWorkflow("open-claude-design")
           [
             "output_format",
             [
-              "Call structured_output after your inspection.",
               "Set ready_for_export=true only when the current preview needs no further refinement before export.",
               "Set ready_for_export=false and populate required_changes when another polish iteration is needed.",
             ].join("\n"),
@@ -823,7 +801,7 @@ export default defineWorkflow("open-claude-design")
         ...refinementDecisionConfig,
       });
 
-      const feedbackDecision = parseRefinementDecision(feedback.text);
+      const feedbackDecision = refinementDecisionFromResult(feedback);
       if (feedbackDecision.ready_for_export) {
         approvedForExport = true;
         break;
@@ -1013,14 +991,13 @@ export default defineWorkflow("open-claude-design")
             "1. Read the HTML at preview_path and score it across all five audit dimensions.",
             "2. Scan for banned anti-patterns, accessibility blockers, severe visual regressions, missing critical states, and handoff gaps.",
             "3. Only mark findings as blocking when they would materially harm implementation or user experience (impeccable P0 severity).",
-            "4. Decide whether export is blocked using the schema-backed structured_output tool.",
+            "4. Decide whether export is blocked.",
             "5. Every blocking finding must include selector-level evidence and a must-fix action.",
           ].join("\n"),
         ],
         [
-          "output_format",
+          "decision_rules",
           [
-            "Call structured_output after the audit.",
             "Set has_blocking_findings=true only when one or more P0 findings block export.",
             "Populate blocking_findings with every blocking P0 issue; leave it empty when export is safe.",
           ].join("\n"),
@@ -1030,7 +1007,7 @@ export default defineWorkflow("open-claude-design")
       ...exportGateDecisionConfig,
     });
 
-    const exportGateDecision = parseExportGateDecision(preExport.text);
+    const exportGateDecision = exportGateDecisionFromResult(preExport);
     if (exportGateDecision.has_blocking_findings) {
       const forcedFix = await ctx.task("forced-fix", {
         prompt: taggedPrompt([

package/dist/builtin/workflows/builtin/ralph.ts

@@ -189,23 +189,8 @@ async function createImplementationNotesFile(prompt: string): Promise<string> {
   return notesPath;
 }
 
-function parseReviewDecision(text: string): ReviewDecision | undefined {
-  try {
-    const parsed = JSON.parse(text) as Partial<ReviewDecision>;
-    if (
-      parsed.overall_correctness !== "patch is correct" &&
-      parsed.overall_correctness !== "patch is incorrect"
-    ) {
-      return undefined;
-    }
-    if (!Array.isArray(parsed.findings)) return undefined;
-    if (typeof parsed.stop_review_loop !== "boolean") return undefined;
-    if (typeof parsed.overall_explanation !== "string") return undefined;
-    if (typeof parsed.overall_confidence_score !== "number") return undefined;
-    return parsed as ReviewDecision;
-  } catch {
-    return undefined;
-  }
+function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDecision | undefined {
+  return result.structured as ReviewDecision | undefined;
 }
 
 function reviewDecisionApproved(decision: ReviewDecision): boolean {
@@ -237,10 +222,12 @@ function reviewerErrorDecision(error: string): ReviewDecision {
 function reviewerErrorResult(
   error: string,
 ): WorkflowTaskResult {
+  const structured = reviewerErrorDecision(error);
   return {
     name: "reviewer-error",
     stageName: "reviewer-error",
-    text: JSON.stringify(reviewerErrorDecision(error), null, 2),
+    text: JSON.stringify(structured, null, 2),
+    structured,
   };
 }
 
@@ -766,7 +753,7 @@ async function runRalphWorkflow(
         ].join("\n"),
       ],
       [
-        "required_actions_before_tool_call",
+        "action_items",
         [
           "1. Identify the changed files or diff under review.",
           "2. Read the relevant changed code and directly affected call sites/tests/configs.",
@@ -782,36 +769,10 @@ async function runRalphWorkflow(
         ].join("\n"),
       ],
       [
-        "structured_output_contract",
+        "decision_rules",
         [
-          "Use the schema-backed structured_output tool after your investigation and validation attempts.",
-          "The tool terminates the turn and provides the structured data; do not emit a separate final assistant response after calling it.",
-          "The review loop decides whether to stop only from the JSON object captured by structured_output; invalid JSON, missing fields, reviewer_error, or stop_review_loop=false are treated as not approved for safety.",
           "Set stop_review_loop=true only when findings is empty, overall_correctness is patch is correct, and reviewer_error is null/omitted.",
-          "If you hit a reviewer/tool/validation error, still return the object with stop_review_loop=false and reviewer_error populated instead of pretending the patch is approved.",
-          "The structured_output schema is authoritative; do not copy a hand-written JSON blob into the final response. Here is an example output:",
-          "{",
-          '  "findings": [',
-          "    {",
-          '      "title": "<≤ 80 chars, imperative, starts with [P0]/[P1]/[P2]/[P3]>",',
-          '      "body": "<one paragraph of valid Markdown explaining why this is a problem; cite files/lines/functions>",',
-          '      "confidence_score": <float 0.0-1.0>,',
-          '      "priority": <int 0-3 or null>,',
-          '      "code_location": {',
-          '        "absolute_file_path": "<absolute file path>",',
-          '        "line_range": {"start": <int>, "end": <int>}',
-          "      }",
-          "    }",
-          "  ],",
-          '  "overall_correctness": "patch is correct" | "patch is incorrect",',
-          '  "overall_explanation": "<1-3 sentence explanation justifying the verdict>",',
-          '  "overall_confidence_score": <float 0.0-1.0>,',
-          '  "goal_oracle_satisfied": <boolean>,',
-          '  "receipt_assessment": "<how receipts/current evidence map to the verification oracle>",',
-          '  "verification_remaining": "<oracle-relevant verification still missing, or none>",',
-          '  "stop_review_loop": <boolean>,',
-          '  "reviewer_error": null | {"kind": "validation_unavailable" | "dependency_unavailable" | "tool_failure" | "reviewer_failure", "message": "<what failed>", "attempted_recovery": "<what you tried>"}',
-          "}",
+          "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved.",
         ].join("\n"),
       ],
     ]);
@@ -853,8 +814,8 @@ async function runRalphWorkflow(
 
     const reviewEntries = await Promise.all(reviews.map(async (review) => {
       const reviewer = review.name ?? review.stageName;
-      const decision = parseReviewDecision(review.text) ??
-        reviewerErrorDecision(`Reviewer ${reviewer} returned invalid structured JSON.`);
+      const decision = reviewDecisionFromResult(review) ??
+        reviewerErrorDecision(`Reviewer ${reviewer} returned no structured decision.`);
       const artifactPath = join(
         artifactDir,
         `review-${iteration}-${artifactSafeName(reviewer)}.json`,
@@ -886,7 +847,7 @@ async function runRalphWorkflow(
         ],
         [
           "objective",
-          `Review the changes since the base branch \`${comparisonBaseBranch}\` and create a provider-appropriate pull request, merge request, or code-review handoff if possible and credentials are available. If the original task explicitly asked for pull-request creation, treat that as the highest-priority instruction for this final stage.`,
+          `Review the changes since the base branch \`${comparisonBaseBranch}\` and create a provider-appropriate pull request, merge request, or code-review handoff if possible and credentials are available. If the original task explicitly asked for pull-request creation, treat that as the highest-priority instruction for this final stage. Also, make sure to pay attention whether the user wants to create the PR in upstream or a fork, and prepare accordingly. If PR creation is not possible (lack of permissions, etc.), report why instead of pretending success.`,
         ],
         workflowCwdContext,
         [

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.29-alpha.3",
+  "version": "0.8.29",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/extension/index.ts

@@ -131,6 +131,21 @@ export const WORKFLOW_TOOL_DESCRIPTION =
   "quote the exact path without rewriting separators (Windows backslashes are valid), " +
   "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.";
 
+export const DEFAULT_PROMPT_GUIDANCE: string[] = [
+  `**Workflows**: Use the \`workflow\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \`task\`, \`tasks\`, or \`chain\` workflow calls for one-off tracked work when that is useful.
+  - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
+  - When designing or editing workflows, read docs/workflows.md and reference its Workflow Starter Patterns: Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done. Choose or combine these patterns before inventing a custom stage graph, and reflect the selected pattern in the spec and Mermaid diagram when using the create-spec skill.
+  - Once you run a workflow with the workflow tool, end your current turn and wait for the next user input or lifecycle notice.
+    - You will automatically be alerted of key lifecycle events like start, finish, failure; do not micro-manage the run with sleep/status polling loops or read its logs/stages unless the user asks you to or you need information for the next step.
+    - If the user needs information from the workflow run, use targeted \`status\`/\`stages\`/\`stage\` checks instead of trying to read everything.
+    - Offer to help the user on another task instead of anxiously polling or help the user run another workflow if they need.
+    - Use run-control and messaging actions (\`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`kill\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.
+  - For transcripts, avoid reading whole session transcripts at once. Use \`stages\` or \`stage\` to get \`sessionFile\`/\`transcriptPath\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \`rg\`/\`grep\`, and read small relevant ranges; use \`transcript\` with explicit \`tail\` or \`limit\` only for quick recent-context checks.
+  - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, success criteria, and selected starter pattern. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.
+    - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \`reads\`, and explicitly prompt the downstream agent with wording like \`Read the file at <path>...\`; do not inject large \`previous\` payloads or session history into the next prompt unless explicitly requested to.
+  - If you run \`ralph\` or \`goal\` workflow, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`,
+];
+
 // ---------------------------------------------------------------------------
 // Minimal ExtensionAPI structural types
 // No `any`; all optional fields use explicit union with undefined.
@@ -269,6 +284,7 @@ export interface PiToolOpts<TArgs, TDetails> {
   label: string;
   description: string;
   parameters: unknown; // TypeBox TSchema — pi consumes it opaquely
+  promptGuidelines?: string[];
   renderShell?: "default" | "self";
   /**
    * Pi calls execute positionally: `(toolCallId, params, signal, onUpdate, ctx)`.
@@ -2744,6 +2760,7 @@ function factory(pi: ExtensionAPI): void {
       label: "workflow",
       description: WORKFLOW_TOOL_DESCRIPTION,
       parameters: workflowParameters,
+      promptGuidelines: DEFAULT_PROMPT_GUIDANCE,
       renderShell: "self",
       execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
         // Overlay is opt-in via F2 / ctrl+h; do not auto-open from a

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -37,37 +37,10 @@ const McpOptionsSchema = Type.Object({
   deny: Type.Optional(Type.Array(Type.String())),
 });
 
-const JsonSchemaObjectTypeValue = {
-  anyOf: [
-    { const: "object" },
-    { type: "array", minItems: 1, maxItems: 1, items: { const: "object" } },
-  ],
-};
-
-const JsonSchemaExplicitObjectDescriptor = {
+const JsonSchemaObject = Type.Unsafe<Record<string, unknown>>({
   type: "object",
-  required: ["type"],
-  properties: { type: JsonSchemaObjectTypeValue },
   additionalProperties: true,
-};
-
-const JsonSchemaObject = Type.Unsafe<Record<string, unknown>>({
-  description: "Top-level object JSON Schema used as structured_output tool arguments for this workflow item.",
-  anyOf: [
-    JsonSchemaExplicitObjectDescriptor,
-    {
-      type: "object",
-      required: ["allOf"],
-      properties: {
-        allOf: {
-          type: "array",
-          minItems: 1,
-          items: JsonSchemaExplicitObjectDescriptor,
-        },
-      },
-      additionalProperties: true,
-    },
-  ],
+  description: "Plain JSON Schema used as final-answer tool arguments for this workflow item.",
 });
 
 const BashCommandRuleSchema = Type.Union([

package/dist/builtin/workflows/src/runs/foreground/stage-runner.ts

@@ -537,10 +537,6 @@ function splitPromptOptions(options: StagePromptOptions | undefined): {
 
 const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
 
-function structuredOutputPrompt(text: string): string {
-  return `${text}\n\nFinal output contract:\n- Your final action MUST be a structured_output tool call.\n- Pass the schema fields directly as tool arguments; do not wrap them in { value: ... } unless the schema explicitly defines a top-level value field.\n- Do not emit a prose final answer instead of structured_output.\n- If you need to inspect files or run commands first, do so, then call structured_output exactly once.`;
-}
-
 function stringifyStructuredOutputValue(value: unknown): string {
   try {
     return JSON.stringify(value, null, 2);
@@ -959,7 +955,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
         adapterMessages = assistantMessage(lastAssistantText);
         return lastAssistantText;
       }
-      await promptWithFallback(structuredOutputCapture ? structuredOutputPrompt(text) : text, sdkOptions);
+      await promptWithFallback(text, sdkOptions);
       if (structuredOutputCapture) {
         if (!structuredOutputCapture.called) {
           throw new Error("atomic-workflows: stage configured with schema must finish by calling structured_output.");

package/dist/builtin/workflows/src/shared/authoring-contract.d.ts

@@ -113,7 +113,7 @@ export interface WorkflowFastModeSettingsManager {
     getCodexFastModeSettings(): WorkflowFastModeSettings;
 }
 export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined> extends WorkflowModelFallbackFields {
-    /** Optional structured final-answer schema. When set, the stage receives a schema-specific `structured_output` tool and must finish by calling it. */
+    /** Optional structured final-answer schema. When set, the stage receives a schema-specific final-answer tool. */
     readonly schema?: TSchemaDef;
     readonly model?: WorkflowModelValue;
     readonly mcp?: StageMcpOptions;

package/dist/builtin/workflows/src/shared/types.ts

@@ -156,7 +156,7 @@ export interface StageMcpOptions extends AuthoringContract.StageMcpOptions {
 export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined>
   extends Omit<CreateAgentSessionOptions, "model" | keyof AuthoringContract.StageOptions>,
     Omit<Mutable<AuthoringContract.StageOptions<TSchemaDef>>, "sessionManager" | "settingsManager"> {
-  /** Optional structured final-answer schema. When set, the stage receives a schema-specific `structured_output` tool and must finish by calling it. */
+  /** Optional structured final-answer schema. When set, the stage receives a schema-specific final-answer tool. */
   schema?: TSchemaDef;
   /** Model id or pi SDK model object used as the primary stage model. */
   model?: WorkflowModelValue;

package/dist/core/sdk.d.ts

@@ -7,7 +7,7 @@ import { ModelRegistry } from "./model-registry.ts";
 import type { ResourceLoader } from "./resource-loader.ts";
 import { SessionManager } from "./session-manager.ts";
 import { SettingsManager } from "./settings-manager.ts";
-import { createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createReadOnlyTools, createReadTool, STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputCapture, createStructuredOutputTool, getStructuredOutputMetadataPath, createWriteTool, withFileMutationQueue, type BashCommandPolicy } from "./tools/index.ts";
+import { createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createReadOnlyTools, createReadTool, STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputCapture, createStructuredOutputTool, createWriteTool, withFileMutationQueue, type BashCommandPolicy } from "./tools/index.ts";
 export interface CreateAgentSessionOptions {
     /** Working directory for project-local discovery. Default: process.cwd() */
     cwd?: string;
@@ -79,8 +79,8 @@ export * from "./agent-session-runtime.ts";
 export type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ExtensionFactory, SlashCommandInfo, SlashCommandSource, ToolDefinition, } from "./extensions/index.ts";
 export type { PromptTemplate } from "./prompt-templates.ts";
 export type { Skill } from "./skills.ts";
-export type { BashCommandParseError, BashCommandParseResult, BashCommandPolicy, BashCommandPolicyDecision, BashCommandPolicyMatchMode, BashCommandPolicyRejection, BashCommandRule, BashCommandSegment, BashCommandSegmentSource, JsonObject, JsonPrimitive, JsonValue, StructuredOutputCapture, StructuredOutputCaptureMetadata, StructuredOutputFileCapture, StructuredOutputToolOptions, Tool, } from "./tools/index.ts";
-export { withFileMutationQueue, STRUCTURED_OUTPUT_TOOL_NAME, createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, createStructuredOutputCapture, createStructuredOutputTool, getStructuredOutputMetadataPath, };
+export type { BashCommandParseError, BashCommandParseResult, BashCommandPolicy, BashCommandPolicyDecision, BashCommandPolicyMatchMode, BashCommandPolicyRejection, BashCommandRule, BashCommandSegment, BashCommandSegmentSource, JsonObject, JsonPrimitive, JsonValue, StructuredOutputCapture, StructuredOutputFileCapture, StructuredOutputToolOptions, Tool, } from "./tools/index.ts";
+export { withFileMutationQueue, STRUCTURED_OUTPUT_TOOL_NAME, createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, createStructuredOutputCapture, createStructuredOutputTool, };
 /**
  * Create an AgentSession with the specified options.
  *