feat(step-read): store assembled prompt in CAS, add --prompt flag

Store the fully assembled prompt sent to each agent in CAS as a text
node, referenced from StepNodePayload.assembledPrompt. This enables
exact reproduction of what the agent received for debugging hallucinations.

Changes:
- workflow-protocol: StepRecord + STEP_NODE_SCHEMA add assembledPrompt field
- workflow-util-agent: AgentRunResult includes assembledPrompt, run.ts stores it
- workflow-util-agent: schemas register TEXT_SCHEMA for prompt storage
- workflow-agent-claude-code: return assembled prompt from buildClaudeCodePrompt
- workflow-agent-hermes: return assembled prompt from buildHermesPrompt
- workflow-agent-builtin: return empty prompt (no prompt assembly)
- cli-workflow: step read --prompt renders the stored prompt
- All test fixtures updated for new field

Legacy steps without assembledPrompt show 'Prompt not recorded' message.

小橘 🍊

packages/cli-workflow/src/__tests__/step-read.test.ts

@@ -146,10 +146,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step with large quota
-    const markdown = await cmdStepRead(tmpDir, stepHash, 10000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 10000, false);
 
     // Assert structure
     expect(markdown).toContain(`# Step ${stepHash}`);
@@ -231,10 +232,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step with limited quota (700 chars)
-    const markdown = await cmdStepRead(tmpDir, stepHash, 700);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 700, false);
 
     // Assert only most recent turns fit
     expect(markdown).toContain(`# Step ${stepHash}`);
@@ -310,10 +312,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step with minimal quota (1 char)
-    const markdown = await cmdStepRead(tmpDir, stepHash, 1);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 1, false);
 
     // Assert at least one turn is always shown
     expect(markdown).toContain("LongTurn");
@@ -365,10 +368,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step - should return metadata only (no error)
-    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000, false);
 
     // Assert metadata is present
     expect(markdown).toContain(`# Step ${stepHash}`);
@@ -441,10 +445,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step - should return metadata only (no error)
-    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000, false);
 
     // Assert metadata is present
     expect(markdown).toContain(`# Step ${stepHash}`);
@@ -515,9 +520,10 @@ describe("step read", () => {
       agent: "uwf-hermes",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
-    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000, false);
 
     expect(markdown).toContain("**Turn role:** assistant");
     expect(markdown).toContain("**terminal**");
@@ -588,10 +594,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step
-    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000, false);
 
     // Assert content is rendered correctly without corruption
     expect(markdown).toContain("`backticks`");

packages/cli-workflow/src/__tests__/step-show-json.test.ts

@@ -116,6 +116,7 @@ async function createTestStep(
     edgePrompt: "",
     startedAtMs: Date.now(),
     completedAtMs: Date.now() + 1000,
+    assembledPrompt: null,
     cwd: "/tmp",
   };
   return store.put(schemas.stepNode, stepPayload);

packages/cli-workflow/src/__tests__/step-timing.test.ts

@@ -85,6 +85,7 @@ describe("protocol types", () => {
       edgePrompt: "",
       startedAtMs: 1000,
       completedAtMs: 2000,
+      assembledPrompt: null,
       cwd: "/test/path",
     };
     expect(record.startedAtMs).toBe(1000);
@@ -153,6 +154,7 @@ describe("StepNode JSON schema", () => {
       edgePrompt: "",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
     expect(hash).toBeTruthy();
   });

packages/cli-workflow/src/__tests__/thread-read-quota.test.ts

@@ -143,6 +143,7 @@ describe("thread read --quota flag", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+      assembledPrompt: null,
       });
       steps.push(stepHash);
     }
@@ -225,6 +226,7 @@ describe("thread read --quota flag", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const step2Content = generateContent(600, "Second");
@@ -251,6 +253,7 @@ describe("thread read --quota flag", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01HX2Q3R4S5T6V7W8X9YZ1" as ThreadId;
@@ -336,6 +339,7 @@ describe("thread read --quota flag", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+      assembledPrompt: null,
       });
       steps.push(stepHash);
     }
@@ -415,6 +419,7 @@ describe("thread read --quota flag", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01HX2Q3R4S5T6V7W8X9YZ4" as ThreadId;
@@ -492,6 +497,7 @@ describe("thread read --quota flag", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+      assembledPrompt: null,
       });
       steps.push(stepHash);
     }
@@ -573,6 +579,7 @@ describe("thread read --quota flag", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+      assembledPrompt: null,
       });
       steps.push(stepHash);
     }

packages/cli-workflow/src/__tests__/thread-read-xml-tags.test.ts

@@ -141,6 +141,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-claude-code",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000001" as ThreadId;
@@ -218,6 +219,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-claude-code",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000002" as ThreadId;
@@ -280,6 +282,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const step2 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -291,6 +294,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000003" as ThreadId;
@@ -345,6 +349,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000004" as ThreadId;
@@ -399,6 +404,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000005" as ThreadId;
@@ -453,6 +459,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000006" as ThreadId;
@@ -527,6 +534,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const step2 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -538,6 +546,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const step3 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -549,6 +558,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000007" as ThreadId;
@@ -629,6 +639,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000008" as ThreadId;
@@ -685,6 +696,7 @@ describe("thread read XML tag isolation", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+      assembledPrompt: null,
       })) as CasRef;
       steps.push(step);
       prev = step;

packages/cli-workflow/src/cli.ts

@@ -364,7 +364,8 @@ step
   .description("Read a step's turns as human-readable markdown")
   .argument("<step-hash>", "CAS hash of the StepNode")
   .option("--quota <chars>", "Max output characters", "4000")
-  .action((stepHash: string, opts: { quota: string }) => {
+  .option("--prompt", "Show the assembled prompt sent to the agent instead of turns")
+  .action((stepHash: string, opts: { quota: string; prompt: boolean }) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const quota = Number.parseInt(opts.quota, 10);
@@ -372,7 +373,7 @@ step
         process.stderr.write("invalid --quota: must be a positive integer\n");
         process.exit(1);
       }
-      const markdown = await cmdStepRead(storageRoot, stepHash as CasRef, quota);
+      const markdown = await cmdStepRead(storageRoot, stepHash as CasRef, quota, opts.prompt === true);
       process.stdout.write(markdown.endsWith("\n") ? markdown : `${markdown}\n`);
     });
   });

packages/cli-workflow/src/commands/step.ts

@@ -289,6 +289,7 @@ export async function cmdStepRead(
   storageRoot: string,
   stepHash: CasRef,
   quota: number,
+  showPrompt: boolean,
 ): Promise<string> {
   const uwf = await createUwfStore(storageRoot);
   const node = uwf.store.get(stepHash);
@@ -300,6 +301,20 @@ export async function cmdStepRead(
   }
   const payload = node.payload as StepNodePayload;
 
+  // --prompt mode: show the assembled prompt that was sent to the agent
+  if (showPrompt) {
+    const promptRef = (payload as Record<string, unknown>).assembledPrompt;
+    if (typeof promptRef !== "string") {
+      return `# Step ${stepHash}\n\n_Prompt not recorded (legacy step)._`;
+    }
+    const promptNode = uwf.store.get(promptRef as CasRef);
+    if (promptNode === null) {
+      return `# Step ${stepHash}\n\n_Prompt CAS node not found: ${promptRef}_`;
+    }
+    const promptText = typeof promptNode.payload === "string" ? promptNode.payload : JSON.stringify(promptNode.payload);
+    return `# Step ${stepHash}\n\n**Role:** ${payload.role}\n**Agent:** ${payload.agent}\n\n## Prompt\n\n${promptText}`;
+  }
+
   if (payload.detail === null) {
     return formatStepMarkdown(stepHash, payload.role, payload.agent, [], []);
   }