pi-code 0.9.0 → 1.0.1

package/README.md

@@ -13,6 +13,8 @@
 
 Claude Code experience for the [pi](https://pi.dev) coding agent, in one package. Point pi at a project that already has a `.claude/` directory and it reads your existing config: rules, commands, skills, hooks, output styles, MCP servers, and agents. It also adds the Claude Code features pi lacks: a todo overlay, checkpoints, memory, web search, and subagents.
 
+What a repository ships is treated as untrusted until you approve it: project MCP servers, hooks, agents, rules, output styles, commands and skills load only once you say yes.
+
 ![pi-code demo](demos/hero.gif)
 
 ## Install
@@ -37,19 +39,19 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 |---|---|---|
 | Global + project rules | `~/.claude/rules`, `.claude/rules` (+ `paths:` frontmatter scoping) | `claude-rules.ts` |
 | Custom slash commands | `.claude/commands/**/*.md` (namespaced `/dir:name`), `$ARGUMENTS`/`$1`, `` !`cmd` `` bash output, `@file` inlining, `allowed-tools`/`model`/`argument-hint` frontmatter; project commands gated on approval | `commands.ts` |
-| Skills | `.claude/skills` → pi skill discovery (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.ts` |
+| Skills | `.claude/skills` → pi skill discovery, project skills gated on approval (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.ts` |
 | Hooks | `.claude/settings.json` hooks: PreToolUse (blocks, rewrites input via `updatedInput`), PostToolUse (feedback and `additionalContext` land next to the tool result), PostToolUseFailure, SessionStart (context injection), UserPromptSubmit (blocks and injects context), Stop (a block continues the conversation), SubagentStart/SubagentStop, PreCompact, PostCompact, SessionEnd; Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort | `hooks.ts` |
 | Output styles | `.claude/output-styles` + active `outputStyle`; Claude replace semantics with `keep-coding-instructions`; bundled Explanatory/Learning/Proactive; `/output-style [name]` | `output-styles.ts` |
 | CLAUDE.md `@imports` | resolves `@path` imports pi's native loader skips; loads `CLAUDE.local.md` (approval-gated) | `context-imports.ts` |
-| MCP servers | user `~/.claude.json` (incl. per-project `projects[cwd]` local scope), `~/.pi/agent/mcp.json`; project `.mcp.json`, `.pi/mcp.json` (once approved; `enabledMcpjsonServers`/`disabledMcpjsonServers`/`enableAllProjectMcpServers` honored, consent keys only from non-repo settings); stdio/HTTP/SSE by `type`; `${VAR:-default}` expansion; `MCP_TIMEOUT`/`MCP_TOOL_TIMEOUT` | `mcp.ts` |
-| Project trust | prompts before loading project config (MCP servers, hooks, agents, rules, output styles) that pi would otherwise trust silently | `internal/project-approval.ts` |
-| Subagents / Task | builtin Explore/Plan/general-purpose agents, `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents`; agent roster with descriptions in the system prompt; background runs | `subagent/` |
+| MCP servers | user `~/.claude.json` (incl. per-project `projects[cwd]` local scope), `~/.pi/agent/mcp.json`; project `.mcp.json`, `.pi/mcp.json` (once approved; `enabledMcpjsonServers`/`disabledMcpjsonServers`/`enableAllProjectMcpServers` honored, consent keys only from non-repo settings); stdio/HTTP/SSE by `type`; `${VAR:-default}` expansion; `MCP_TIMEOUT`/`MCP_TOOL_TIMEOUT`; tools refresh on `list_changed` | `mcp.ts` |
+| Project trust | prompts before loading project config (MCP servers, hooks, agents, rules, output styles, commands, skills) that pi would otherwise trust silently | `internal/project-approval.ts` |
+| Subagents / Task | builtin Explore/Plan/general-purpose agents, `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents`; agent roster with descriptions in the system prompt; `skills` preload; background runs with cancel and resume | `subagent/` |
 | Plan mode | `plan_mode_complete` tool, exact tool snapshot/restore | `plan-mode/` |
 | Todo list | persistent overlay, status machine, compaction-safe | `todo.ts` |
-| Checkpoints / rewind | shadow-repo snapshots; restore overwrites checkpointed files, keeps files created later | `git-checkpoint.ts` |
-| Persistent memory | per-project memories, index injected each session | `memory.ts` |
+| Checkpoints / rewind | shadow-repo snapshots; restore overwrites checkpointed files, keeps files created later; 100 per session, repos pruned after 30 days | `git-checkpoint.ts` |
+| Persistent memory | per-project memories, index injected each session within Claude's 200-line/25KB bound; a save that would overflow it reports why | `memory.ts` |
 | WebSearch / WebFetch | key-free DuckDuckGo search, SSRF-guarded fetch | `web.ts` |
-| AskUserQuestion | one question with `header`, single- or `multiSelect` options, plus free-text; no multi-question batching | `question.ts` |
+| AskUserQuestion | 1-4 questions per call (asked in sequence), each with `header`, single- or `multiSelect` options, plus free-text | `question.ts` |
 | Statusline | Claude `statusLine` command contract (stdin JSON, `padding`, `refreshInterval`); built-in turn state + session cost fallback | `status-line.ts` |
 | Notifications | vendored example | `notify.ts` |
 

package/extensions/commands.ts

@@ -63,7 +63,11 @@ export default function commandsExtension(pi: ExtensionAPI) {
   async function runCommand(parsed: ParsedCommand, args: string, ctx: ExtensionCommandContext): Promise<void> {
     const withArgs = substituteArgs(parsed.body, args)
     const expanded = await expandDynamicContent(withArgs, ctx.cwd, async (shell) => {
-      const result = await pi.exec('/bin/sh', ['-c', shell], { timeout: BASH_TIMEOUT_MS })
+      // Hooks get CLAUDE_PROJECT_DIR, and a command's bash span is the same kind of
+      // project-scoped script. pi.exec takes no env, so it is exported in the script.
+      const projectDir = ctx.cwd.replaceAll("'", String.raw`'\''`)
+      const script = `export CLAUDE_PROJECT_DIR='${projectDir}'; ${shell}`
+      const result = await pi.exec('/bin/sh', ['-c', script], { cwd: ctx.cwd, timeout: BASH_TIMEOUT_MS })
       return { stdout: result.stdout, stderr: result.stderr, code: result.code }
     })
 

package/extensions/git-checkpoint.ts

@@ -34,6 +34,15 @@ interface Checkpoint {
  * for the life of the machine. */
 export const CHECKPOINT_RETENTION_DAYS = 30
 
+/** Claude keeps the 100 most recent checkpoints per session. Older ones drop off the
+ * rewind list; their commits stay in the shadow repo until the retention sweep. */
+export const MAX_CHECKPOINTS_PER_SESSION = 100
+
+/** The newest entries, up to the per-session cap, oldest first. */
+export function capCheckpoints<T>(all: T[]): T[] {
+  return all.length <= MAX_CHECKPOINTS_PER_SESSION ? all : all.slice(all.length - MAX_CHECKPOINTS_PER_SESSION)
+}
+
 /** Remove shadow repos untouched for longer than the retention window. The live
  * session's repo is always kept, whatever its age: a long session's directory mtime
  * can predate the window. Failures are ignored; this is housekeeping, not a gate. */
@@ -209,6 +218,10 @@ export default function gitCheckpointExtension(pi: ExtensionAPI) {
 
     const checkpoint: Checkpoint = { entryId: target.entryId, ref: snap.ref, prompt: target.prompt, createdAt: snap.createdAt }
     checkpoints.set(checkpoint.entryId, checkpoint)
+    // Bound the rewind list the way Claude does, dropping the oldest first.
+    for (const stale of [...checkpoints.keys()].slice(0, Math.max(0, checkpoints.size - MAX_CHECKPOINTS_PER_SESSION))) {
+      checkpoints.delete(stale)
+    }
     pi.appendEntry(CUSTOM_TYPE, checkpoint)
   })
 

package/extensions/mcp.ts

@@ -28,6 +28,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js' // NOSONAR
 import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js'
 import { Type } from 'typebox'
 import { MCP_TOOLS_CHANNEL, type McpToolAlias } from './internal/mcp-alias.js'
 import { capForContext } from './internal/output-guard.js'
@@ -317,8 +318,14 @@ async function connectWithTimeout(client: Client, transport: Parameters<Client['
   }
 }
 
-async function listAllTools(client: Client): Promise<Array<{ name: string; description?: string; inputSchema?: unknown }>> {
-  const tools: Array<{ name: string; description?: string; inputSchema?: unknown }> = []
+export interface McpToolInfo {
+  name: string
+  description?: string
+  inputSchema?: unknown
+}
+
+async function listAllTools(client: Client): Promise<McpToolInfo[]> {
+  const tools: McpToolInfo[] = []
   let cursor: string | undefined
   do {
     const page = await client.listTools({ cursor })
@@ -331,10 +338,73 @@ async function listAllTools(client: Client): Promise<Array<{ name: string; descr
 export default async function mcpExtension(pi: ExtensionAPI) {
   const clients = new Map<string, Client>()
   const status = new Map<string, { state: string; tools: number }>()
-  const registered = new Set<string>()
+  // pi tool name -> owning server, so a refresh can tell its own tools from a conflict.
+  const registered = new Map<string, string>()
   // Original server/tool names per registered pi name, for Claude-style hook matchers.
   const aliases: McpToolAlias[] = []
 
+  /** Register every not-yet-registered tool of a server; returns how many were added. */
+  function registerTools(name: string, config: ServerConfig, client: Client, tools: McpToolInfo[]): number {
+    let count = 0
+    for (const tool of tools) {
+      const toolName = formatToolName(name, tool.name)
+      const owner = registered.get(toolName)
+      if (owner === name) continue // already registered for this server: a refresh re-listing it
+      if (RESERVED_NAMES.has(toolName) || owner !== undefined) {
+        console.warn(`pi-code-mcp: skipping colliding tool name ${toolName}`)
+        continue
+      }
+      registered.set(toolName, name)
+      aliases.push({ pi: toolName, claude: `mcp__${name}__${tool.name}` })
+      count++
+      pi.registerTool({
+        name: toolName,
+        label: `${name}: ${tool.name}`,
+        description: tool.description ?? `MCP tool ${tool.name} from ${name}`,
+        parameters: Type.Unsafe(normalizeSchema(tool.inputSchema)),
+        async execute(_id, params) {
+          // Pass the timeout to the SDK too: its own default request timeout is 60s and
+          // would otherwise reject first, so the outer race at CALL_TIMEOUT_MS was dead.
+          // Claude's per-server timeout wins over MCP_TOOL_TIMEOUT, with a 1s floor.
+          const declared = typeof config.timeout === 'number' && config.timeout >= 1000 ? config.timeout : undefined
+          const budget = declared ?? callTimeoutMs()
+          const result = await withTimeout(client.callTool({ name: tool.name, arguments: params as Record<string, unknown> }, undefined, { timeout: budget }), budget, toolName)
+          const content = mapContent(result.content as McpContentBlock[], result.structuredContent)
+          const details: { error?: string } = {}
+          if (result.isError) {
+            details.error = 'tool_error'
+            const hint = JSON.stringify(normalizeSchema(tool.inputSchema))
+            content.push({ type: 'text', text: `Tool reported an error. Expected input schema: ${hint}` })
+          }
+          return { content, details }
+        },
+      })
+    }
+    return count
+  }
+
+  /** Claude refreshes tools on a server's list_changed notification. pi has no
+   * unregister, so a withdrawn tool keeps its registration and surfaces the server's
+   * own error when called; a newly announced one is registered without a restart. */
+  function subscribeToToolChanges(name: string, config: ServerConfig, client: Client): void {
+    try {
+      client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+        try {
+          const refreshed = await withTimeout(listAllTools(client), connectTimeoutMs(), `list tools ${name}`)
+          const added = registerTools(name, config, client, refreshed)
+          if (added === 0) return
+          const current = status.get(name)
+          status.set(name, { state: current?.state ?? 'connected', tools: (current?.tools ?? 0) + added })
+          pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])
+        } catch (error) {
+          console.warn(`pi-code-mcp: tool refresh failed for ${name}: ${error instanceof Error ? error.message : String(error)}`)
+        }
+      })
+    } catch {
+      // a transport or client without notification support simply never refreshes
+    }
+  }
+
   async function connectServers(servers: Record<string, ServerConfig>): Promise<void> {
     for (const [name, config] of Object.entries(servers)) {
       // A later scope must not take the name of a server that already connected: it
@@ -349,39 +419,8 @@ export default async function mcpExtension(pi: ExtensionAPI) {
         const client = await connect(name, config)
         clients.set(name, client)
         const tools = await withTimeout(listAllTools(client), connectTimeoutMs(), `list tools ${name}`)
-        let count = 0
-        for (const tool of tools) {
-          const toolName = formatToolName(name, tool.name)
-          if (RESERVED_NAMES.has(toolName) || registered.has(toolName)) {
-            console.warn(`pi-code-mcp: skipping colliding tool name ${toolName}`)
-            continue
-          }
-          registered.add(toolName)
-          aliases.push({ pi: toolName, claude: `mcp__${name}__${tool.name}` })
-          count++
-          pi.registerTool({
-            name: toolName,
-            label: `${name}: ${tool.name}`,
-            description: tool.description ?? `MCP tool ${tool.name} from ${name}`,
-            parameters: Type.Unsafe(normalizeSchema(tool.inputSchema)),
-            async execute(_id, params) {
-              // Pass the timeout to the SDK too: its own default request timeout is 60s and
-              // would otherwise reject first, so the outer race at CALL_TIMEOUT_MS was dead.
-              // Claude's per-server timeout wins over MCP_TOOL_TIMEOUT, with a 1s floor.
-              const declared = typeof config.timeout === 'number' && config.timeout >= 1000 ? config.timeout : undefined
-              const budget = declared ?? callTimeoutMs()
-              const result = await withTimeout(client.callTool({ name: tool.name, arguments: params as Record<string, unknown> }, undefined, { timeout: budget }), budget, toolName)
-              const content = mapContent(result.content as McpContentBlock[], result.structuredContent)
-              const details: { error?: string } = {}
-              if (result.isError) {
-                details.error = 'tool_error'
-                const hint = JSON.stringify(normalizeSchema(tool.inputSchema))
-                content.push({ type: 'text', text: `Tool reported an error. Expected input schema: ${hint}` })
-              }
-              return { content, details }
-            },
-          })
-        }
+        const count = registerTools(name, config, client, tools)
+        subscribeToToolChanges(name, config, client)
         status.set(name, { state: 'connected', tools: count })
       } catch (error) {
         status.set(name, { state: `failed: ${error instanceof Error ? error.message : String(error)}`, tools: 0 })

package/extensions/memory.ts

@@ -63,6 +63,40 @@ export function migrateLegacyStore(cwd: string): void {
   }
 }
 
+/** Whether adding this memory would push the index past what a session can load.
+ * Claude reports an explicit error instead of silently writing a memory that will
+ * never be seen; replacing an existing entry is not growth. */
+export function indexWouldOverflow(index: string, name: string, description: string): boolean {
+  // Editing an entry that already exists is always allowed: it adds no entry, and
+  // refusing it would strand a user whose index is already at the bound with no way
+  // to revise their way back under it. An over-long description is bounded anyway,
+  // since the injected index is capped at read time.
+  const isUpdate = index.split('\n').some((entry) => entry.startsWith(entryPrefix(name)))
+  if (isUpdate) return false
+  const next = upsertIndexLine(index, name, description)
+  return next.split('\n').length > INDEX_MAX_LINES || Buffer.byteLength(next, 'utf-8') > INDEX_MAX_BYTES
+}
+
+/** Write a memory and its index line, or say why it cannot be written. */
+export function saveMemory(dir: string, indexPath: string, name: string | undefined, description: string | undefined, content: string | undefined): { content: Array<{ type: 'text'; text: string }>; details: Record<string, never> } {
+  if (!name || !description || !content) {
+    return { content: [{ type: 'text', text: 'save requires name, description, and content.' }], details: {} }
+  }
+  const index = readIndex(dir)
+  // Claude reports an explicit error rather than writing a memory the next session
+  // would never load, and says what to do about it.
+  if (indexWouldOverflow(index, name, description)) {
+    return {
+      content: [{ type: 'text', text: `Memory index is full (${INDEX_MAX_LINES} entries or ${INDEX_MAX_BYTES} bytes). Delete or consolidate memories before saving ${name}.` }],
+      details: {},
+    }
+  }
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(path.join(dir, `${name}.md`), content)
+  fs.writeFileSync(indexPath, upsertIndexLine(index, name, description))
+  return { content: [{ type: 'text', text: `Saved memory ${name}.` }], details: {} }
+}
+
 /** The index as injected into the prompt, bounded like Claude's startup load. */
 export function capIndexForPrompt(index: string): string {
   const withinLines = index.split('\n').slice(0, INDEX_MAX_LINES)
@@ -151,13 +185,7 @@ export default function memoryExtension(pi: ExtensionAPI) {
       const indexPath = path.join(dir, INDEX_FILE)
 
       if (params.action === 'save') {
-        if (!name || !params.description || !params.content) {
-          return { content: [{ type: 'text' as const, text: 'save requires name, description, and content.' }], details: {} }
-        }
-        fs.mkdirSync(dir, { recursive: true })
-        fs.writeFileSync(path.join(dir, `${name}.md`), params.content)
-        fs.writeFileSync(indexPath, upsertIndexLine(readIndex(dir), name, params.description))
-        return { content: [{ type: 'text' as const, text: `Saved memory ${name}.` }], details: {} }
+        return saveMemory(dir, indexPath, name, params.description, params.content)
       }
 
       if (params.action === 'read') {

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,44 @@ 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 })),
+  header: Type.Optional(Type.String({ description: 'Short label for the question, shown above it, kept to 12 characters' })),
   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, kept to 12 characters' })),
+  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: shortHeader(params.header), options: params.options ?? [], multiSelect: params.multiSelect }]
+  return []
+}
+
+/** Claude keeps a header short for the label slot. Truncating is the forgiving read:
+ * rejecting the call costs a turn while the model recovers from a validation error,
+ * which is a poor trade for a display detail. */
+export const HEADER_MAX = 12
+export const shortHeader = (header: string | undefined): string | undefined => (header === undefined ? undefined : header.slice(0, HEADER_MAX))
+
 function checkbox(checked: boolean | undefined): string {
   if (checked === undefined) return ''
   return checked ? '[x] ' : '[ ] '
@@ -121,157 +152,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,
-        }
+    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 }
       }
-
-      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,
-        }
-      }
-      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 +191,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 +214,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: shortHeader(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: shortHeader(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
 }

package/extensions/subagent/index.ts

@@ -26,8 +26,9 @@ import { type Static, Type } from 'typebox'
 import { capForContext } from '../internal/output-guard.js'
 import { isProjectApproved, isProjectApprovedSilently } from '../internal/project-approval.js'
 import { SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
-import { type AgentConfig, type AgentScope, discoverAgents } from './agents.js'
-import { activeBackgroundRuns, backgroundStatusText, cancelBackgroundRun, MAX_BACKGROUND_RUNS, startBackgroundRun } from './background.js'
+import { skillDirs } from '../skills.js'
+import { type AgentConfig, type AgentScope, discoverAgents, resolveModelAlias, withPreloadedSkills } from './agents.js'
+import { activeBackgroundRuns, backgroundStatusText, cancelBackgroundRun, MAX_BACKGROUND_RUNS, resumeBackgroundRun, startBackgroundRun } from './background.js'
 
 const MAX_PARALLEL_TASKS = 8
 const MAX_CONCURRENCY = 4
@@ -259,6 +260,10 @@ interface RunAgentOptions {
   onUpdate?: OnUpdateCallback
   makeDetails: (results: SingleResult[]) => SubagentDetails
   onPhase?: SubagentPhaseSink
+  /** Skill directories to preload from, resolved where project trust is known. */
+  skillRoots?: string[]
+  /** Models this user can actually run, for resolving a tier alias. */
+  availableModels?: ReadonlyArray<{ id: string }>
 }
 
 /** Publishes a child run's start/stop for the hooks extension's SubagentStart/Stop. */
@@ -294,7 +299,7 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
     }
   }
 
-  const args = agentInvocationArgs(agent)
+  const args = agentInvocationArgs(agent, resolveModelAlias(agent.modelAlias, options.availableModels ?? []))
 
   let tmpPromptDir: string | null = null
   let tmpPromptPath: string | null = null
@@ -321,8 +326,9 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
   }
 
   try {
-    if (agent.systemPrompt.trim()) {
-      const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt)
+    const promptWithSkills = withPreloadedSkills(agent.systemPrompt, agent.skills, options.skillRoots ?? [])
+    if (promptWithSkills.trim()) {
+      const tmp = await writePromptToTempFile(agent.name, promptWithSkills)
       tmpPromptDir = tmp.dir
       tmpPromptPath = tmp.filePath
       args.push('--append-system-prompt', tmpPromptPath)
@@ -461,6 +467,7 @@ const SubagentParams = Type.Object({
   background: Type.Optional(Type.Boolean({ description: 'Run the single-mode task in the background: returns a run id immediately and a notification arrives when it completes.' })),
   status: Type.Optional(Type.Boolean({ description: 'Set true (alone, no other params) to list background runs instead of running anything.' })),
   cancel: Type.Optional(Type.String({ description: 'Background run id to cancel (from the id returned when it started, or from status).' })),
+  resume: Type.Optional(Type.String({ description: 'Finished background run id to continue with a follow-up task; the child keeps everything it already saw. Pass task with it.' })),
 })
 
 /**
@@ -490,6 +497,21 @@ type SubagentParamsStatic = Static<typeof SubagentParams>
 type ChainStepParam = Static<typeof ChainItem>
 type TaskItemParam = Static<typeof TaskItem>
 
+/** The completion notice a background run sends when it finishes. */
+export function backgroundCompletionText(run: { id: string; agent: string; state: string; turns: number; output?: string }): string {
+  const output = capForContext(run.output ?? '') || '(no output)'
+  return `Background subagent run ${run.id} (${run.agent}) ${run.state} after ${run.turns} turns.\n\n${output}`
+}
+
+/** What to tell the model about a resume request. */
+export function resumeResultText(id: string, task: string | undefined, onComplete: (run: { id: string; agent: string; state: string; turns: number; output?: string }) => void): string {
+  if (!task) return 'Pass task with resume: the follow-up needs an instruction.'
+  const outcome = resumeBackgroundRun(id, task, onComplete)
+  if (outcome === 'resumed') return `Resumed background run ${id} with the follow-up task; a notification will arrive on completion.`
+  if (outcome === 'still-running') return `Background run ${id} is still running; wait for it or cancel it first.`
+  return `Unknown background run: ${id}.\n\n${backgroundStatusText()}`
+}
+
 /** What to tell the model about a cancel request. */
 export function cancelResultText(id: string): string {
   const outcome = cancelBackgroundRun(id)
@@ -506,6 +528,8 @@ interface ModeContext {
   onUpdate: OnUpdateCallback | undefined
   makeDetails: MakeDetails
   onPhase?: SubagentPhaseSink
+  skillRoots: string[]
+  availableModels: ReadonlyArray<{ id: string }>
 }
 
 async function checkProjectAgentGate(params: SubagentParamsStatic, agents: AgentConfig[], ctx: ExtensionContext, projectAgentsDir: string | null, gateMode: SubagentMode, makeDetails: MakeDetails): Promise<ToolResult | null> {
@@ -539,11 +563,14 @@ async function checkProjectAgentGate(params: SubagentParamsStatic, agents: Agent
 }
 
 /** CLI args shared by foreground and background children, from the agent's config. */
-function agentInvocationArgs(agent: AgentConfig): string[] {
+function agentInvocationArgs(agent: AgentConfig, aliasModel?: string): string[] {
   const args: string[] = ['--mode', 'json', '-p', '--no-session']
-  // pi reads a thinking level from the model pattern's :suffix, so Claude's effort
-  // has a seam only when the agent pins a concrete model.
-  if (agent.model) args.push('--model', agent.effort ? `${agent.model}:${agent.effort}` : agent.model)
+  // A concrete model wins; otherwise a Claude tier alias resolved against the models
+  // this user can actually run. pi reads a thinking level from the model pattern's
+  // :suffix when a model is pinned, and from --thinking otherwise.
+  const model = agent.model ?? aliasModel
+  if (model) args.push('--model', agent.effort ? `${model}:${agent.effort}` : model)
+  else if (agent.effort) args.push('--thinking', agent.effort)
   if (agent.tools && agent.tools.length > 0) args.push('--tools', agent.tools.join(','))
   if (agent.disallowedTools && agent.disallowedTools.length > 0) args.push('--exclude-tools', agent.disallowedTools.join(','))
   return args
@@ -570,7 +597,7 @@ function removeTmpPrompt(tmpPrompt: { dir: string; filePath: string } | undefine
   }
 }
 
-async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConfig[], defaultCwd: string, pi: ExtensionAPI, makeDetails: MakeDetails): Promise<ToolResult> {
+async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConfig[], defaultCwd: string, pi: ExtensionAPI, makeDetails: MakeDetails, skillRoots: string[], availableModels: ReadonlyArray<{ id: string }>): Promise<ToolResult> {
   const task = params.task
   const agentName = params.agent
   if (!task || !agentName) {
@@ -590,10 +617,11 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
   if (activeBackgroundRuns() >= MAX_BACKGROUND_RUNS) {
     return backgroundCapResult(makeDetails)
   }
-  const args = agentInvocationArgs(agent)
+  const args = agentInvocationArgs(agent, resolveModelAlias(agent.modelAlias, availableModels))
   let tmpPrompt: { dir: string; filePath: string } | undefined
-  if (agent.systemPrompt.trim()) {
-    tmpPrompt = await writePromptToTempFile(agent.name, agent.systemPrompt)
+  const promptWithSkills = withPreloadedSkills(agent.systemPrompt, agent.skills, skillRoots)
+  if (promptWithSkills.trim()) {
+    tmpPrompt = await writePromptToTempFile(agent.name, promptWithSkills)
     args.push('--append-system-prompt', tmpPrompt.filePath)
   }
   args.push(`Task: ${task}`)
@@ -601,15 +629,7 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
   const id = startBackgroundRun(agent.name, task, { command: invocation.command, args: invocation.args, cwd: params.cwd ?? defaultCwd }, (run) => {
     removeTmpPrompt(tmpPrompt)
     pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id })
-    const output = capForContext(run.output ?? '') || '(no output)'
-    pi.sendMessage(
-      {
-        customType: 'subagent-background',
-        content: `Background subagent run ${run.id} (${run.agent}) ${run.state} after ${run.turns} turns.\n\n${output}`,
-        display: true,
-      },
-      { triggerTurn: true },
-    )
+    pi.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
   })
   if (id === null) {
     // Lost the cap race to a parallel batch: the atomic check inside startBackgroundRun refused.
@@ -659,6 +679,8 @@ async function runChainMode(chain: ChainStepParam[], mode: ModeContext): Promise
       onUpdate: chainUpdate,
       makeDetails: makeDetails('chain'),
       onPhase: mode.onPhase,
+      skillRoots: mode.skillRoots,
+      availableModels: mode.availableModels,
     })
     results.push(result)
 
@@ -774,6 +796,8 @@ async function runSingleMode(agentName: string, task: string, cwd: string | unde
     onUpdate,
     makeDetails: makeDetails('single'),
     onPhase: mode.onPhase,
+    skillRoots: mode.skillRoots,
+    availableModels: mode.availableModels,
   })
   const isError = result.exitCode !== 0 || result.stopReason === 'error' || result.stopReason === 'aborted'
   if (isError) {
@@ -1077,6 +1101,10 @@ function renderParallelResult(results: SingleResult[], expanded: boolean, theme:
 }
 
 export default function subagentExtension(pi: ExtensionAPI) {
+  const notifyBackgroundCompletion = (run: { id: string; agent: string; state: string; turns: number; output?: string }): void => {
+    pi.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
+  }
+
   // Claude surfaces each agent's description so the model can pick one autonomously.
   // Rebuilt per turn (agents are rediscovered per invocation too); project agents are
   // included only when the project is already approved, read without prompting, since
@@ -1129,6 +1157,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
           results,
         })
 
+      if (params.resume) {
+        return { content: [{ type: 'text', text: resumeResultText(params.resume, params.task, notifyBackgroundCompletion) }], details: makeDetails('single')([]) }
+      }
+
       if (params.cancel) {
         return { content: [{ type: 'text', text: cancelResultText(params.cancel) }], details: makeDetails('single')([]) }
       }
@@ -1157,9 +1189,16 @@ export default function subagentExtension(pi: ExtensionAPI) {
       const gateResult = await checkProjectAgentGate(params, agents, ctx, discovery.projectAgentsDir, gateMode, makeDetails)
       if (gateResult) return gateResult
 
-      if (params.background) return runBackgroundMode(params, agents, ctx.cwd, pi, makeDetails)
+      // Project skills only preload once the project is approved, matching the
+      // gate the skills extension applies to discovery itself.
+      const skillRoots = skillDirs(ctx.cwd, os.homedir(), isProjectApprovedSilently(ctx))
+      // Tier aliases resolve against what this user is authenticated for; an
+      // unavailable tier still falls back to the session model.
+      const availableModels = ctx.modelRegistry?.getAvailable?.() ?? []
+
+      if (params.background) return runBackgroundMode(params, agents, ctx.cwd, pi, makeDetails, skillRoots, availableModels)
 
-      const mode: ModeContext = { agents, defaultCwd: ctx.cwd, signal, onUpdate, makeDetails, onPhase: (phase, agentType, agentId) => pi.events.emit(SUBAGENT_CHANNEL, { phase, agentType, agentId }) }
+      const mode: ModeContext = { agents, defaultCwd: ctx.cwd, signal, onUpdate, makeDetails, skillRoots, availableModels, onPhase: (phase, agentType, agentId) => pi.events.emit(SUBAGENT_CHANNEL, { phase, agentType, agentId }) }
 
       if (params.chain?.length) return runChainMode(params.chain, mode)
       if (params.tasks?.length) return runParallelMode(params.tasks, mode)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "0.9.0",
+  "version": "1.0.1",
   "description": "Claude Code experience for the pi coding agent: reads your .claude config (rules, commands, skills, hooks, output styles, MCP servers, agents) and adds todo, checkpoints, memory, web, and subagents",
   "keywords": [
     "pi",