@bastani/atomic 0.5.23 → 0.5.24-0

package/.agents/skills/workflow-creator/references/agent-sessions.md

@@ -95,47 +95,38 @@ Claude maintains conversation context across calls within the same pane. Call `s
 })
 ```
 
-### Advanced: Claude Agent SDK `query()` API
+### Advanced: Claude Agent SDK `query()` option surface (reference only)
 
-For programmatic control beyond tmux automation, the Claude Agent SDK provides `query()`. **Do not call it from inside a non-headless `ctx.stage()`** — that spawns a TUI in a tmux pane that goes unused while the SDK runs in-process (see `failure-modes.md` §F17). Either set `headless: true` on the stage and pass SDK options through `s.session.query(prompt, options)` (the headless wrapper forwards them to `query()`), or use the interactive TUI route below with `chatFlags: ["--agent", "<name>", ...]` plus `s.session.query(prompt)`.
+**Do not import `query` from `@anthropic-ai/claude-agent-sdk` inside a `ctx.stage()` callback.** In a non-headless stage it double-spawns Claude (idle TUI pane + in-process SDK call) — see `failure-modes.md` §F16. In a headless stage it bypasses the runtime's wiring. Always go through `s.session.query()`; the runtime forwards options to the SDK for headless stages and routes the interactive TUI for non-headless stages.
 
-The example below is reference for the SDK option surface — in real workflow code, prefer `s.session.query()` so the runtime, not your callback, decides which transport to use:
+Two correct routes:
 
-```ts
-import { query } from "@anthropic-ai/claude-agent-sdk";
+1. **Headless + SDK options** — `s.session.query(prompt, sdkOptions)` inside `{ headless: true }`.
+2. **Interactive TUI + `--agent`** — `chatFlags: ["--agent", "<name>", ...]` in `clientOpts`.
 
-.run(async (ctx) => {
-  await ctx.stage({ name: "implement" }, {}, {}, async (s) => {
-    const result = query({
-      prompt: (s.inputs.prompt ?? ""),
-      options: {
-        model: "claude-opus-4-6",
-        effort: "high",
-        maxTurns: 50,
-        maxBudgetUsd: 5.0,
-        permissionMode: "acceptEdits",
-        allowedTools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
-        disallowedTools: ["AskUserQuestion"],
-        systemPrompt: "You are a senior engineer...",
-        outputFormat: {
-          type: "json_schema",
-          schema: { type: "object", properties: { tasks: { type: "array", items: { type: "string" } } } },
-        },
-        agents: {
-          reviewer: { description: "Review code changes", prompt: "You are a code reviewer..." },
-        },
-      },
-    });
-    for await (const message of result) {
-      // Process streaming messages
-    }
+For the full SDK option surface, see `session-config.md` §"`query()` options".
+
+Example workflow usage in a headless stage:
+
+```ts
+await ctx.stage({ name: "implement", headless: true }, {}, {}, async (s) => {
+  const messages = await s.session.query(s.inputs.prompt ?? "", {
+    model: "claude-opus-4-6",
+    permissionMode: "acceptEdits",
+    allowedTools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
+    outputFormat: {
+      type: "json_schema",
+      schema: { type: "object", properties: { tasks: { type: "array", items: { type: "string" } } } },
+    },
   });
-})
+  s.save(s.sessionId);
+  return extractAssistantText(messages, 0);
+});
 ```
 
 Key `query()` options:
 - `model` — model ID (`"claude-opus-4-6"`, `"claude-sonnet-4-6"`) or alias (`"opus"`, `"sonnet"`, `"haiku"`)
-- `effort` — reasoning effort (`"low"`, `"medium"`, `"high"`, `"max"` — `"max"` is Opus 4.6 only)
+- `effort` — reasoning effort (`"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` — `"max"` is Opus 4.6/4.7 only)
 - `thinking` — thinking/reasoning config: `{ type: "adaptive" }` (default for supported models), `{ type: "enabled", budgetTokens: N }`, or `{ type: "disabled" }`
 - `maxTurns` — maximum conversation turns
 - `maxBudgetUsd` — spending cap in USD
@@ -155,43 +146,67 @@ Key `query()` options:
 
 ### Subagents
 
-Claude supports parallel subagents via the `agents` option (a `Record<string, AgentDefinition>` keyed by agent name):
+Claude supports parallel subagents via the `agents` option (a
+`Record<string, AgentDefinition>` keyed by agent name). In a workflow,
+pass the option through `s.session.query(prompt, sdkOptions)` in a
+**headless** stage — see §F16 for why the raw SDK `query()` import is
+an anti-pattern:
 
 ```ts
-const agents = {
-  worker: {
-    description: "Implement a single task",
-    prompt: "You are a task implementer...",
-    tools: ["Read", "Write", "Edit", "Bash"],
-  },
-  reviewer: {
-    description: "Review code changes",
-    prompt: "You are a code reviewer...",
-    tools: ["Read", "Grep", "Glob"],
+await ctx.stage(
+  { name: "implement-and-review", headless: true },
+  {}, {},
+  async (s) => {
+    const messages = await s.session.query(
+      "Implement and review the feature",
+      {
+        agents: {
+          worker: {
+            description: "Implement a single task",
+            prompt: "You are a task implementer...",
+            tools: ["Read", "Write", "Edit", "Bash"],
+          },
+          reviewer: {
+            description: "Review code changes",
+            prompt: "You are a code reviewer...",
+            tools: ["Read", "Grep", "Glob"],
+          },
+        },
+      },
+    );
+    s.save(s.sessionId);
+    return extractAssistantText(messages, 0);
   },
-};
-
-const result = query({
-  prompt: "Implement and review the feature",
-  options: { agents },
-});
+);
 ```
 
 ### Session continuity
 
-Resume or fork prior sessions:
+Resume or fork prior sessions through `s.session.query()` in a headless
+stage (same reasoning as Subagents above — never import `query` directly):
 
 ```ts
 // Resume a session (continues the same conversation)
-const result = query({ prompt: "Continue...", options: { resume: sessionId } });
+await ctx.stage({ name: "continue", headless: true }, {}, {}, async (s) => {
+  const messages = await s.session.query("Continue...", { resume: sessionId });
+  s.save(s.sessionId);
+  return extractAssistantText(messages, 0);
+});
 
 // Fork a session (creates a new branch from the session's history)
-const result = query({ prompt: "Try a different approach", options: { resume: sessionId, forkSession: true } });
+await ctx.stage({ name: "fork", headless: true }, {}, {}, async (s) => {
+  const messages = await s.session.query(
+    "Try a different approach",
+    { resume: sessionId, forkSession: true },
+  );
+  s.save(s.sessionId);
+  return extractAssistantText(messages, 0);
+});
 ```
 
-### Sub-agent delegation
+### Subagent delegation
 
-For stages that call a single sub-agent, use `--agent` (interactive) or the SDK `agent` option (headless) to route all prompts through that agent. The agent must be defined in `.claude/agents/` or `.agents/skills/`.
+For stages that call a single subagent, use `--agent` (interactive) or the SDK `agent` option (headless) to route all prompts through that agent. The agent must be defined in `.claude/agents/` or `.agents/skills/`.
 
 **Interactive stages** — pass `--agent` via `chatFlags` in client opts (2nd arg):
 
@@ -318,38 +333,45 @@ A workflow is not just a sequence of agent calls — it is an **information
 flow problem**. The single most common failure mode in Copilot workflows is
 assuming context carries across session boundaries when it doesn't.
 Designing a workflow without thinking about information flow produces
-sub-agents that hallucinate, repeat work, or drop requirements silently.
+subagents that hallucinate, repeat work, or drop requirements silently.
 
 **Treat this section as load-bearing**, not decorative. If you skip it, your
 workflow will ship broken in subtle, non-deterministic ways.
 
-#### The three session lifecycle states
+#### Session lifecycle states
 
-Every Copilot session is always in exactly one of these states, and the
+For normal workflow authoring, use the **3-state rubric** from SKILL.md:
+`Fresh` / `Continued` / `Closed`. Every new `ctx.stage()` call is fresh; if
+you need full history, prefer another turn inside the same stage callback.
+
+Copilot also exposes an advanced `Resumed` state at the provider level. Each
 state determines what context the model sees on its next turn:
 
-| State | How you get there | Context available | Action needed |
-|---|---|---|---|
-| **Fresh** | `client.createSession(...)` | **None** — empty conversation | You MUST inject everything the agent needs in the first prompt |
-| **Continued** | Same session, additional `send` calls | All prior turns in this session | Nothing — but watch total token usage |
-| **Resumed** | `client.resumeSession(sessionId)` | All persisted turns from the prior session of the SAME agent | Nothing — full history is reattached |
-| **Closed** | `session.disconnect()` or `client.stop()` | **Gone** from the live client; persisted on disk if the host enables it | Either resume by ID (same agent) or start fresh and re-inject context |
+| State                    | How you get there                                                                                    | Context available                                                       | Action needed                                                             |
+| ------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| **Fresh**                | `client.createSession(...)` (what `ctx.stage()` does)                                                | **None** — empty conversation                                           | You MUST inject everything the agent needs in the first prompt            |
+| **Continued**            | Same session, additional `send` calls                                                                | All prior turns in this session                                         | Nothing — but watch total token usage                                     |
+| **Resumed** *(advanced)* | `client.resumeSession(sessionId)`                                                                    | All persisted turns from the prior session of the SAME agent            | Nothing — full history is reattached. Use only for same-role continuation |
+| **Closed**               | `session.disconnect()` or `client.stop()` (auto-handled by runtime after the stage callback returns) | **Gone** from the live client; persisted on disk if the host enables it | Either resume by ID (same agent) or start fresh and re-inject context     |
 
 The failure mode: you close a session, create a new one, and assume the new
 one "remembers" the previous conversation. It doesn't. `client` is just the
-transport — each session is a fully independent conversation.
-
-For normal workflow authoring, the key rule is simpler than the full lifecycle
-table: **every new `ctx.stage()` call is fresh**. If you need full history,
-prefer another turn inside the same stage callback. Resume/fork APIs are
-provider-specific escape hatches, not the default stage-to-stage handoff path.
+transport — each session is a fully independent conversation. Resume/fork
+APIs are provider-specific escape hatches, not the default stage-to-stage
+handoff path.
 
 ```ts
-// Buggy — the orchestrator session is fresh and knows NOTHING about
-// what the planner just produced, because createSession() started a
-// brand-new conversation.
-await runAgent("planner", buildPlannerPrompt((ctx.inputs.prompt ?? "")));
-await runAgent("orchestrator", buildOrchestratorPrompt());
+// Buggy — the orchestrator stage is fresh and knows NOTHING about what
+// the planner just produced, because each ctx.stage() starts a brand-new
+// conversation for Copilot.
+await ctx.stage({ name: "planner" }, {}, { agent: "planner" }, async (s) => {
+  await s.session.send({ prompt: buildPlannerPrompt((s.inputs.prompt ?? "")) });
+  s.save(await s.session.getMessages());
+});
+await ctx.stage({ name: "orchestrator" }, {}, { agent: "orchestrator" }, async (s) => {
+  await s.session.send({ prompt: buildOrchestratorPrompt() });
+  s.save(await s.session.getMessages());
+});
 // ↑ orchestrator only sees buildOrchestratorPrompt() — no planner output,
 //   no original user spec, no context.
 ```
@@ -361,22 +383,37 @@ mutually exclusive — ralph uses (1) + (2) together as belt-and-braces.
 
 **1. Explicit prompt handoff** — capture the prior session's last assistant
 message and inject it (or a summary) into the next session's first prompt.
-Simplest and most common fix:
+Simplest and most common fix. Use `ctx.stage()` — the runtime auto-creates
+and cleans up each session, so never call `client.createSession()` directly
+(see Structural Rule 7 in SKILL.md):
 
 ```ts
-async function runAgent(agent: string, prompt: string): Promise<string> {
-  const session = await client.createSession({ agent, onPermissionRequest: approveAll });
-  await session.send({ prompt });
-  const messages = await session.getMessages();
-  await session.disconnect();
-  return getAssistantText(messages); // concatenate every top-level turn — see failure-modes.md §F1
-}
-
 // Correct — forward the planner's output into the orchestrator prompt
-const plannerNotes = await runAgent("planner", buildPlannerPrompt((ctx.inputs.prompt ?? "")));
-await runAgent(
-  "orchestrator",
-  buildOrchestratorPrompt((ctx.inputs.prompt ?? ""), { plannerNotes }),
+const plannerHandle = await ctx.stage(
+  { name: "planner" },
+  {},
+  { agent: "planner" },
+  async (s) => {
+    await s.session.send({ prompt: buildPlannerPrompt((s.inputs.prompt ?? "")) });
+    const messages = await s.session.getMessages();
+    s.save(messages);
+    return getAssistantText(messages); // see failure-modes.md §F1 for getAssistantText
+  },
+);
+
+await ctx.stage(
+  { name: "orchestrator" },
+  {},
+  { agent: "orchestrator" },
+  async (s) => {
+    await s.session.send({
+      prompt: buildOrchestratorPrompt(
+        (s.inputs.prompt ?? ""),
+        { plannerNotes: plannerHandle.result },
+      ),
+    });
+    s.save(await s.session.getMessages());
+  },
 );
 ```
 
@@ -427,15 +464,15 @@ trade-offs in depth.
 Information flow is a design problem, not an implementation detail. Before
 committing to a session layout, pull in the relevant skills:
 
-| When you're deciding... | Consult |
-|---|---|
-| What context each session actually needs (anatomy + token budget) | `context-fundamentals` |
+| When you're deciding...                                                  | Consult                |
+| ------------------------------------------------------------------------ | ---------------------- |
+| What context each session actually needs (anatomy + token budget)        | `context-fundamentals` |
 | How many sessions and how they hand off (orchestrator vs peers vs swarm) | `multi-agent-patterns` |
-| How to compress large planner/reviewer output before re-injecting | `context-compression` |
-| How to detect and prevent lost-in-middle, poisoning, and distraction | `context-degradation` |
-| How to use files as coordination medium across sessions | `filesystem-context` |
-| How to persist knowledge across whole workflow runs | `memory-systems` |
-| Which turns to drop, which to cache, when to compact | `context-optimization` |
+| How to compress large planner/reviewer output before re-injecting        | `context-compression`  |
+| How to detect and prevent lost-in-middle, poisoning, and distraction     | `context-degradation`  |
+| How to use files as coordination medium across sessions                  | `filesystem-context`   |
+| How to persist knowledge across whole workflow runs                      | `memory-systems`       |
+| Which turns to drop, which to cache, when to compact                     | `context-optimization` |
 
 These aren't optional reading — they're the difference between a workflow
 that works on day one and a workflow that silently degrades as inputs grow.
@@ -518,27 +555,17 @@ await ctx.stage(
 
 Do **not** just grab `.at(-1).data.content` — a Copilot turn's final
 `assistant.message` often has empty `content` (tool-calls-only) and
-sub-agent messages can pollute the stream via `parentToolCallId`. Concatenate
-every top-level turn's non-empty content instead. See
-`references/failure-modes.md` §"Copilot: `getLastAssistantText` returns
-empty string" for the full explanation and wrong-vs-right examples.
+subagent messages can pollute the stream via `parentToolCallId`. Concatenate
+every top-level turn's non-empty content instead.
+
+The canonical `getAssistantText` helper lives in `failure-modes.md` §F1 —
+copy it into a sibling `helpers/parsers.ts` and import it. Usage:
 
 ```ts
-import type { SessionEvent } from "@github/copilot-sdk";
-
-/** Concatenate every top-level assistant turn's non-empty content.
- *  Canonical definition — also referenced in failure-modes.md §F1
- *  and computation-and-validation.md. */
-function getAssistantText(messages: SessionEvent[]): string {
-  return messages
-    .filter(
-      (m): m is Extract<SessionEvent, { type: "assistant.message" }> =>
-        m.type === "assistant.message" && !m.data.parentToolCallId,
-    )
-    .map((m) => m.data.content)
-    .filter((c) => c.length > 0)
-    .join("\n\n");
-}
+import { getAssistantText } from "../helpers/parsers.ts";
+
+const messages = await s.session.getMessages();
+const text = getAssistantText(messages);
 ```
 
 ### Streaming events
@@ -554,9 +581,9 @@ s.session.on("assistant.reasoning_delta", (event) => {
 });
 ```
 
-### Sub-agent delegation
+### Subagent delegation
 
-Pass the `agent` parameter in `sessionOpts` (3rd arg to `ctx.stage()`) to bind the session to a named sub-agent:
+Pass the `agent` parameter in `sessionOpts` (3rd arg to `ctx.stage()`) to bind the session to a named subagent:
 
 ```ts
 .run(async (ctx) => {
@@ -629,11 +656,11 @@ export default defineWorkflow({
 
 OpenCode sessions have **exactly the same isolation semantics as Copilot
 sessions**. Every call to `client.session.create(...)` returns a fresh,
-empty conversation. Creating a new session for the next sub-agent wipes
+empty conversation. Creating a new session for the next subagent wipes
 everything the prior session knew — conversation history, tool-call
 results, intermediate reasoning — unless you forward it explicitly.
 
-The full explanation, the three lifecycle states (Fresh / Continued /
+The full explanation, the four lifecycle states (Fresh / Continued /
 Resumed / Closed), the three valid ways to carry context across a session
 boundary, compaction & clearing guidance, and the context engineering
 skill-map live in the **Copilot** section above under
@@ -642,32 +669,70 @@ available"](#critical-pitfall-session-lifecycle-controls-what-context-is-availab
 Every principle there applies to OpenCode without modification — just
 substitute the OpenCode API equivalents:
 
-| Concept | Copilot API | OpenCode API |
-|---|---|---|
-| Fresh session (auto-created) | `s.session` (runtime creates via `createSession`) | `s.session` (runtime creates via `session.create`) |
-| Send a turn | `s.session.send({ prompt })` | `s.client.session.prompt({ sessionID: s.session.id, parts })` |
-| Close / disconnect | Auto-handled by runtime | session lifecycle managed via server; no explicit disconnect in typical flow |
-| Continue prior conversation | `s.client.resumeSession(sessionId)` (provider API; advanced) | Reuse the same `sessionID` with `s.client.session.prompt()` inside the same logical conversation. `ctx.stage()` itself still creates a fresh session every time |
-| Extract final text | `getAssistantText(messages)` (see `failure-modes.md` §F1) | `extractResponseText(result.data!.parts)` |
+| Concept                      | Copilot API                                                  | OpenCode API                                                                                                                                                    |
+| ---------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Fresh session (auto-created) | `s.session` (runtime creates via `createSession`)            | `s.session` (runtime creates via `session.create`)                                                                                                              |
+| Send a turn                  | `s.session.send({ prompt })`                                 | `s.client.session.prompt({ sessionID: s.session.id, parts })`                                                                                                   |
+| Close / disconnect           | Auto-handled by runtime                                      | session lifecycle managed via server; no explicit disconnect in typical flow                                                                                    |
+| Continue prior conversation  | `s.client.resumeSession(sessionId)` (provider API; advanced) | Reuse the same `sessionID` with `s.client.session.prompt()` inside the same logical conversation. `ctx.stage()` itself still creates a fresh session every time |
+| Extract final text           | `getAssistantText(messages)` (see `failure-modes.md` §F1)    | `extractResponseText(result.data!.parts)`                                                                                                                       |
 
 **Multi-agent handoff example (applies the same pattern as Copilot):**
 
 ```ts
-// Buggy — orchestrator session is fresh; it has no idea what the planner
-// produced because we created a brand-new session for it.
-await runAgent("planner-1", "planner", buildPlannerPrompt((ctx.inputs.prompt ?? "")));
-await runAgent("orchestrator-1", "orchestrator", buildOrchestratorPrompt());
+// Buggy — orchestrator stage is fresh; it has no idea what the planner
+// produced because each ctx.stage() starts a brand-new session.
+await ctx.stage({ name: "planner" }, {}, { title: "planner" }, async (s) => {
+  const result = await s.client.session.prompt({
+    sessionID: s.session.id,
+    parts: [{ type: "text", text: buildPlannerPrompt((s.inputs.prompt ?? "")) }],
+    agent: "planner",
+  });
+  s.save(result.data!);
+});
+await ctx.stage({ name: "orchestrator" }, {}, { title: "orchestrator" }, async (s) => {
+  await s.client.session.prompt({
+    sessionID: s.session.id,
+    parts: [{ type: "text", text: buildOrchestratorPrompt() }],
+    agent: "orchestrator",
+  });
+  s.save(/* ... */);
+});
 
 // Correct — capture planner output and forward it into orchestrator prompt
-const plannerNotes = await runAgent(
-  "planner-1",
-  "planner",
-  buildPlannerPrompt((ctx.inputs.prompt ?? "")),
+const plannerHandle = await ctx.stage(
+  { name: "planner" },
+  {},
+  { title: "planner" },
+  async (s) => {
+    const result = await s.client.session.prompt({
+      sessionID: s.session.id,
+      parts: [{ type: "text", text: buildPlannerPrompt((s.inputs.prompt ?? "")) }],
+      agent: "planner",
+    });
+    s.save(result.data!);
+    return extractResponseText(result.data!.parts); // see failure-modes.md §F3
+  },
 );
-await runAgent(
-  "orchestrator-1",
-  "orchestrator",
-  buildOrchestratorPrompt((ctx.inputs.prompt ?? ""), { plannerNotes }),
+
+await ctx.stage(
+  { name: "orchestrator" },
+  {},
+  { title: "orchestrator" },
+  async (s) => {
+    const result = await s.client.session.prompt({
+      sessionID: s.session.id,
+      parts: [{
+        type: "text",
+        text: buildOrchestratorPrompt(
+          (s.inputs.prompt ?? ""),
+          { plannerNotes: plannerHandle.result },
+        ),
+      }],
+      agent: "orchestrator",
+    });
+    s.save(result.data!);
+  },
 );
 ```
 
@@ -751,20 +816,14 @@ const result = await s.client.session.prompt({
 
 ### Extracting response text
 
+Non-text parts (`tool`, `file`, `reasoning`, …) coexist with `text` parts in
+`result.data!.parts`; naive `.map(p => p.text)` emits `undefined` for them.
+The canonical `extractResponseText` helper lives in `failure-modes.md` §F3 —
+copy it into a sibling `helpers/parsers.ts` and import it. Usage:
+
 ```ts
-/** Filter for text parts only — non-text parts produce [object Object].
- *  Canonical definition — also referenced in failure-modes.md §F3
- *  and computation-and-validation.md. */
-function extractResponseText(
-  parts: Array<{ type: string; [key: string]: unknown }>,
-): string {
-  return parts
-    .filter((p) => p.type === "text")
-    .map((p) => (p as { type: string; text: string }).text)
-    .join("\n");
-}
-
-// Usage inside a ctx.stage callback:
+import { extractResponseText } from "../helpers/parsers.ts";
+
 const result = await s.client.session.prompt({
   sessionID: s.session.id,
   parts: [{ type: "text", text: (s.inputs.prompt ?? "") }],
@@ -783,9 +842,9 @@ const unsubscribe = await s.client.event.subscribe((event) => {
 });
 ```
 
-### Sub-agent delegation
+### Subagent delegation
 
-Pass the `agent` parameter to `s.client.session.prompt()` to route a prompt to a named sub-agent:
+Pass the `agent` parameter to `s.client.session.prompt()` to route a prompt to a named subagent:
 
 ```ts
 .run(async (ctx) => {

package/.agents/skills/workflow-creator/references/computation-and-validation.md

@@ -4,12 +4,14 @@ Deterministic computation — validation, data transforms, file I/O, API calls
 
 ## Inline computation
 
-Any TypeScript code inside a session callback that doesn't call an SDK prompt function is deterministic computation:
+Any TypeScript code inside a session callback that doesn't call an SDK prompt function is deterministic computation. Prefer handle-based lookups (`s.getMessages(plannerHandle)`) over string names when a handle is in scope — it preserves type information and survives stage renames:
 
 ```ts
+const plannerHandle = await ctx.stage({ name: "planner" }, {}, {}, async (s) => { /* ... */ });
+
 await ctx.stage({ name: "validate-and-fix", description: "Validate, then fix if needed" }, {}, {}, async (s) => {
-  // Step 1: Deterministic — parse prior session's output
-  const messages = await s.getMessages("planner");
+  // Step 1: Deterministic — parse prior session's output (handle-based lookup)
+  const messages = await s.getMessages(plannerHandle);
   const planText = extractText(messages);
   const plan = JSON.parse(planText);
 
@@ -72,39 +74,12 @@ const text = extractResponseText(result.data!.parts);
 
 ### JSON parsing with fallback
 
-Use a layered fallback: direct parse, then the **last** fenced block (not
-the first — see `failure-modes.md` §F4 / §F8 for why), then last balanced
-object:
-
-```ts
-function parseJsonResponse(text: string): Record<string, unknown> | null {
-  // 1. Direct parse
-  try { return JSON.parse(text); } catch {}
-
-  // 2. LAST fenced code block (prose often quotes examples before the real output)
-  const blockRe = /```(?:json)?\s*\n([\s\S]*?)\n```/g;
-  let lastBlock: string | null = null;
-  let m: RegExpExecArray | null;
-  while ((m = blockRe.exec(text)) !== null) {
-    if (m[1]) lastBlock = m[1];
-  }
-  if (lastBlock) {
-    try { return JSON.parse(lastBlock); } catch {}
-  }
-
-  // 3. Last balanced JSON object
-  const objRe = /\{[\s\S]*\}/g;
-  let lastObj: string | null = null;
-  while ((m = objRe.exec(text)) !== null) {
-    if (m[0]) lastObj = m[0];
-  }
-  if (lastObj) {
-    try { return JSON.parse(lastObj); } catch {}
-  }
-
-  return null;
-}
-```
+Use a layered fallback: direct parse → **last** fenced block (not the
+first — prose often quotes examples earlier; see `failure-modes.md` §F8) →
+last balanced object. Canonical helper lives in `state-and-data-flow.md`
+§"Response parsers"; copy it into a sibling `helpers/parsers.ts` and
+import. The full three-layer implementation, including the balanced-object
+fallback, is in `src/sdk/workflows/builtin/ralph/helpers/prompts.ts`.
 
 ### Zod validation
 
@@ -171,7 +146,7 @@ Transform data between sessions:
 ```ts
 // Inside a ctx.stage() callback:
 async (s) => {
-  const raw = await s.getMessages("planner");
+  const raw = await s.getMessages("planner"); // or s.getMessages(handle) if a handle is in scope (preferred)
 
   // Transform: extract only task IDs and descriptions
   const tasks = extractTasks(raw).map(t => ({