@tranhoangnguyen0310/pi-flow-external 2.9.0-external.0 → 2.10.0-external.0

package/CHANGELOG.md

@@ -4,7 +4,20 @@ All notable changes to pi-flow external are documented here.
 
 ## Unreleased
 
+## [2.10.0-external.0] - 2026-09-25
+
+### Added
+- Add paged Launch inspection through `external_runs` and `/external runs` for queued, active, and historical assignments, including recorded prompts, context, and execution configuration.
+- Record requested settings and applied Pi SDK tools/thinking/context, and preserve workflow source and arguments in redacted launch evidence.
+- Document the delegation experience north star and visual guidelines.
+
+### Changed
+- Make background Agent and workflow cards explicit launch receipts, with inspection routes and clearer workflow purpose, workspace, and access disclosure.
+- Improve card legibility with consistent label/value contrast, bounded source paths and run references, and expanded-only usage accounting.
+- Add run-detail refresh and recover from stale inspection pages without closing navigation.
+
 ## [2.9.0-external.0] - 2026-09-25
+
 ### Added
 
 - OpenCode (`opencode`) as a sixth CLI backend, with JSONL progress, verified-final-step completion, session resume, native root-step usage, cancellation, and durable receipts. Targets OpenCode 2 only (verified against `@opencode/cli` 2.0.16); OpenCode 1.x is not supported. Every run uses `--standalone`, a private server the run owns, and never touches the shared background service. Success is verified from the persisted session export: a new user turn for this prompt, a `succeeded` idle outcome, and a clean final assistant message whose text is the result. It never relies on the zero exit code or streamed narration alone. Restricted tiers use native deny-by-default tool rules, not an OS sandbox, and select their agent with `--agent` on every run, including resumes. Unsafe resumes (a restricted resume of a session with its own permission rules, or a danger resume of a restricted session) are refused. A pinned thinking level is passed as the pinned model's `#variant`, which OpenCode validates. Structured schemas are rejected. Nested-subagent total cost is unknown, and budgets are unenforceable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "2.9.0-external.0",
+  "version": "2.10.0-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/core/run-inspection.ts

@@ -17,7 +17,7 @@ const MAX_CURSOR_CHARS = 4096;
 const MAX_LIST_SCAN = 200;
 const RUN_ID_PATTERN = /^run_[A-Za-z0-9_-]{1,128}$/;
 
-export type RunInspectionView = "output" | "diagnostics" | "summary" | "final";
+export type RunInspectionView = "output" | "diagnostics" | "summary" | "final" | "launch";
 export type RunRecordIntegrity = "complete" | "incomplete" | "damaged";
 export type RunOutputStatus = "preliminary" | "final" | "interrupted";
 
@@ -98,6 +98,8 @@ interface EvidenceEvent { runId?: string; sequence?: number; timestamp?: string;
 interface CompleteLine { start: number; end: number; text: string }
 interface ScanResult { missing: boolean; stopped: boolean; truncatedTail: boolean; malformed: boolean; endPosition: number }
 interface RunObservation {
+  launch?: Record<string, unknown>;
+  applied?: Record<string, unknown>;
   metadata?: Record<string, unknown>;
   queuedAt?: string;
   executionStartedAt?: string;
@@ -115,10 +117,12 @@ export async function inspectRun({
   view,
   limitBytes = DEFAULT_PAGE_BYTES,
   cursor,
+  live = false,
 }: {
   runsDirectory: string;
   runId: string;
   view: RunInspectionView;
+  live?: boolean;
   limitBytes?: number;
   cursor?: string;
 }): Promise<RunInspectionPage> {
@@ -136,10 +140,16 @@ export async function inspectRun({
   const terminalStatus = asString(terminal?.status);
   const finalAvailable = isFinalAvailable(terminal);
 
-  if (view === "summary") {
+  if (view === "summary" || view === "launch") {
     if (decoded?.kind === "inspect" && decoded.source !== "summary") throw new Error("Cursor source does not match summary view");
     const observation = await readObservation(eventsPath, runId);
-    const text = JSON.stringify(summaryProjection(runId, summary, observation));
+    const text = JSON.stringify(view === "launch" ? {
+      runId,
+      intent: asRecord(summary.document?.metadata) ?? observation.metadata ?? "Evidence pending or unavailable",
+      execution: observation.launch ?? (terminal?.backendStarted === false ? "Never started" : summary.document ? "Not recorded" : live ? "Pending — execution settings not recorded yet" : "Interrupted or uncertain — launch settings unavailable"),
+      applied: observation.applied ?? "Not recorded; see execution for CLI settings",
+      backendInternalContext: "Not observable by this extension",
+    } : summaryProjection(runId, summary, observation), null, view === "launch" ? 2 : undefined);
     const revision = contentRevision(text);
     if (decoded?.kind === "inspect" && decoded.revision !== revision) throw staleCursorError();
     const offset = decoded?.kind === "inspect" ? decoded.textOffset : 0;
@@ -402,6 +412,10 @@ async function readObservation(eventsPath: string, runId: string): Promise<RunOb
     if (event.type === "run_started") {
       observation.metadata = asRecord(event.data);
       observation.queuedAt = asString(observation.metadata?.queuedAt) ?? event.timestamp;
+    } else if (event.type === "launch_resolved") {
+      observation.launch ??= asRecord(event.data);
+    } else if (event.type === "launch_applied") {
+      observation.applied ??= asRecord(event.data);
     } else if (event.type === "execution_started") {
       observation.executionStartedAt ??= event.timestamp;
     } else if (event.type === "process_started") {
@@ -839,7 +853,7 @@ function hasKeys(value: Record<string, unknown>, keys: string[]): boolean {
 }
 
 function isView(value: unknown): value is RunInspectionView {
-  return value === "output" || value === "diagnostics" || value === "summary" || value === "final";
+  return value === "output" || value === "diagnostics" || value === "summary" || value === "final" || value === "launch";
 }
 
 function isNonNegativeInteger(value: unknown): value is number {

package/src/core/spawn.ts

@@ -22,9 +22,9 @@ import {
 } from "./progress.ts";
 import { spawnClaudeSubagent } from "./claude.ts";
 import { spawnCodexSubagent } from "./codex.ts";
-import { spawnAgySubagent, isTransientAgyFailure } from "./agy.ts";
-import { spawnGrokSubagent } from "./grok.ts";
-import { museHasNestedAgentActivity, spawnMuseSubagent } from "./muse.ts";
+import { spawnAgySubagent, isTransientAgyFailure, normalizeAgyEffort } from "./agy.ts";
+import { spawnGrokSubagent, normalizeGrokReasoningEffort } from "./grok.ts";
+import { museHasNestedAgentActivity, spawnMuseSubagent, normalizeMuseReasoningEffort } from "./muse.ts";
 import { opencodeHasNestedAgentActivity, spawnOpencodeSubagent } from "./opencode.ts";
 import type {
   PermissionTier,
@@ -392,6 +392,34 @@ export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentT
     }
     return result;
   }
+  await record?.event("launch_resolved", {
+    roleInstructions: params.profile.systemPrompt,
+    appendedInstructions: params.appendInstructions ?? null,
+    outputSchema: params.outputSchema ?? params.customTools?.find(tool => tool.name === "structured_output")?.parameters ?? null,
+    context: params.context ?? { mode: "none" },
+    configuration: {
+      harness: selectorHarness(params.profile),
+      backend: params.profile.backend,
+      model: params.model ? `${params.model.provider}/${params.model.id}` : params.profile.model ?? "Backend default (not resolved by extension)",
+      thinkingRequested: params.thinkingLevel,
+      thinkingApplied: params.profile.backend === "pi" ? "Pending SDK initialization" :
+        params.profile.backend === "agy" ? normalizeAgyEffort(params.thinkingLevel) ?? "Backend default" :
+        params.profile.backend === "grok" ? normalizeGrokReasoningEffort(params.thinkingLevel) ?? "Backend default" :
+        params.profile.backend === "muse" ? normalizeMuseReasoningEffort(params.thinkingLevel) ?? "Backend default" : params.thinkingLevel ?? "Backend default",
+      thinkingApplication: "CLI effort argument, or SDK setting; not a claim about provider-internal reasoning",
+      requestedTools: params.profile.tools ?? "Backend defaults",
+      resourceLoading: params.profile.backend === "pi" ? { preset: effectivePiResourcePreset(params.profile.preset), projectTrusted: params.projectTrusted === true, contextFiles: "SDK-loaded; recorded after initialization", skills: effectivePiResourcePreset(params.profile.preset) === "skills" ? "Enabled; project skills require trust" : "Disabled", extensions: false, promptTemplates: false, themes: false } : "Backend-controlled; not fully observable",
+      tools: params.profile.backend === "pi" ? "Pending SDK initialization" : "Backend-controlled; requested tools recorded separately",
+      excludedTools: params.excludeTools,
+      workspace: params.ctx.cwd,
+      permissionRequested: params.permission ?? "default",
+      permissionEffective: permission,
+      timeoutMs: params.timeoutMs,
+      maxBudgetUsd: params.maxBudgetUsd ?? null,
+      budgetEnforced: (params.maxBudgetUsd ?? 0) > 0 && params.profile.backend === "claude",
+      resumeRunId: params.resumeRunId ?? null,
+    },
+  });
   let resumeSession: Awaited<ReturnType<typeof resolveResume>>["session"];
   if (params.resumeRunId) {
     const resolved = await resolveResume(runRecordsDirectory(), params.resumeRunId, params.profile.backend);
@@ -439,6 +467,7 @@ export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentT
     let result = await spawnSubagentRuntime({
       ...params,
       permission: effectiveTier,
+      runRecord: record,
       signal: timeout.signal,
       onBackendEvent,
       onProcessStart,
@@ -906,6 +935,12 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
       thinkingClamped = { requested: thinkingLevel, effective: session.thinkingLevel };
     }
 
+    await params.runRecord?.event("launch_applied", {
+      thinkingApplied: session.thinkingLevel,
+      tools: session.getActiveToolNames(),
+      contextFiles: resourceLoader.getAgentsFiles(),
+      systemPrompt: session.systemPrompt,
+    });
     if (signal) {
       abortHandler = () => {
         void session?.abort();

package/src/core/subagent-render.ts

@@ -253,7 +253,7 @@ export function renderCompactSubagentNode(
     ? ` ${theme.fg("muted", `${status === "running" ? "--" : "->"} ${formatActivityLineForDisplay(summary)}`)}`
     : "";
   return new Text(
-    `${indent}${subagentMarker(status, theme, frame, node.timedOut)} ${theme.fg(bodyColor, compactTitle(node))}${meta ? ` ${theme.fg("dim", meta)}` : ""}${preview}`,
+    `${indent}${subagentMarker(status, theme, frame, node.timedOut)} ${status === "error" || status === "aborted" ? theme.fg(bodyColor, compactTitle(node)) : compactTitle(node)}${meta ? ` ${theme.fg("dim", meta)}` : ""}${preview}`,
     0,
     0,
   );
@@ -305,13 +305,18 @@ export function renderSubagentNode(
   expanded = false,
   showAccess = true,
 ): Text | Container {
+  const displayNode = expanded ? node : { ...node, usage: undefined };
   const rendered = shouldRenderRichSubagent(node, runningCount)
-    ? renderRichSubagentNode(node, theme, frame, indent, now, showAccess)
-    : renderCompactSubagentNode(node, theme, frame, indent, now, showAccess);
-  if (!expanded || isActiveSubagentStatus(node.status)) {
-    return rendered;
+    ? renderRichSubagentNode(displayNode, theme, frame, indent, now, showAccess)
+    : renderCompactSubagentNode(displayNode, theme, frame, indent, now, showAccess);
+  if (isActiveSubagentStatus(node.status)) {
+    const active = new Container();
+    active.addChild(rendered);
+    active.addChild(new Text(`${indent}  ${theme.fg("muted", "Inspect")} ${expanded ? node.runId ?? node.externalRunId ?? "pending" : (node.runId ?? node.externalRunId)?.slice(-8) ?? "pending"} · ${theme.fg("accent", "/external runs")}`, 0, 0));
+    return active;
   }
 
+  if (!expanded) return rendered;
   const container = new Container();
   container.addChild(rendered);
   const output = node.result ?? node.assistantOutput?.messages.map((message) => message.text).join("\n\n");

package/src/external-command.ts

@@ -696,10 +696,18 @@ async function readSummary(options: ExternalCommandOptions, runId: string, ctx:
   return object(JSON.parse(text));
 }
 
-async function showPages(options: ExternalCommandOptions, runId: string, view: "output" | "diagnostics" | "final", ctx: ExtensionCommandContext): Promise<void> {
+async function showPages(options: ExternalCommandOptions, runId: string, view: "output" | "diagnostics" | "final" | "launch", ctx: ExtensionCommandContext): Promise<void> {
   let cursor: string | undefined;
   do {
-    const page = await runAction(options, { action: "inspect", runId, view, ...(cursor ? { cursor } : {}) }, ctx);
+    let page: ExternalRunsResult;
+    try {
+      page = await runAction(options, { action: "inspect", runId, view, ...(cursor ? { cursor } : {}) }, ctx);
+    } catch (error) {
+      if (!cursor || !(error instanceof Error) || !error.message.includes("Run changed while paging")) throw error;
+      ctx.ui.notify("Run changed while reading. Reopening the latest snapshot from page 1.", "info");
+      cursor = undefined;
+      page = await runAction(options, { action: "inspect", runId, view }, ctx);
+    }
     // The tool's `final` projection is deliberately a clean, narration-free
     // canonical-answer surface: unavailable is a bounded EMPTY page with
     // finalAvailable:false (true for both an agent run and a workflow — see
@@ -738,15 +746,17 @@ function formatSummaryHeader(summary: JsonObject): string {
 
 async function navigateRun(options: ExternalCommandOptions, runId: string, ctx: ExtensionCommandContext): Promise<void> {
   const summary = await readSummary(options, runId, ctx);
+  const observedAt = new Date().toISOString();
   const children = Array.isArray(summary.children) ? summary.children.map(object).filter((child) => typeof child.runId === "string") : [];
   const state = object(summary.state);
   const childChoices = children.map((child) => `Child ${String(child.runId)}${child.label ? ` · ${String(child.label)}` : ""}`);
-  const actions = ["Summary", "Output", "Final", "Diagnostics", ...childChoices, ...(state.status === "running" || state.status === "queued" ? ["Cancel run"] : []), "Back"];
+  const actions = ["Refresh", "Launch", "Summary", "Output", "Final", "Diagnostics", ...childChoices, ...(state.status === "running" || state.status === "queued" ? ["Cancel run"] : []), "Back"];
   while (true) {
     const choice = await ctx.ui.select(`Run ${runId}`, actions);
     if (!choice || choice === "Back") return;
-    if (choice === "Summary") await ctx.ui.editor(`summary ${runId}`, `${formatSummaryHeader(summary)}\n\n${JSON.stringify(summary, null, 2)}`);
-    else if (choice === "Output" || choice === "Final" || choice === "Diagnostics") await showPages(options, runId, choice.toLowerCase() as "output" | "final" | "diagnostics", ctx);
+    if (choice === "Refresh") return navigateRun(options, runId, ctx);
+    if (choice === "Summary") await ctx.ui.editor(`summary ${runId}`, `Snapshot ${observedAt} · Refresh for current state\n${formatSummaryHeader(summary)}\n\n${JSON.stringify(summary, null, 2)}`);
+    else if (choice === "Launch" || choice === "Output" || choice === "Final" || choice === "Diagnostics") await showPages(options, runId, choice.toLowerCase() as "output" | "final" | "diagnostics" | "launch", ctx);
     else if (choice === "Cancel run") {
       if (await ctx.ui.confirm("Cancel external run?", `${runId}\n\nStopping execution does not roll back side effects.`)) {
         const result = await runAction(options, { action: "cancel", runId, reason: "cancelled from /external runs" }, ctx);

package/src/external-runs.ts

@@ -32,8 +32,8 @@ const externalRunsParameters = Type.Object({
     maxItems: MAX_TARGETS,
     description: "Target run IDs (run_... agent, wf_... workflow). For inspect: a single-entry list [\"run_...\"] inspects that run with any view (summary, output, diagnostics, final); multiple entries (1-20 targets) batch summary inspect. For cancel: a single-entry list [\"run_...\"]. For wait: any|all of up to 100 targets.",
   })),
-  view: Type.Optional(StringEnum(["summary", "output", "diagnostics", "final"] as const, {
-    description: "inspect view: summary (state/timing/freshness/refs, default), output (assistant text plus canonical result, partial or final), diagnostics (tool activity/errors), final (only the verified canonical terminal answer, empty until a successful terminal boundary exists). Batch inspect (runIds) only supports summary.",
+  view: Type.Optional(StringEnum(["summary", "output", "diagnostics", "final", "launch"] as const, {
+    description: "inspect view: launch (recorded prompt, context and execution configuration; sensitive, explicit inspection only), summary (state/timing/freshness/refs, default), output (assistant text plus canonical result, partial or final), diagnostics (tool activity/errors), final (only the verified canonical terminal answer, empty until a successful terminal boundary exists). Batch inspect (runIds) only supports summary.",
   })),
   mode: Type.Optional(StringEnum(["any", "all"] as const, {
     description: "wait mode: any returns on the first terminal outcome; all waits for every target. Neither cancels pending work; an unsuccessful selected workflow returns early even in all mode.",
@@ -797,7 +797,9 @@ export function createExternalRunsTool(
             const nextCursor = page.nextOffset === undefined ? undefined : encodeProjectionCursor(params.runId, view, page.nextOffset, text);
             return result(page.text, { runId: params.runId, view, text: page.text, finalAvailable: true, nextCursor });
           }
-          const source = view === "summary"
+          const source = view === "launch"
+            ? { runId: params.runId, launch: (entry?.observation as WorkflowToolDetails | undefined)?.launch ?? historical?.launch ?? "Not recorded" }
+            : view === "summary"
             ? entry ? liveSummary(entry, true) : journalSummary(historical!, true)
             : view === "output"
               // Ternary, not ??: entry and historical are mutually exclusive, but a
@@ -835,7 +837,7 @@ export function createExternalRunsTool(
             return result(portion.text, { runId: params.runId, view, text: portion.text, outputStatus: entry.state === "running" ? "preliminary" : entry.outcome?.outcome === "succeeded" ? "final" : "interrupted", nextCursor });
           }
         }
-        const page = await inspectRun({ runsDirectory, runId: params.runId, view, limitBytes: params.limitBytes, cursor: params.cursor });
+        const page = await inspectRun({ runsDirectory, runId: params.runId, view, limitBytes: params.limitBytes, cursor: params.cursor, live: entry?.state === "running" });
         const text = page.items.map((item) => item.text).join("\n");
         // view: "final" stays a clean, narration-free canonical-answer
         // surface — a bounded empty page (finalAvailable:false) when

package/src/pi-subagent.ts

@@ -448,12 +448,16 @@ function createAgentTool(
           project,
           description: params.description,
           prompt: briefing.prompt,
+          authoredPrompt: params.prompt,
+          plannedConfiguration: { roleInstructions: profile.systemPrompt, model: profile.model, thinking: thinkingLevel, tools: profile.tools, permissionRequested: params.permission ?? "default", timeoutMs, maxBudgetUsd },
+          context: briefing.context ?? { mode: "none" },
           profile: profile.name,
           backend: profile.backend,
           harness: selectorHarness(profile),
           queuedAt: new Date(queuedAt).toISOString(),
         },
       });
+      await runRecord.event("intent_ready");
       const progress = createProgressNode(toolCallId, params.description, subagentType, "queued", profile.backend, selectorHarness(profile));
       progress.context = briefing.context;
       progress.queuedAt = queuedAt;
@@ -589,6 +593,7 @@ function createAgentTool(
           runId: runRecord.runId,
           recordPath: runRecord.directory,
           progress,
+          backgroundReceipt: true,
         },
       );
     },
@@ -639,14 +644,16 @@ function createAgentTool(
       const lines = [
         `${theme.bold("Delegating")} ${theme.bold(getBackendAgentLabel(backend))} ${theme.fg("muted", `→ ${subagentType}`)} · ${theme.fg("warning", tierLabel)}`,
         description ? `${theme.fg("muted", "Task")} ${description}` : "",
-        profile?.description ? `${theme.fg("muted", "Why")} ${profile.description}` : "",
+        profile?.description ? `${theme.fg("muted", "Role")} ${profile.description}` : "",
         formatSharedContext(args.context) ? `${theme.fg("muted", "Context")} ${formatSharedContext(args.context)}` : "",
         context.cwd ? `${theme.fg("muted", "Workspace")} ${context.cwd}` : "",
+        `${theme.fg("muted", "Mode")} ${args.background ? "Background" : "Foreground"}`,
       ].filter(Boolean);
       return new Text(lines.join("\n"), 0, 0);
     },
     renderResult(result, { expanded }, theme) {
       const details = result.details as SubagentToolDetails;
+      if (details.backgroundReceipt) return new Text(`${theme.bold("Started in background")}\n${theme.fg("muted", "Launch receipt — not a live monitor")}\n${theme.fg("muted", "Run")} ${expanded ? details.runId : details.runId?.slice(-8)} · ${theme.fg("accent", "/external runs")} ${theme.fg("muted", "to inspect or follow")}`, 0, 0);
       return renderSubagentNode(
         details.progress ?? details,
         theme,

package/src/types.ts

@@ -143,6 +143,8 @@ export interface WorkflowAgentSnapshot {
 }
 
 export interface WorkflowToolDetails {
+  launch?: unknown;
+  backgroundReceipt?: boolean;
   name: string;
   status: "running" | "completed" | "error" | "aborted";
   /**
@@ -243,6 +245,7 @@ export interface SubagentProgressNode {
 }
 
 export interface SubagentToolDetails {
+  backgroundReceipt?: boolean;
   context?: ParentContextReceipt;
   description: string;
   subagentType: SubagentType | "unknown";

package/src/workflow/journal.ts

@@ -27,6 +27,7 @@ export interface WorkflowRunIdentity {
 }
 
 export interface LoadedWorkflowJournal {
+  launch?: unknown;
   runId: string;
   path: string;
   agentResults: WorkflowCachedAgentResult[];
@@ -106,6 +107,7 @@ export async function loadWorkflowJournal(dir: string, runId: string): Promise<L
 
   const agentResults: WorkflowCachedAgentResult[] = [];
   const children: LoadedWorkflowJournal["children"] = [];
+  let launch: unknown;
   let seenRunStart = false;
   let name: string | undefined;
   let source: string | undefined;
@@ -131,6 +133,7 @@ export async function loadWorkflowJournal(dir: string, runId: string): Promise<L
         );
       }
       seenRunStart = entry.runId === runId;
+      launch = entry.launch;
       name = typeof entry.name === "string" ? entry.name : undefined;
       source = typeof entry.source === "string" ? entry.source : undefined;
       project = typeof entry.project === "string" ? entry.project : undefined;
@@ -189,7 +192,7 @@ export async function loadWorkflowJournal(dir: string, runId: string): Promise<L
   if (!seenRunStart) {
     throw new Error(`Workflow journal ${path} does not match run id ${runId}`);
   }
-  return { runId, path, agentResults, name, source, project, status, outcome, result, error: terminalError, children: children.filter(Boolean) };
+  return { launch, runId, path, agentResults, name, source, project, status, outcome, result, error: terminalError, children: children.filter(Boolean) };
 }
 
 export interface WorkflowJournalPage {
@@ -243,6 +246,7 @@ export async function listWorkflowJournals(dir: string, project: string, limit =
 }
 
 export async function createWorkflowJournalWriter(params: {
+  launch?: unknown;
   dir: string;
   identity: WorkflowRunIdentity;
   name: string;
@@ -251,12 +255,13 @@ export async function createWorkflowJournalWriter(params: {
   scriptPath?: string;
   resumeFromRunId?: string;
 }): Promise<WorkflowJournalWriter> {
-  await mkdir(params.dir, { recursive: true });
+  await mkdir(params.dir, { recursive: true, mode: 0o700 });
   const path = workflowJournalPath(params.dir, params.identity.runId);
   await writeFile(
     path,
     `${JSON.stringify({
       type: "run_start",
+      launch: params.launch,
       version: JOURNAL_VERSION,
       apiVersion: params.identity.apiVersion,
       runId: params.identity.runId,
@@ -268,7 +273,7 @@ export async function createWorkflowJournalWriter(params: {
       scriptHash: params.identity.scriptHash,
       argsHash: params.identity.argsHash,
     })}\n`,
-    "utf8",
+    { encoding: "utf8", mode: 0o600 },
   );
 
   let appendQueue = Promise.resolve();

package/src/workflow/runtime.ts

@@ -235,7 +235,7 @@ export async function runWorkflow<T = unknown>(
     state.resumePrefixActive = false;
 
     // Queue on the shared global cap. May reject if aborted while waiting.
-    const queuedEvent: WorkflowAgentQueuedEvent = { index, label, phase: assignedPhase, subagentType, prompt: taskPrompt, context: briefing.context };
+    const queuedEvent: WorkflowAgentQueuedEvent = { permission: call.permission, maxBudgetUsd: call.maxBudgetUsd, schema: call.schema, authoredPrompt: originalPrompt, index, label, phase: assignedPhase, subagentType, prompt: taskPrompt, context: briefing.context };
     await options.onAgentQueued?.(queuedEvent);
     const runRecord = queuedEvent.runRecord;
     if (runRecord) call.runRecord = runRecord;

package/src/workflow/source.ts

@@ -12,6 +12,7 @@ import {
   type WorkflowRunIdentity,
 } from "./journal.ts";
 import { loadSavedWorkflowRegistry, loadWorkflowScriptPath } from "./registry.ts";
+import { redactSecrets } from "../core/run-record.ts";
 import { parseWorkflowScript } from "./script-validation.ts";
 import type { WorkflowCachedAgentResult, WorkflowMetaPhase } from "./types.ts";
 
@@ -56,6 +57,7 @@ export type WorkflowToolParams = Static<typeof workflowToolParameters>;
 
 export type PreparedWorkflowToolSource = {
   script: string;
+  launch: unknown;
   metaName: string;
   plannedPhases?: WorkflowMetaPhase[];
   source: "inline" | "saved" | "path";
@@ -309,10 +311,17 @@ export async function prepareWorkflowToolSource(
     resumeAgentResults = journal.agentResults;
   }
 
+  const launch = redactSecrets({
+    name: metaName, description: parseWorkflowScript(script).meta.description,
+    source: source.source, sourcePath: source.sourcePath, script, args: params.args,
+    workspace: project, mode: params.background ? "background" : "foreground",
+    plannedPhases, resumeFromRunId,
+  });
   let journalWriter: WorkflowJournalWriter | undefined;
   if (sessionWorkflowDir) {
     try {
       journalWriter = await createWorkflowJournalWriter({
+        launch,
         dir: sessionWorkflowDir,
         identity,
         name: metaName,
@@ -339,6 +348,7 @@ export async function prepareWorkflowToolSource(
   return {
     ok: true,
     value: {
+      launch,
       script,
       metaName,
       plannedPhases,

package/src/workflow/tool.ts

@@ -7,7 +7,7 @@ import {
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Container, Text } from "@earendil-works/pi-tui";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import type { ConcurrencyLimiter } from "../core/concurrency.ts";
 import { isActiveSubagentStatus, isCompletedSubagentStatus, renderOutputText, renderSubagentNode } from "../core/subagent-render.ts";
 import { SPINNER_INTERVAL_MS } from "../core/spinner.ts";
@@ -24,6 +24,7 @@ import { loadExternalCatalog, resolveExternalProfile, selectorHarness, unknownEx
 import { effectivePiResourcePreset, loadHarnessConfigs } from "../harnesses.ts";
 import { WORKFLOW_PROMPT_SNIPPET } from "../prompts.ts";
 import { EXTERNAL_HARNESSES, type PermissionTier, type SubagentProfile, type SubagentToolDetails, type SubagentUsage, type WorkflowAgentSnapshot, type WorkflowToolDetails } from "../types.ts";
+import { parseWorkflowScript } from "./script-validation.ts";
 import { isWorkflowAbortError, runWorkflow } from "./runtime.ts";
 import { prepareWorkflowToolSource, workflowToolParameters } from "./source.ts";
 import { ChildRunError, type ChildRunOutcome, type WorkflowAgentRunner, type WorkflowSubagentDescriptor } from "./types.ts";
@@ -173,6 +174,7 @@ export function createWorkflowTool(
       } = prepared.value;
 
       const snapshot: WorkflowToolDetails = {
+        launch: prepared.value.launch,
         name: metaName,
         status: "running",
         agentCount: 0,
@@ -428,12 +430,16 @@ export function createWorkflowTool(
                 workflowRunId: identity.runId,
                 description: event.label,
                 prompt: event.prompt,
+                authoredPrompt: event.authoredPrompt,
+                plannedConfiguration: { roleInstructions: profile?.systemPrompt, model: profile?.model, thinking: profile?.thinking ?? thinkingLevel, tools: profile?.tools, timeoutMs, permissionRequested: event.permission ?? "default", maxBudgetUsd: event.maxBudgetUsd ?? profile?.maxBudgetUsd ?? defaultMaxBudgetUsd, outputSchema: event.schema ?? null, outputInstructions: event.schema ? "Schema-constrained output; backend-specific instructions resolved at start" : WORKFLOW_PLAIN_TEXT_OUTPUT_NOTE },
+                context: event.context ?? { mode: "none" },
                 profile: event.subagentType,
                 backend: profile?.backend,
                 harness: profile ? selectorHarness(profile) : undefined,
                 queuedAt: new Date(queuedAt).toISOString(),
               },
             });
+            await runRecord.event("intent_ready");
             event.runRecord = runRecord;
             snapshot.agents.push({
               index: event.index,
@@ -588,23 +594,41 @@ export function createWorkflowTool(
             : result.details.error ? { error: result.details.error } : {}),
         }),
       });
+      emit();
       if (!background) return await registered.result;
       return workflowResult(
         `Workflow "${metaName}" queued as ${identity.runId}. Use external_runs to inspect, wait, or cancel it.`,
-        cloneSnapshot(snapshot),
+        { ...cloneSnapshot(snapshot), backgroundReceipt: true },
       );
     },
-    renderCall(args, theme, _context) {
-      const name = typeof args.name === "string" && args.name.trim() ? ` ${theme.fg("muted", args.name.trim())}` : "";
-      return new Text(`${theme.bold("Workflow")}${name} · ${theme.fg("warning", "unsandboxed external agents")}`, 0, 0);
+    renderCall(args, theme, context) {
+      let name = args.name || (args.scriptPath ? basename(args.scriptPath) : "Preparing workflow");
+      let purpose = "";
+      const state = context.state as { script?: string; meta?: { name: string; description: string } };
+      if (typeof args.script === "string") {
+        if (state.script !== args.script) {
+          state.script = args.script;
+          state.meta = undefined;
+          try { state.meta = parseWorkflowScript(args.script).meta; } catch { /* Streamed arguments may be incomplete. */ }
+        }
+        if (state.meta) { name = state.meta.name; purpose = state.meta.description; }
+      }
+      return new Text([
+        `${theme.bold("Workflow")} ${name}`,
+        purpose ? `${theme.fg("muted", "Purpose")} ${purpose}` : "",
+        `${theme.fg("muted", "Source")} ${args.scriptPath ? (context.expanded ? args.scriptPath : basename(args.scriptPath)) : args.name ?? "Ad-hoc workflow"}`,
+        `${theme.fg("muted", "Workspace")} ${context.cwd}`,
+        `${theme.fg("muted", "Mode")} ${args.background ? "Background" : "Foreground"}`,
+        theme.fg("warning", "Host access · children may execute unsandboxed; inspect effective permissions"),
+      ].filter(Boolean).join("\n"), 0, 0);
     },
-    renderResult(result, { expanded }, theme) {
+    renderResult(result, { expanded }, theme, context) {
       // Pure function of the snapshot: the spinner frame is carried on the
       // snapshot itself and advanced by the runtime heartbeat in execute(), so
       // there is no UI-side timer to leak when a row is torn down or rendered in
       // a non-live context (e.g. HTML export).
       const details = result.details as WorkflowToolDetails;
-      return renderWorkflowSnapshot(details, theme, details.frame ?? 0, expanded);
+      return renderWorkflowSnapshot(details, theme, details.frame ?? 0, expanded, Boolean((context.state as { meta?: unknown } | undefined)?.meta));
     },
   });
 }
@@ -733,14 +757,23 @@ function renderFlatAgents(container: Container, details: WorkflowToolDetails, th
   }
 }
 
-function renderWorkflowSnapshot(details: WorkflowToolDetails, theme: Theme, frame: number, expanded: boolean): Container {
+function renderWorkflowSnapshot(details: WorkflowToolDetails, theme: Theme, frame: number, expanded: boolean, purposeShown = false): Container {
   const container = new Container();
+  const launch = details.launch as { description?: string } | undefined;
+  if (!purposeShown && launch?.description) container.addChild(new Text(`${theme.fg("muted", "Purpose")} ${launch.description}`, 0, 0));
+  const inspect = `${theme.fg("muted", "Run")} ${expanded ? details.runId : details.runId?.slice(-8)} · ${theme.fg("accent", "/external runs")} ${theme.fg("muted", "to inspect or follow")}`;
+  if (details.backgroundReceipt) {
+    container.addChild(new Text(`${theme.bold("Started in background")}\n${theme.fg("muted", "Launch receipt — not a live monitor")}\n${inspect}`, 0, 0));
+    return container;
+  }
+  if (details.runId) container.addChild(new Text(inspect, 0, 0));
+  if (!details.agents.length && details.status === "running") container.addChild(new Text("Preparing workflow · No assignments launched yet", 0, 0));
   const done = details.agents.filter((agent) => isCompletedSubagentStatus(agent.status)).length;
   const active = workflowRunningCount(details);
   const queued = details.agents.filter((agent) => agent.status === "queued").length;
   const failed = details.agents.filter(isFailedWorkflowAgent).length;
   const counts = formatAgentCounts(done, active, queued, failed, details.agents.length);
-  const access = details.status === "running" ? "external host access · " : "";
+  const access = "";
   container.addChild(
     new Text(
       `${theme.bold(`Workflow(${details.name})`)} ${theme.fg("dim", `${normalizeRunStatus(details.status)} · ${access}${counts}`)}`,

package/src/workflow/types.ts

@@ -1,7 +1,7 @@
 import type { ParentContextMessages, ParentContextReceipt } from "../core/parent-context.ts";
 import type { ConcurrencyLimiter } from "../core/concurrency.ts";
 import type { RunRecord } from "../core/run-record.ts";
-import type { SubagentAssistantOutput } from "../types.ts";
+import type { PermissionTier, SubagentAssistantOutput } from "../types.ts";
 
 export type ChildRunOutcome = "failed" | "cancelled" | "timed_out";
 
@@ -112,6 +112,10 @@ export interface WorkflowAgentResultEvent extends WorkflowCachedAgentResult {
 }
 
 export interface WorkflowAgentQueuedEvent {
+  permission?: PermissionTier;
+  maxBudgetUsd?: number;
+  schema?: unknown;
+  authoredPrompt?: string;
   index: number;
   label: string;
   phase?: string;