pi-code 0.8.0 → 1.0.0

package/extensions/question.ts

@@ -6,7 +6,7 @@
  * Multiple questions per call are not batched; ask sequentially.
  */
 
-import type { ExtensionAPI, Theme } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionContext, Theme } from '@earendil-works/pi-coding-agent'
 import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from '@earendil-works/pi-tui'
 import { Type } from 'typebox'
 
@@ -32,13 +32,38 @@ const OptionSchema = Type.Object({
   description: Type.Optional(Type.String({ description: 'Optional description shown below label' })),
 })
 
-export const QuestionParams = Type.Object({
+const SingleQuestion = Type.Object({
   question: Type.String({ description: 'The question to ask the user' }),
   header: Type.Optional(Type.String({ description: 'Short label for the question, shown above it (max 12 characters)', maxLength: 12 })),
   options: Type.Array(OptionSchema, { description: 'Options for the user to choose from (1-4)', minItems: 1, maxItems: 4 }),
   multiSelect: Type.Optional(Type.Boolean({ description: 'Allow selecting several options (space toggles, enter confirms)' })),
 })
 
+/** One question in the flat form, plus an optional batch for Claude's 1-4 questions.
+ * The flat fields stay the documented path: a schema offering two equally optional
+ * shapes gave smaller models nothing to follow, and they produced neither. */
+export const QuestionParams = Type.Object({
+  question: Type.Optional(Type.String({ description: 'The question to ask. Required, unless asking several via questions.' })),
+  options: Type.Optional(Type.Array(OptionSchema, { description: 'The 1-4 choices for this question, each {label, description?}. Required with question.', minItems: 1, maxItems: 4 })),
+  header: Type.Optional(Type.String({ description: 'Optional short label shown above the question (max 12 characters)', maxLength: 12 })),
+  multiSelect: Type.Optional(Type.Boolean({ description: 'Optional: allow selecting several options (space toggles, enter confirms)' })),
+  questions: Type.Optional(Type.Array(SingleQuestion, { description: 'Only to ask 2-4 questions in one call: each entry takes the same fields as above. Leave unset for a single question.', minItems: 1, maxItems: 4 })),
+})
+
+export interface QuestionSpec {
+  question: string
+  header?: string
+  options: DisplayOption[]
+  multiSelect?: boolean
+}
+
+/** Normalize either accepted shape into the list of questions to ask. */
+export function questionList(params: Partial<QuestionSpec> & { questions?: QuestionSpec[] }): QuestionSpec[] {
+  if (params.questions && params.questions.length > 0) return params.questions
+  if (typeof params.question === 'string') return [{ question: params.question, header: params.header, options: params.options ?? [], multiSelect: params.multiSelect }]
+  return []
+}
+
 function checkbox(checked: boolean | undefined): string {
   if (checked === undefined) return ''
   return checked ? '[x] ' : '[ ] '
@@ -121,157 +146,29 @@ export default function question(pi: ExtensionAPI) {
   pi.registerTool({
     name: 'question',
     label: 'Question',
-    description: 'Ask the user a question and let them pick from options. Use when you need user input to proceed.',
+    description:
+      'Ask the user a question and let them pick from options. Use when you need user input to proceed. Pass question and options, for example {"question": "Which one?", "options": [{"label": "alpha"}, {"label": "beta"}]}. To ask 2-4 questions at once, pass questions instead, with the same fields per entry.',
     parameters: QuestionParams,
 
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      if (!ctx.hasUI) {
-        return {
-          content: [{ type: 'text', text: 'Error: UI not available (running in non-interactive mode)' }],
-          details: {
-            question: params.question,
-            options: params.options.map((o) => o.label),
-            answer: null,
-          } as QuestionDetails,
-        }
-      }
-
-      if (params.options.length === 0) {
-        return {
-          content: [{ type: 'text', text: 'Error: No options provided' }],
-          details: { question: params.question, options: [], answer: null } as QuestionDetails,
-        }
-      }
-
-      const multiSelect = params.multiSelect === true
-      // The free-text option does not compose with checkbox selection, so it is single-select only.
-      const allOptions: DisplayOption[] = multiSelect ? [...params.options] : [...params.options, { label: 'Type something.', isOther: true }]
-
-      const result = await ctx.ui.custom<{ answer: string; wasCustom: boolean; index?: number } | null>((tui, theme, _kb, done) => {
-        let optionIndex = 0
-        let editMode = false
-        const checked: boolean[] = allOptions.map(() => false)
-        let cachedLines: string[] | undefined
-        let cachedWidth: number | undefined
-
-        const editorTheme: EditorTheme = {
-          borderColor: (s) => theme.fg('accent', s),
-          selectList: {
-            selectedPrefix: (t) => theme.fg('accent', t),
-            selectedText: (t) => theme.fg('accent', t),
-            description: (t) => theme.fg('muted', t),
-            scrollInfo: (t) => theme.fg('dim', t),
-            noMatch: (t) => theme.fg('warning', t),
-          },
-        }
-        const editor = new Editor(tui, editorTheme)
-
-        editor.onSubmit = (value) => {
-          const trimmed = value.trim()
-          if (trimmed) {
-            done({ answer: trimmed, wasCustom: true })
-          } else {
-            editMode = false
-            editor.setText('')
-            refresh()
-          }
-        }
-
-        function refresh() {
-          cachedLines = undefined
-          tui.requestRender()
-        }
-
-        function handleInput(data: string) {
-          if (editMode) {
-            if (matchesKey(data, Key.escape)) {
-              editMode = false
-              editor.setText('')
-              refresh()
-              return
-            }
-            editor.handleInput(data)
-            refresh()
-            return
-          }
-
-          if (matchesKey(data, Key.up)) {
-            optionIndex = Math.max(0, optionIndex - 1)
-            refresh()
-            return
-          }
-          if (matchesKey(data, Key.down)) {
-            optionIndex = Math.min(allOptions.length - 1, optionIndex + 1)
-            refresh()
-            return
-          }
-
-          if (multiSelect && data === ' ') {
-            checked[optionIndex] = !checked[optionIndex]
-            refresh()
-            return
-          }
-
-          if (matchesKey(data, Key.enter)) {
-            if (multiSelect) {
-              done({ answer: selectedLabels(allOptions, checked), wasCustom: false })
-              return
-            }
-            const selected = allOptions[optionIndex]
-            if (selected.isOther) {
-              editMode = true
-              refresh()
-            } else {
-              done({ answer: selected.label, wasCustom: false, index: optionIndex + 1 })
-            }
-            return
-          }
-
-          if (matchesKey(data, Key.escape)) {
-            done(null)
-          }
-        }
-
-        function render(width: number): string[] {
-          if (cachedLines && cachedWidth === width) return cachedLines
-          cachedWidth = width
-          cachedLines = buildQuestionLines({ width, question: params.question, header: params.header, options: allOptions, optionIndex, editMode, multiSelect, checked, editor, theme })
-          return cachedLines
-        }
-
-        return {
-          render,
-          invalidate: () => {
-            cachedWidth = undefined
-            cachedLines = undefined
-          },
-          handleInput,
-        }
-      })
-
-      // Build simple options list for details; header/multiSelect appear only when set,
-      // so single-select details are unchanged.
-      const simpleOptions = params.options.map((o) => o.label)
-      const base = { question: params.question, options: simpleOptions, ...(params.header ? { header: params.header } : {}), ...(multiSelect ? { multiSelect: true } : {}) }
-
-      if (!result) {
-        return {
-          content: [{ type: 'text', text: 'User cancelled the selection' }],
-          details: { ...base, answer: null } as QuestionDetails,
-        }
-      }
-
-      if (result.wasCustom) {
-        return {
-          content: [{ type: 'text', text: `User wrote: ${result.answer}` }],
-          details: { ...base, answer: result.answer, wasCustom: true } as QuestionDetails,
-        }
+    async execute(_toolCallId, rawParams, _signal, _onUpdate, ctx) {
+      const specs = questionList(rawParams as Partial<QuestionSpec> & { questions?: QuestionSpec[] })
+      if (specs.length === 0) {
+        return { content: [{ type: 'text', text: 'Error: No question provided' }], details: { question: '', options: [], answer: null } as QuestionDetails }
       }
-      const selectionText = multiSelect ? `User selected: ${result.answer || '(none)'}` : `User selected: ${result.index}. ${result.answer}`
-      return {
-        content: [{ type: 'text', text: selectionText }],
-        details: { ...base, answer: result.answer, wasCustom: false } as QuestionDetails,
+      if (specs.length === 1) return await askOne(specs[0], ctx)
+
+      // Several questions are asked in sequence; a cancel ends the run, since the
+      // remaining answers would be guesses about a flow the user just declined.
+      const texts: string[] = []
+      const collected: QuestionDetails[] = []
+      for (const spec of specs) {
+        const result = await askOne(spec, ctx)
+        const detail = result.details as QuestionDetails
+        collected.push(detail)
+        texts.push(`${spec.question}\n${result.content[0].text}`)
+        if (detail.answer === null) break
       }
+      return { content: [{ type: 'text', text: texts.join('\n\n') }], details: { ...collected[0], questions: collected } as QuestionDetails }
     },
 
     renderCall(args, theme, _context) {
@@ -288,7 +185,6 @@ export default function question(pi: ExtensionAPI) {
       }
       return new Text(text, 0, 0)
     },
-
     renderResult(result, _options, theme, _context) {
       const details = result.details as QuestionDetails | undefined
       if (!details) {
@@ -312,3 +208,153 @@ export default function question(pi: ExtensionAPI) {
     },
   })
 }
+
+async function askOne(params: QuestionSpec, ctx: ExtensionContext): Promise<{ content: Array<{ type: 'text'; text: string }>; details: QuestionDetails }> {
+  if (!ctx.hasUI) {
+    return {
+      content: [{ type: 'text', text: 'Error: UI not available (running in non-interactive mode)' }],
+      details: {
+        question: params.question,
+        options: params.options.map((o) => o.label),
+        answer: null,
+      } as QuestionDetails,
+    }
+  }
+
+  if (params.options.length === 0) {
+    return {
+      content: [{ type: 'text', text: 'Error: No options provided' }],
+      details: { question: params.question, options: [], answer: null } as QuestionDetails,
+    }
+  }
+
+  const multiSelect = params.multiSelect === true
+  // The free-text option does not compose with checkbox selection, so it is single-select only.
+  const allOptions: DisplayOption[] = multiSelect ? [...params.options] : [...params.options, { label: 'Type something.', isOther: true }]
+
+  const result = await ctx.ui.custom<{ answer: string; wasCustom: boolean; index?: number } | null>((tui: Parameters<Parameters<ExtensionContext['ui']['custom']>[0]>[0], theme: Theme, _kb: unknown, done: (value: { answer: string; wasCustom: boolean; index?: number } | null) => void) => {
+    let optionIndex = 0
+    let editMode = false
+    const checked: boolean[] = allOptions.map(() => false)
+    let cachedLines: string[] | undefined
+    let cachedWidth: number | undefined
+
+    const editorTheme: EditorTheme = {
+      borderColor: (s) => theme.fg('accent', s),
+      selectList: {
+        selectedPrefix: (t) => theme.fg('accent', t),
+        selectedText: (t) => theme.fg('accent', t),
+        description: (t) => theme.fg('muted', t),
+        scrollInfo: (t) => theme.fg('dim', t),
+        noMatch: (t) => theme.fg('warning', t),
+      },
+    }
+    const editor = new Editor(tui, editorTheme)
+
+    editor.onSubmit = (value) => {
+      const trimmed = value.trim()
+      if (trimmed) {
+        done({ answer: trimmed, wasCustom: true })
+      } else {
+        editMode = false
+        editor.setText('')
+        refresh()
+      }
+    }
+
+    function refresh() {
+      cachedLines = undefined
+      tui.requestRender()
+    }
+
+    function handleInput(data: string) {
+      if (editMode) {
+        if (matchesKey(data, Key.escape)) {
+          editMode = false
+          editor.setText('')
+          refresh()
+          return
+        }
+        editor.handleInput(data)
+        refresh()
+        return
+      }
+
+      if (matchesKey(data, Key.up)) {
+        optionIndex = Math.max(0, optionIndex - 1)
+        refresh()
+        return
+      }
+      if (matchesKey(data, Key.down)) {
+        optionIndex = Math.min(allOptions.length - 1, optionIndex + 1)
+        refresh()
+        return
+      }
+
+      if (multiSelect && data === ' ') {
+        checked[optionIndex] = !checked[optionIndex]
+        refresh()
+        return
+      }
+
+      if (matchesKey(data, Key.enter)) {
+        if (multiSelect) {
+          done({ answer: selectedLabels(allOptions, checked), wasCustom: false })
+          return
+        }
+        const selected = allOptions[optionIndex]
+        if (selected.isOther) {
+          editMode = true
+          refresh()
+        } else {
+          done({ answer: selected.label, wasCustom: false, index: optionIndex + 1 })
+        }
+        return
+      }
+
+      if (matchesKey(data, Key.escape)) {
+        done(null)
+      }
+    }
+
+    function render(width: number): string[] {
+      if (cachedLines && cachedWidth === width) return cachedLines
+      cachedWidth = width
+      cachedLines = buildQuestionLines({ width, question: params.question, header: params.header, options: allOptions, optionIndex, editMode, multiSelect, checked, editor, theme })
+      return cachedLines
+    }
+
+    return {
+      render,
+      invalidate: () => {
+        cachedWidth = undefined
+        cachedLines = undefined
+      },
+      handleInput,
+    }
+  })
+
+  // Build simple options list for details; header/multiSelect appear only when set,
+  // so single-select details are unchanged.
+  const simpleOptions = params.options.map((o) => o.label)
+  const base = { question: params.question, options: simpleOptions, ...(params.header ? { header: params.header } : {}), ...(multiSelect ? { multiSelect: true } : {}) }
+
+  if (!result) {
+    return {
+      content: [{ type: 'text', text: 'User cancelled the selection' }],
+      details: { ...base, answer: null } as QuestionDetails,
+    }
+  }
+
+  if (result.wasCustom) {
+    return {
+      content: [{ type: 'text', text: `User wrote: ${result.answer}` }],
+      details: { ...base, answer: result.answer, wasCustom: true } as QuestionDetails,
+    }
+  }
+  const selectionText = multiSelect ? `User selected: ${result.answer || '(none)'}` : `User selected: ${result.index}. ${result.answer}`
+  return {
+    content: [{ type: 'text', text: selectionText }],
+    details: { ...base, answer: result.answer, wasCustom: false } as QuestionDetails,
+  }
+}

package/extensions/skills.ts

@@ -15,6 +15,8 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { isProjectApprovedSilently } from './internal/project-approval.js'
+
 function isDirectory(target: string): boolean {
   try {
     return fs.statSync(target).isDirectory()
@@ -24,8 +26,13 @@ function isDirectory(target: string): boolean {
 }
 
 /** Existing `.claude/skills` directories, user first then project. */
-export function skillDirs(cwd: string, home: string): string[] {
-  const candidates = [path.join(home, '.claude', 'skills'), path.join(cwd, '.claude', 'skills')]
+/** Existing `.claude/skills` directories, user first then project. The project
+ * directory is included only for approved projects: pi's loader surfaces every skill's
+ * name and description to the model, so an untrusted repository would otherwise get
+ * text into the prompt without the user ever agreeing to load its config. */
+export function skillDirs(cwd: string, home: string, trusted: boolean): string[] {
+  const candidates = [path.join(home, '.claude', 'skills')]
+  if (trusted) candidates.push(path.join(cwd, '.claude', 'skills'))
   const dirs: string[] = []
   for (const dir of candidates) {
     if (!dirs.includes(dir) && isDirectory(dir)) dirs.push(dir)
@@ -35,7 +42,9 @@ export function skillDirs(cwd: string, home: string): string[] {
 
 export default function skillsExtension(pi: ExtensionAPI) {
   pi.on('resources_discover', async (_event, ctx) => {
-    const skillPaths = skillDirs(ctx.cwd, os.homedir())
+    // resources_discover fires after session_start, so the approval is already
+    // resolved; reading it silently keeps a second trust dialog off the screen.
+    const skillPaths = skillDirs(ctx.cwd, os.homedir(), isProjectApprovedSilently(ctx))
     return skillPaths.length > 0 ? { skillPaths } : undefined
   })
 }

package/extensions/subagent/README.md

@@ -7,7 +7,7 @@ Delegate tasks to specialized subagents with isolated context windows.
 - **Isolated context**: Each subagent runs in a separate `pi` process
 - **Streaming output**: See tool calls and progress as they happen
 - **Parallel streaming**: All parallel tasks stream updates simultaneously
-- **Background runs**: `{background: true}` returns a run id and notifies on completion; `{status: true}` lists runs and `{cancel: "<id>"}` stops one (signalling its process group); max 8 running at once
+- **Background runs**: `{background: true}` returns a run id and notifies on completion; `{status: true}` lists runs, `{cancel: "<id>"}` stops one (signalling its process group), and `{resume: "<id>", task: "..."}` continues a finished run under its own session, so the child keeps everything it already saw; max 8 running at once
 - **Bounded fan-out**: A subagent refuses to spawn subagents of its own (an env marker the tool honors: steering, not a sandbox)
 - **Markdown rendering**: Final output rendered with proper formatting (expanded view)
 - **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
@@ -111,11 +111,18 @@ System prompt for the agent goes here.
 
 Claude Code fields map onto pi where a sensible seam exists: `tools` and
 `disallowedTools` (comma string or YAML list) become pi's `--tools` /
-`--exclude-tools`; `effort` becomes the `:thinking` suffix on a pinned model;
+`--exclude-tools`; `effort` becomes the `:thinking` suffix on a pinned model, or
+`--thinking` when no model is pinned;
 `permissionMode: plan` selects a read-only toolset unless `tools` is set. Model
-aliases (`sonnet`, `opus`, `haiku`, `inherit`) run on the session's default
-model. Fields with no pi equivalent are ignored: `skills`, `memory`,
-`mcpServers`, `maxTurns`.
+aliases (`sonnet`, `opus`, `haiku`) resolve against the models this machine is
+authenticated for, falling back to the session's default model when that tier is
+unavailable; `inherit` is the session model by definition. `skills` names skills to preload: their bodies are inlined into the child's
+prompt, since a child pi process does not inherit the parent's skill discovery, and
+a name that resolves to nothing is reported in the prompt rather than dropped.
+Fields with no pi seam are ignored, each verified against pi's CLI rather than
+assumed: `maxTurns` (no turn-limit flag), `mcpServers` (a child reads MCP config
+from files, and writing config into the workspace to fake it would be worse than
+the gap), and `memory` (pi-code's memory is per project, not per agent).
 
 **Locations:**
 - `~/.claude/agents/*.md`, `~/.pi/agent/agents/*.md` - User-level (always loaded; `~/.pi` wins a name conflict)

package/extensions/subagent/agents.ts

@@ -54,6 +54,24 @@ function parseModelField(raw: unknown): string | undefined {
   return model && !CLAUDE_MODEL_ALIASES.has(model.toLowerCase()) ? model : undefined
 }
 
+/** The tier alias an agent asked for, kept so it can be resolved against the models
+ * this user is actually authenticated for. `inherit` is not a tier: it means the
+ * session model, which is also the fallback when a tier is unavailable. */
+function parseModelAlias(raw: unknown): string | undefined {
+  if (typeof raw !== 'string') return undefined
+  const alias = raw.trim().toLowerCase()
+  return alias !== 'inherit' && CLAUDE_MODEL_ALIASES.has(alias) ? alias : undefined
+}
+
+/** Resolve a Claude tier alias to a concrete model id the user can actually run.
+ * Returning undefined leaves the child on the session model, which is what the
+ * unresolvable case degraded to before and still does. */
+export function resolveModelAlias(alias: string | undefined, available: ReadonlyArray<{ id: string; provider?: string }>): string | undefined {
+  if (!alias || alias === 'inherit') return undefined
+  const needle = alias.toLowerCase()
+  return available.find((model) => model.id.toLowerCase().includes(needle))?.id
+}
+
 /** pi's extended thinking levels; Claude's effort values are a subset, so they map 1:1. */
 const THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
 
@@ -63,6 +81,55 @@ function parseEffortField(raw: unknown): string | undefined {
   return THINKING_LEVELS.has(effort) ? effort : undefined
 }
 
+/** Claude's `skills` frontmatter: a comma string or YAML list of skill names. */
+function parseSkillsField(raw: unknown): string[] | undefined {
+  let names: string[] = []
+  if (Array.isArray(raw)) names = raw.map(String)
+  else if (typeof raw === 'string') names = raw.split(',')
+  const cleaned = names.map((name) => name.trim()).filter(Boolean)
+  return cleaned.length > 0 ? cleaned : undefined
+}
+
+/** Inline the named skills into an agent's prompt. Claude preloads a subagent's
+ * `skills` at startup rather than letting it discover them, and a child pi process
+ * does not inherit the parent's skill discovery, so the bodies travel in the prompt.
+ * A name that resolves to nothing is reported rather than dropped: a silently missing
+ * instruction is worse than a visible gap. */
+export function withPreloadedSkills(prompt: string, skills: string[] | undefined, skillDirs: string[]): string {
+  if (!skills || skills.length === 0) return prompt
+  const sections: string[] = []
+  for (const name of skills) {
+    const body = readSkillBody(name, skillDirs)
+    sections.push(body === undefined ? `<skill name="${name}">(skill not found)</skill>` : `<skill name="${name}">\n${body.trim()}\n</skill>`)
+  }
+  return `${prompt}\n\n## Preloaded skills\n\n${sections.join('\n\n')}`
+}
+
+/** A skill name is a single directory or file stem, never a path. The name comes from
+ * agent frontmatter, which a repository can control, and the body is inlined into the
+ * prompt sent to the model, so a traversal would be an arbitrary-file read. */
+const SKILL_NAME = /^[A-Za-z0-9_.-]+$/
+
+function readSkillBody(name: string, skillDirs: string[]): string | undefined {
+  if (!SKILL_NAME.test(name) || name === '.' || name === '..') return undefined
+  for (const dir of skillDirs) {
+    const root = path.resolve(dir)
+    for (const candidate of [path.join(dir, name, 'SKILL.md'), path.join(dir, `${name}.md`)]) {
+      // Belt and braces against symlinks and platform path quirks: the file actually
+      // read must still sit under the skills directory it was resolved from.
+      if (!path.resolve(candidate).startsWith(root + path.sep)) continue
+      try {
+        const content = fs.readFileSync(candidate, 'utf-8')
+        const match = /^---\r?\n[\s\S]*?\r?\n---/.exec(content)
+        return match ? content.slice(match[0].length) : content
+      } catch {
+        // try the next shape
+      }
+    }
+  }
+  return undefined
+}
+
 /** permissionMode has no pi equivalent; 'plan' means a research agent, so translate
  * the intent into a read-only toolset unless the file pins tools itself. */
 const READ_ONLY_TOOLS = ['read', 'grep', 'find', 'ls']
@@ -90,6 +157,8 @@ function parseAgentFile(content: string, source: AgentSource, filePath: string):
     disallowedTools,
     model: parseModelField(frontmatter.model),
     effort: parseEffortField(frontmatter.effort),
+    modelAlias: parseModelAlias(frontmatter.model),
+    skills: parseSkillsField(frontmatter.skills),
     systemPrompt: body,
     source,
     filePath,
@@ -105,6 +174,10 @@ export interface AgentConfig {
   disallowedTools?: string[]
   model?: string
   effort?: string
+  /** Claude tier alias (`sonnet`/`opus`/`haiku`) when the file named one. */
+  modelAlias?: string
+  /** Skill names to inline into the child's prompt, per Claude's `skills` field. */
+  skills?: string[]
   systemPrompt: string
   source: AgentSource
   filePath: string

package/extensions/subagent/background.ts

@@ -18,6 +18,10 @@ export interface BackgroundRun {
   turns: number
   /** Set while running so the run can be cancelled; cleared on completion. */
   kill?: () => void
+  /** pi session the child ran under, so a follow-up can continue its context. */
+  sessionId: string
+  /** How the child was spawned, so a follow-up can repeat it with a new task. */
+  spawn: BackgroundSpawn
 }
 
 export interface BackgroundSpawn {
@@ -57,7 +61,7 @@ export function parseFinalOutputFromJsonl(jsonl: string): { text: string; turns:
   return { text, turns }
 }
 
-export function formatStatus(all: Iterable<BackgroundRun>): string {
+export function formatStatus(all: Iterable<Pick<BackgroundRun, 'id' | 'agent' | 'task' | 'state' | 'turns' | 'exitCode'>>): string {
   const lines = [...all].map((run) => {
     const label = run.state === 'running' ? 'running' : `${run.state} (exit ${run.exitCode ?? '?'}, ${run.turns} turns)`
     return `${run.id} ${run.agent}: ${label} - ${run.task.slice(0, 60)}`
@@ -81,15 +85,47 @@ export function backgroundStatusText(): string {
   return formatStatus(runs.values())
 }
 
+/** A finished run, so a caller can continue its session with a follow-up task. */
+export function backgroundRun(id: string): BackgroundRun | undefined {
+  return runs.get(id)
+}
+
+/** Re-spawn a finished run's session with a new task. The child is started with the
+ * same --session-id, so it continues with everything it already saw rather than
+ * re-deriving context the parent would have to repeat. */
+export function resumeBackgroundRun(id: string, task: string, onComplete: (run: BackgroundRun) => void): 'resumed' | 'still-running' | 'unknown' {
+  const run = runs.get(id)
+  if (!run) return 'unknown'
+  if (run.state === 'running') return 'still-running'
+  const args = run.spawn.args.map((arg) => (arg.startsWith('Task: ') ? `Task: ${task}` : arg))
+  run.state = 'running'
+  run.task = task
+  run.output = undefined
+  run.exitCode = undefined
+  driveRun(run, { ...run.spawn, args }, onComplete)
+  return 'resumed'
+}
+
 export function startBackgroundRun(agent: string, task: string, invocation: BackgroundSpawn, onComplete: (run: BackgroundRun) => void): string | null {
   // Checked here, synchronously with registration: callers await temp-file writes
   // between any check of their own and this call, so a parallel tool-call batch
   // could otherwise all pass that earlier check and overshoot the cap.
   if (activeBackgroundRuns() >= MAX_BACKGROUND_RUNS) return null
   const id = `bg-${randomUUID().slice(0, 8)}`
-  const run: BackgroundRun = { id, agent, task, state: 'running', turns: 0 }
+  // A stable session id per run: the child persists its session, so a follow-up can
+  // resume it instead of starting cold.
+  const sessionId = `pi-code-${id}-${randomUUID().slice(0, 8)}`
+  const args = invocation.args.map((arg) => (arg === '--no-session' ? '--session-id' : arg))
+  const withSession = args.includes('--session-id') ? args.flatMap((arg) => (arg === '--session-id' ? ['--session-id', sessionId] : [arg])) : args
+  const spawnSpec: BackgroundSpawn = { ...invocation, args: withSession }
+  const run: BackgroundRun = { id, agent, task, state: 'running', turns: 0, sessionId, spawn: spawnSpec }
   runs.set(id, run)
+  driveRun(run, spawnSpec, onComplete)
+  return id
+}
 
+/** Spawn the child for a run and wire its lifecycle back onto the record. */
+function driveRun(run: BackgroundRun, invocation: BackgroundSpawn, onComplete: (run: BackgroundRun) => void): void {
   const proc = spawn(invocation.command, invocation.args, {
     cwd: invocation.cwd,
     shell: false,
@@ -133,5 +169,4 @@ export function startBackgroundRun(agent: string, task: string, invocation: Back
     run.exitCode = 1
     complete()
   })
-  return id
 }