@herbertgao/pi-subagents 0.17.1 → 0.18.0

package/src/schedule.ts

@@ -281,8 +281,15 @@ export class SubagentScheduler {
         isolated: job.isolated,
         thinkingLevel: job.thinking,
         isolation: job.isolation,
+        // A scheduled run has no tool call to build this, so without it the
+        // conversation viewer shows nothing about how the job was configured.
+        // The model is left out on purpose: agent-manager fills in the effective
+        // one when the session reports it, and naming the pre-session pick here
+        // would only be right until then.
         invocation: {
           thinking: job.thinking,
+          // Normalized like the Agent tool's own snapshot: `0` means unlimited,
+          // and rendering it as "max turns: 0" would read as a limit of none.
           maxTurns: normalizeMaxTurns(job.max_turns),
           isolated: job.isolated,
           runInBackground: true,
@@ -301,7 +308,6 @@ export class SubagentScheduler {
 
     this.emit({ type: "fired", jobId: id, agentId, name: job.name })
 
-    const record = manager.getRecord(agentId)
     const finalize = (status: "success" | "error") => {
       const next = this.getNextRun(id)
       const current = store.get(id)
@@ -316,21 +322,20 @@ export class SubagentScheduler {
     // AgentManager's promise resolves either way (its .catch returns ""), so we
     // can't infer success/failure from the promise — read record.status instead.
     // Terminal states: completed/steered = success; error/aborted/stopped = error.
-    if (record?.promise) {
-      record.promise
-        .then(() => {
-          const r = manager.getRecord(agentId)
-          const failed =
-            r?.status === "error" ||
-            r?.status === "aborted" ||
-            r?.status === "stopped"
-          finalize(failed ? "error" : "success")
-        })
-        .catch(() => finalize("error"))
-    } else {
-      // Spawn returned without a promise (defensive — bypassQueue path always sets one).
-      finalize("success")
-    }
+    // awaitStartup first: with isolation: "worktree" the run promise only exists
+    // once the repo copy is made, and a failed copy rejects here.
+    manager
+      .awaitStartup(agentId)
+      .then(() => manager.getRecord(agentId)?.promise)
+      .then(() => {
+        const r = manager.getRecord(agentId)
+        const failed =
+          r?.status === "error" ||
+          r?.status === "aborted" ||
+          r?.status === "stopped"
+        finalize(failed ? "error" : "success")
+      })
+      .catch(() => finalize("error"))
   }
 
   private emit(event: ScheduleChangeEvent): void {

package/src/settings.ts

@@ -6,11 +6,36 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { getAgentDir } from "@earendil-works/pi-coding-agent"
 import { NO_FALLBACK } from "./agent-types.js"
-import type { JoinMode, ViewerMarkdownMode, WidgetMode } from "./types.js"
+import type {
+  AgentMentionMode,
+  JoinMode,
+  ViewerMarkdownMode,
+  WidgetMode,
+} from "./types.js"
 
 export interface SubagentsSettings {
   maxConcurrent?: number
-  /** Max concurrent blocking agents. 0 = unlimited (default). */
+  /**
+   * Max concurrent FOREGROUND (blocking) agents — `0` = unlimited, the default,
+   * which preserves the behaviour that has always applied: nothing bounded
+   * foreground work, and pi dispatches a message's tool calls through
+   * `Promise.all`, so an unqualified fan-out of blocking `Agent` calls runs all
+   * at once. Set it to bound that (#253 — on local models, parallel agents
+   * thrash the prompt cache).
+   *
+   * Deliberately independent of `maxConcurrent` rather than folded into it: a
+   * foreground agent blocks the parent anyway, so charging it to the background
+   * pool would let a saturated pool starve the main session of work it could
+   * have done itself.
+   *
+   * Bounds only spawns a caller is blocking on inline. Nested children are
+   * exempt — their parent is blocked awaiting them, so queueing a child behind
+   * its own parent would deadlock — and so are detached spawns from
+   * cross-extension RPC or `@handle` mentions, which block nobody and are
+   * documented to start immediately. Foreground `resume` is also outside the
+   * pool: it reuses an existing session and never reaches the spawn path, so
+   * several blocking resumes in one message can still exceed the limit.
+   */
   maxConcurrentForeground?: number
   /**
    * 0 = unlimited — the extension's single source of truth for that convention:
@@ -70,8 +95,14 @@ export interface SubagentsSettings {
   scopeModels?: boolean
   /**
    * When true, an unreadable or unparseable agent `.md` aborts extension load
-   * instead of being skipped with a warning. This applies only during startup;
-   * later per-call reloads remain tolerant. Defaults to false.
+   * instead of being skipped with a warning — pi exits, naming the file.
+   *
+   * Startup only, by design. Mid-session reloads (one per `Agent` call) keep
+   * warning: a bad edit at 3pm should not kill the session on the next
+   * unrelated spawn, where the failure would look disconnected from its cause.
+   * For a checked-in `.pi/agents/`, failing at startup is the point — the
+   * alternative is running a *different* agent than the file names.
+   * Defaults to false.
    */
   strictAgentFiles?: boolean
   /**
@@ -98,6 +129,34 @@ export interface SubagentsSettings {
    * the list never registers and the global key handler never captures input.
    */
   fleetView?: boolean
+  /**
+   * Whether `@handle message` typed at the prompt is routed to that subagent
+   * instead of the main model, and whether `@` offers running agents alongside
+   * pi's file completion. Defaults to `model`. Applied live.
+   *
+   *   - `model`: mentioning an agent that is not running asks the main model to
+   *     spawn it with the `Agent` tool, Claude Code's behaviour. Costs a turn,
+   *     and the model writes the agent's prompt rather than your text being it.
+   *   - `direct`: that agent is started here instead, with the typed message as
+   *     its prompt and no main-model turn spent.
+   *   - `off`: the input hook falls straight through and the stacked
+   *     autocomplete provider delegates everything back to pi's built-in one.
+   *
+   * Messaging a running agent and resuming a finished one are direct in both
+   * `model` and `direct`. The legacy booleans are still accepted: `true` reads
+   * as `model`, `false` as `off`.
+   */
+  agentMentions?: AgentMentionMode
+  /**
+   * Whether subagents persist their pi session by default, so `@handle` can
+   * reopen an agent's conversation long after its in-memory record is gone.
+   * Defaults to `true`. Per-agent `persist_session:` frontmatter overrides it
+   * in both directions. Turning it off restores the previous behaviour, where
+   * a handle stops resolving roughly ten minutes after the agent finishes and
+   * mentioning it starts a fresh run instead. Persisted sessions also appear
+   * nested under the spawning session in pi's `/resume`.
+   */
+  rememberAgents?: boolean
   /**
    * Display mode for the persistent above-editor agent widget:
    *   - `all`: show every agent (foreground + background).
@@ -143,6 +202,27 @@ export interface SubagentsSettings {
    * scheduler and the unvalidated cross-extension RPC path.
    */
   worktreeIsolation?: boolean
+  /**
+   * Master switch for scripted workflows. Defaults to `true`.
+   *
+   * Off is not a soft hide: the `SubagentWorkflow` tool is never registered, so
+   * the model is not told it exists and cannot call it, the `/agents`
+   * Workflows entry is hidden, and `--subagents-workflow-file` is refused.
+   *
+   * Absent is not the same as `true`. Unset means *auto*: on, but yielding to
+   * another extension that already offers a workflow tool, because two
+   * orchestrators in one tool spec is a worse default than none — the model
+   * has to guess which to call, and pays for both descriptions to find out.
+   * Setting it explicitly pins the answer in both directions: `true` keeps
+   * ours whatever else is loaded, `false` is off regardless. See
+   * `resolveWorkflowCollisions` in index.ts.
+   *
+   * Read once at extension init, before registration, so flipping it in
+   * `/agents → Settings` takes effect on the next pi session — the same
+   * contract `schedulingEnabled` has, and for the same reason: a tool spec is
+   * fixed once pi has it.
+   */
+  workflowsEnabled?: boolean
   /**
    * Hard ceiling on nested subagent delegation, counted from the main session:
    * main = 0, its subagents = 1, their children = 2. Defaults to `2`; `0` or `1`
@@ -202,9 +282,30 @@ export interface SubagentsSettings {
    * what the parent session counts.
    */
   showCost?: boolean
-  /** Show effective model and thinking level in running widget rows. */
+
+  /**
+   * Whether the widget's running rows name the model driving each agent and the
+   * thinking level it is running at.
+   *
+   * Off by default, unlike the tool result and the conversation viewer, which
+   * show the pair unconditionally: those have a line to themselves, while the
+   * widget row already carries the description, turns, tool uses, tokens and
+   * elapsed time, and every character it gains is one the description loses on a
+   * narrow terminal.
+   */
   showModel?: boolean
-  /** Markdown scope in the conversation viewer. Defaults to assistant. */
+  /**
+   * How much of the conversation viewer's transcript renders as Markdown.
+   * Defaults to `assistant`. Applied live — the viewer's `m` key cycles this
+   * same setting, so a choice made in the overlay persists like one made in
+   * `/agents → Settings`.
+   *
+   * Scoped rather than all-or-nothing because the two kinds of content have
+   * different contracts: assistant text is authored as Markdown, while a tool
+   * result is whatever bytes the tool produced. Rendering the latter as
+   * Markdown is lossy in ways that look like the tool misbehaved — see
+   * `ViewerMarkdownMode` for the specific rewrites — so `all` is opt-in.
+   */
   viewerMarkdown?: ViewerMarkdownMode
 }
 
@@ -224,9 +325,12 @@ export interface SettingsAppliers {
   setDisableDefaultAgents: (b: boolean) => void
   setToolDescriptionMode: (mode: ToolDescriptionMode) => void
   setFleetView: (b: boolean) => void
+  setAgentMentions: (mode: AgentMentionMode) => void
+  setRememberAgents: (b: boolean) => void
   setWidgetMode: (mode: WidgetMode) => void
   setOutputTranscript: (b: boolean) => void
   setWorktreeIsolation: (b: boolean) => void
+  setWorkflowsEnabled: (b: boolean) => void
   setMaxSubagentDepth: (n: number) => void
   setFallbackSubagent: (v: string | undefined) => void
   setReportUsage: (b: boolean) => void
@@ -252,6 +356,8 @@ const VALID_WIDGET_MODES: ReadonlySet<string> = new Set<WidgetMode>([
 ])
 const VALID_VIEWER_MARKDOWN_MODES: ReadonlySet<string> =
   new Set<ViewerMarkdownMode>(["off", "assistant", "all"])
+const VALID_AGENT_MENTION_MODES: ReadonlySet<string> =
+  new Set<AgentMentionMode>(["model", "direct", "off"])
 
 // Sanity ceilings — prevent hand-edited configs from asking for values that
 // make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
@@ -273,6 +379,8 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.maxConcurrent = r.maxConcurrent as number
   }
+  // Floor 0, not 1 like maxConcurrent above: 0 is the documented "unlimited"
+  // value and the default, so dropping it would silently be unrepresentable.
   if (
     Number.isInteger(r.maxConcurrentForeground) &&
     (r.maxConcurrentForeground as number) >= 0 &&
@@ -331,6 +439,19 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.fleetView === "boolean") {
     out.fleetView = r.fleetView
   }
+  // Was a boolean before the `model` mode existed. A hand-written or
+  // previously-written `true` means "on", which is now the default `model`.
+  if (typeof r.agentMentions === "boolean") {
+    out.agentMentions = r.agentMentions ? "model" : "off"
+  } else if (
+    typeof r.agentMentions === "string" &&
+    VALID_AGENT_MENTION_MODES.has(r.agentMentions)
+  ) {
+    out.agentMentions = r.agentMentions as AgentMentionMode
+  }
+  if (typeof r.rememberAgents === "boolean") {
+    out.rememberAgents = r.rememberAgents
+  }
   if (
     typeof r.widgetMode === "string" &&
     VALID_WIDGET_MODES.has(r.widgetMode)
@@ -358,6 +479,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.viewerMarkdown = r.viewerMarkdown as ViewerMarkdownMode
   }
+  if (typeof r.workflowsEnabled === "boolean") {
+    out.workflowsEnabled = r.workflowsEnabled
+  }
   if (r.fallbackSubagent === false) {
     // The only non-string spelling worth accepting: a boolean would otherwise be
     // dropped, silently leaving the PERMISSIVE default in place. Every string is
@@ -434,8 +558,9 @@ export function applySettings(
 ): void {
   if (typeof s.maxConcurrent === "number")
     appliers.setMaxConcurrent(s.maxConcurrent)
-  if (typeof s.maxConcurrentForeground === "number")
+  if (typeof s.maxConcurrentForeground === "number") {
     appliers.setMaxConcurrentForeground(s.maxConcurrentForeground)
+  }
   if (typeof s.defaultMaxTurns === "number")
     appliers.setDefaultMaxTurns(s.defaultMaxTurns)
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns)
@@ -456,6 +581,9 @@ export function applySettings(
   if (s.toolDescriptionMode)
     appliers.setToolDescriptionMode(s.toolDescriptionMode)
   if (typeof s.fleetView === "boolean") appliers.setFleetView(s.fleetView)
+  if (s.agentMentions) appliers.setAgentMentions(s.agentMentions)
+  if (typeof s.rememberAgents === "boolean")
+    appliers.setRememberAgents(s.rememberAgents)
   if (s.widgetMode) appliers.setWidgetMode(s.widgetMode)
   if (typeof s.outputTranscript === "boolean")
     appliers.setOutputTranscript(s.outputTranscript)
@@ -465,6 +593,8 @@ export function applySettings(
   if (typeof s.showCost === "boolean") appliers.setShowCost(s.showCost)
   if (typeof s.showModel === "boolean") appliers.setShowModel(s.showModel)
   if (s.viewerMarkdown) appliers.setViewerMarkdown(s.viewerMarkdown)
+  if (typeof s.workflowsEnabled === "boolean")
+    appliers.setWorkflowsEnabled(s.workflowsEnabled)
 }
 
 /**

package/src/structured-output.ts

@@ -0,0 +1,136 @@
+/**
+ * structured-output.ts — the synthetic tool behind `agent(prompt, { schema })`.
+ *
+ * A workflow script that passes a `schema` wants an *object* back, not prose it
+ * has to parse. Claude Code does this by giving the child a `StructuredOutput`
+ * tool whose input schema is the caller's schema, so the provider fills the
+ * fields, and returning the validated payload as the agent's result.
+ *
+ * We do the same, with one gap named up front: Claude Code *forces* the call,
+ * and we cannot. `toolChoice` exists in pi-ai's provider layer but is not
+ * plumbed through `AgentSession`, so an extension has no way to require a
+ * particular tool. What we have instead is three softer pressures —
+ *
+ *   1. `constrainedSampling`, so providers that support it hold the payload to
+ *      the schema at sampling time;
+ *   2. the tool's description, snippet and guideline, which say the answer must
+ *      come through this call;
+ *   3. validation here, answering a bad payload with `isError` so the model
+ *      sees what was wrong and calls again inside the same run.
+ *
+ * — and, when all three fail, one more prompt from `runAgent`. See
+ * {@link structuredRetryPrompt}.
+ *
+ * The name matches Claude Code's exactly, so a ported prompt that mentions
+ * `StructuredOutput` is still telling the truth.
+ */
+
+import {
+  defineTool,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent"
+import type { CompiledSchema } from "./workflow/json-schema.js"
+
+/**
+ * Deliberately NOT added to `SUBAGENT_TOOL_NAMES`: that list becomes
+ * `EXCLUDED_TOOL_NAMES`, which is exactly the denial this tool has to avoid.
+ * Nor to `BUILTIN_TOOL_NAMES` — it is ours to inject, never a name a user may
+ * ask for in an agent's `tools:` frontmatter.
+ */
+export const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput"
+
+/** What the child produced, filled in as the tool is called. */
+export interface StructuredCapture {
+  /** The last payload that validated, canonicalised. Absent until one does. */
+  json?: string
+  /** Why the most recent attempt was rejected, for the retry prompt. */
+  lastError?: string
+  /** Whether the tool was called at all — "never tried" reads differently. */
+  called: boolean
+}
+
+export function createStructuredCapture(): StructuredCapture {
+  return { called: false }
+}
+
+/**
+ * Build the tool for one child.
+ *
+ * `capture` is the box the caller reads afterwards. It is passed in rather than
+ * returned so `runAgent` owns its lifetime and can consult it on every exit
+ * path, including the ones where the tool was never reached.
+ */
+export function createStructuredOutputTool(
+  compiled: CompiledSchema,
+  capture: StructuredCapture,
+): ToolDefinition {
+  return defineTool({
+    name: STRUCTURED_OUTPUT_TOOL_NAME,
+    label: "Structured Output",
+    description:
+      "Report your final answer. Call this exactly once, with the complete result, and put everything the " +
+      "caller needs inside the arguments — text written outside this call is discarded. If a call is " +
+      "rejected for not matching the schema, fix the reported fields and call it again.",
+    promptSnippet: "Report your final answer as structured data",
+    promptGuidelines: [
+      "Your final answer MUST be reported by calling StructuredOutput. Prose outside that call is discarded.",
+    ],
+    // The caller's schema *is* the tool's input schema, verbatim — that is what
+    // makes the provider fill the fields. pi types this as TypeBox's `TSchema`,
+    // which v1 defines as an open interface, so a plain JSON Schema satisfies
+    // it without a cast at runtime or a conversion at author time.
+    parameters: compiled.schema as never,
+    // "prefer", not "require": a provider that cannot constrain sampling should
+    // fall through to validation-and-retry rather than fail the call outright.
+    constrainedSampling: { type: "json_schema", strict: "prefer" },
+    // Models occasionally send the whole payload as one JSON string instead of
+    // an object. Recovering that costs nothing and saves a whole retry.
+    prepareArguments: (args: unknown) => {
+      if (typeof args !== "string") return args as never
+      try {
+        return JSON.parse(args) as never
+      } catch {
+        return args as never
+      }
+    },
+    execute: async (_toolCallId, params) => {
+      capture.called = true
+      const verdict = compiled.check(params)
+      if (verdict !== true) {
+        capture.lastError = verdict
+        // `isError` puts the reason in front of the model as a tool result, so
+        // it can correct itself inside this same run. This is where most
+        // mismatches are resolved; the prompt-level retry is the backstop.
+        return {
+          content: [
+            {
+              type: "text",
+              text: `StructuredOutput did not match the required schema:\n${verdict}\nCall it again with a corrected value.`,
+            },
+          ],
+          isError: true,
+          details: {},
+        }
+      }
+      // Last valid call wins: a model that calls twice meant the second one.
+      capture.json = JSON.stringify(params)
+      capture.lastError = undefined
+      return { content: [{ type: "text", text: "Recorded." }], details: {} }
+    },
+  }) as ToolDefinition
+}
+
+/**
+ * The one extra prompt sent when a run ended with nothing captured.
+ *
+ * Distinguishes "never called it" from "called it wrongly" — the two need
+ * different corrections, and telling a model it got the shape wrong when it
+ * never answered at all sends it looking for a mistake it did not make.
+ */
+export function structuredRetryPrompt(capture: StructuredCapture): string {
+  const reason =
+    capture.called && capture.lastError !== undefined
+      ? `Your last ${STRUCTURED_OUTPUT_TOOL_NAME} call did not match the required schema: ${capture.lastError}`
+      : `You did not call ${STRUCTURED_OUTPUT_TOOL_NAME}, so your answer was not recorded.`
+  return `${reason}\n\nCall ${STRUCTURED_OUTPUT_TOOL_NAME} now with your complete final answer. Do not reply with prose.`
+}

package/src/types.ts

@@ -105,12 +105,75 @@ export type JoinMode = "async" | "group" | "smart"
  */
 export type WidgetMode = "all" | "background" | "off"
 
-/** How much of the conversation viewer renders as Markdown. */
+/**
+ * How much of the conversation viewer's transcript is rendered as Markdown.
+ * - `off`: every line wraps as literal text, as it did before the mode existed.
+ * - `assistant`: assistant text renders as Markdown; tool results stay verbatim
+ *   and dim. The default, because assistant text *is* Markdown by contract
+ *   while a tool result is arbitrary bytes — a Markdown pass over a log or a
+ *   diff eats `#` from shell comments, swallows a `---` line into a setext
+ *   heading, re-fences indented output and redraws `| a | b |` as a table.
+ *   (Ordered-list renumbering is the one such rewrite actively suppressed —
+ *   see `MARKDOWN_OPTIONS` — because it silently changes data, not layout.)
+ * - `all`: tool results render as Markdown too, for tools that genuinely emit
+ *   it (#210's `ctx_execute`), accepting the rewrites above on ones that don't.
+ */
 export type ViewerMarkdownMode = "off" | "assistant" | "all"
 
+/**
+ * How `@handle message` starts an agent that is not already running.
+ * - `model`: inject Claude Code's `agent_mention` reminder and let the main
+ *   model spawn it with the `Agent` tool, which is what Claude Code does.
+ * - `direct`: spawn it here, immediately, with the typed message as its prompt
+ *   and no main-model turn spent.
+ * - `off`: `@` means only "attach a file" again.
+ *
+ * Messaging a running agent and resuming a finished one are direct in every
+ * mode — Claude Code only differs from us on the *new* invocation.
+ */
+export type AgentMentionMode = "model" | "direct" | "off"
+
+/**
+ * What survives a record's eviction so `@handle` keeps working. The live record
+ * is discarded after ~10 minutes, but the pi session it wrote is still on disk,
+ * and this is the little that is needed to find and describe it again.
+ */
+export interface AgentTombstone {
+  handle: string
+  alias?: string
+  id: string
+  type: SubagentType
+  description: string
+  /** Always set — a record with no session file is never tombstoned. */
+  sessionFile: string
+  completedAt: number
+}
+
+/**
+ * What `@handle` resolved to: an agent still in memory, or the remains of one
+ * whose conversation can be reopened from disk.
+ */
+export type MentionResolution =
+  | { kind: "live"; record: AgentRecord }
+  | { kind: "tombstone"; entry: AgentTombstone }
+
 export interface AgentRecord {
   id: string
   type: SubagentType
+  /**
+   * Typeable name for the `@handle message` prompt mention, derived from the
+   * agent type and numbered when siblings collide (`explore`, `explore-2`).
+   * Top-level agents only — nested children are hidden from every top-level
+   * surface, so nothing can address them.
+   */
+  handle?: string
+  /**
+   * A second, memorable handle from the spawner's `name` (`@auth-audit`), drawn
+   * from the same namespace as `handle` so the two can never collide. Purely
+   * additive: `handle` is assigned regardless, so a named agent stays reachable
+   * by its type and `@explore` never comes to mean "start another one".
+   */
+  alias?: string
   description: string
   status:
     | "queued"
@@ -128,9 +191,21 @@ export interface AgentRecord {
   session?: AgentSession
   abortController?: AbortController
   promise?: Promise<string>
-  /** Whether a caller is awaiting this agent inline. */
+  /**
+   * A caller is awaiting this agent inline (`spawnAndWait`) — what
+   * `maxConcurrentForeground` bounds. Distinct from `isBackground === false`,
+   * which says only that the agent has an inline result surface: a detached
+   * cross-extension RPC spawn is foreground by that measure and yet blocks
+   * nobody, so it takes no slot.
+   */
   blocking?: boolean
-  /** Resolves when a queued blocking agent starts or is removed from the queue. */
+  /**
+   * Present only while the record is "queued": resolves when it leaves the
+   * queue, started or aborted. `spawnAndWait` waits on this because a queued
+   * record has no `promise` yet. Always resolves, never rejects — a rejection
+   * would escape into the caller's tool `execute` and take down pi's whole
+   * Promise.all tool batch.
+   */
   startGate?: Promise<void>
   groupId?: string
   joinMode?: JoinMode
@@ -141,11 +216,23 @@ export interface AgentRecord {
   /** Worktree info if the agent is running in an isolated worktree. */
   worktree?: { path: string; branch: string; baseSha: string; workPath: string }
   /** Worktree cleanup result after agent completion. */
-  worktreeResult?: { hasChanges: boolean; branch?: string }
+  worktreeResult?: {
+    hasChanges: boolean
+    branch?: string
+    path?: string
+    error?: string
+  }
   /** The tool_use_id from the original Agent tool call. */
   toolCallId?: string
   /** Path to the streaming output transcript file. */
   outputFile?: string
+  /**
+   * The agent's pi session file, when it was persisted (`persist_session`, or
+   * the `rememberAgents` default). Captured so a mention can reopen the
+   * conversation after the record itself has been evicted; undefined for an
+   * in-memory session, which leaves nothing to reopen.
+   */
+  sessionFile?: string
   /** Cleanup function for the output file stream subscription. */
   outputCleanup?: () => void
   /**
@@ -171,8 +258,27 @@ export interface AgentRecord {
   invocation?: AgentInvocation
   /** Nesting depth: top-level subagent = 1. */
   depth?: number
+  /**
+   * The validated `StructuredOutput` payload, as canonical JSON.
+   *
+   * Set only when the spawn asked for a schema. Separate from `result` because
+   * `result` is prose for a reader — previewed in the widget, written to the
+   * transcript, and appended to with the worktree branch note — and JSON that
+   * has been appended to no longer parses.
+   */
+  structuredJson?: string
+  /** Whether the child needed the extra structured-output prompt. */
+  structuredRetried?: boolean
   /** Parent agent ID for ownership-scoped nested controls. */
   parentAgentId?: string
+  /**
+   * The workflow run that owns this child, when a workflow spawned it.
+   *
+   * Owned the same way a nested child is owned by its parent: filtered out of
+   * every top-level surface, and outside the `maxConcurrent` pool. See
+   * `isTopLevelAgent`.
+   */
+  workflowId?: string
   /** Effective inherited nesting cap for this branch. */
   maxSubagentDepth?: number
   /**
@@ -183,17 +289,29 @@ export interface AgentRecord {
   rootSessionId?: string
 }
 
-/** Effective session level, including pi's display-only `off` value. */
+/**
+ * What a session reports as its level: pi's `ThinkingLevel` plus the `"off"` a
+ * model with thinking disabled reports. Display-only — spawning still takes a
+ * `ThinkingLevel`, so this widening cannot leak into an invocation.
+ */
 export type EffectiveThinkingLevel = ThinkingLevel | "off"
 
 export interface AgentInvocation {
-  /** Short model label for tight UI rows. */
+  /** Short display name for tight rows, e.g. "haiku 4.5". Always set once known. */
   modelName?: string
-  /** Canonical provider/model id. */
+  /** Canonical `provider/id`, for surfaces with room to disambiguate providers. */
   modelId?: string
+  /** The level actually in effect, once a session exists to report one. */
   thinking?: EffectiveThinkingLevel
-  /** Requested values retained only when the run used something else. */
+  /**
+   * What the caller asked for, kept only when they did not get it — pi clamped
+   * the level to the model's capabilities, or an agent file's frontmatter
+   * outranked the parameter (#182). The snapshot exists to answer "did the spawn
+   * honor my instructions?" (#62), which it cannot do if the request is lost, so
+   * neither `requested*` field is overwritten once set.
+   */
   requestedThinking?: EffectiveThinkingLevel
+  /** The caller's `model` parameter, as written, when an agent file's pin won. */
   requestedModel?: string
   maxTurns?: number
   isolated?: boolean