pi-code 1.0.30 → 1.0.32

package/extensions/hooks/decisions.ts

@@ -19,9 +19,14 @@ export interface HookDecision {
   ask?: boolean
 }
 
+/** Claude's stdout shape rule: only output that starts with `{` and ends with `}`
+ * (ignoring surrounding whitespace) is read as JSON output; a JSON array, a quoted
+ * string, or a bare number is plain text. Multi-line output whose lines each parse
+ * as JSON on their own with no output field set is plain text too (that case
+ * arrives here as a parse failure and hookJsonError sorts it from a real error). */
 export function tryParseJson(text: string):
   | {
-      hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string; additionalContext?: string; updatedInput?: unknown }
+      hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string; additionalContext?: string; updatedInput?: unknown; suppressOriginalPrompt?: boolean }
       decision?: string
       reason?: string
       continue?: boolean
@@ -32,13 +37,58 @@ export function tryParseJson(text: string):
       ok?: boolean
     }
   | undefined {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) return undefined
   try {
-    return JSON.parse(text)
+    const parsed: unknown = JSON.parse(trimmed)
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? (parsed as ReturnType<typeof tryParseJson>) : undefined
   } catch {
     return undefined
   }
 }
 
+/** Top-level JSON output fields; a multi-line output where a line sets one of
+ * these is a parse failure rather than plain text, as Claude documents. */
+const OUTPUT_FIELDS = new Set(['decision', 'reason', 'continue', 'stopReason', 'systemMessage', 'suppressOutput', 'hookSpecificOutput', 'updatedToolOutput', 'updatedMCPToolOutput', 'ok'])
+
+/** Claude reports a `<hook> hook error` notice when {..}-shaped stdout cannot be
+ * read as JSON output, and does not treat that stdout as plain text. Returns the
+ * error message for that case; undefined for valid JSON output and for output the
+ * shape rule already reads as plain text (including the multi-line case). */
+export function hookJsonError(text: string): string | undefined {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) return undefined
+  let parseError: string
+  try {
+    JSON.parse(trimmed)
+    return undefined
+  } catch (error) {
+    parseError = error instanceof Error ? error.message : String(error)
+  }
+  const lines = trimmed
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '')
+  if (lines.length >= 2 && !multiLineSetsOutputField(lines)) return undefined
+  return `invalid JSON output: ${parseError}`
+}
+
+/** Whether every line parses as JSON and at least one sets an output field; a
+ * non-JSON line means the multi-line rule does not apply (still a parse error). */
+function multiLineSetsOutputField(lines: string[]): boolean {
+  let setsField = false
+  for (const line of lines) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(line)
+    } catch {
+      return true // not all-JSON: the whole output is a parse failure
+    }
+    if (parsed !== null && typeof parsed === 'object' && Object.keys(parsed).some((key) => OUTPUT_FIELDS.has(key))) setsField = true
+  }
+  return setsField
+}
+
 /** The reason a JSON body's blocking decision carries, whichever spelling made it. */
 function jsonBlockingReason(parsed: ReturnType<typeof tryParseJson>): string | undefined {
   if (parsed?.hookSpecificOutput?.permissionDecision === 'deny') return parsed.hookSpecificOutput.permissionDecisionReason
@@ -94,6 +144,10 @@ function surfaceHookFailures(commands: HookCommand[], results: HookRunResult[],
   if (!notify) return
   for (const [i, result] of results.entries()) {
     if (result.spawnFailed) notify(`Hook failed to run: ${commands[i].command}: ${result.stderr.trim() || 'unknown error'}`)
+    // Claude shows a `<hook> hook error` notice when {..}-shaped stdout cannot be
+    // read as JSON output (exit 2 still blocks and reads its own channels).
+    const jsonError = result.code === 2 ? undefined : hookJsonError(result.stdout)
+    if (jsonError !== undefined) notify(`${commands[i].command} hook error: ${jsonError}`)
   }
 }
 
@@ -196,6 +250,8 @@ export interface PromptDecision {
   block: boolean
   reason?: string
   context: string
+  /** Claude's suppressOriginalPrompt: the hook's context replaces the prompt. */
+  suppress?: boolean
 }
 
 /** Additional context a UserPromptSubmit hook contributes: an explicit
@@ -203,6 +259,8 @@ export interface PromptDecision {
 export function promptContext(stdout: string): string {
   const parsed = tryParseJson(stdout)
   if (parsed) return parsed.hookSpecificOutput?.additionalContext ?? ''
+  // Malformed JSON output is an error, not plain text: no context is added.
+  if (hookJsonError(stdout) !== undefined) return ''
   return stdout.trim()
 }
 
@@ -221,13 +279,17 @@ export async function runUserPromptSubmit(config: HooksConfig, prompt: string, r
   }
   if (onSystemMessage) surfaceSystemMessages(results, onSystemMessage)
   const contexts: string[] = []
+  let suppress = false
   for (const result of results) {
     const decision = interpretHookResult(result.code, result.stdout, result.stderr)
     if (decision.block) return { block: true, reason: decision.reason, context: '' }
+    // Claude's suppressOriginalPrompt: any hook setting it hides the original
+    // prompt, and the collected context is what reaches the model.
+    if (tryParseJson(result.stdout)?.hookSpecificOutput?.suppressOriginalPrompt === true) suppress = true
     const context = promptContext(result.stdout)
     if (context) contexts.push(context)
   }
-  return { block: false, context: contexts.join('\n') }
+  return { block: false, context: contexts.join('\n'), suppress }
 }
 
 /** The feedback lines one PostToolUse/PostToolUseFailure result appends next to the

package/extensions/hooks/index.ts

@@ -187,6 +187,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
   /** Consecutive Stop-hook blocks with no user progress between them. Reset on user input
    * and on a non-blocking Stop; at the cap the continuation is suppressed and the turn ends. */
   let stopHookBlockCount = 0
+  /** Tool start times per call id, for Claude's duration_ms on PostToolUse: the
+   * clock starts after PreToolUse hooks and any confirm dialog resolve. */
+  const toolStartTimes = new Map<string, number>()
   /** The pending idle_prompt notification: Claude fires it when the turn ended about
    * 60 seconds ago and the user hasn't typed since, so it arms on agent_end and is
    * canceled by input or the next turn. */
@@ -337,7 +340,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
     if (!isSubagentPhaseEvent(data) || !sessionCtx) return
     const ctx = sessionCtx
     const eventName = data.phase === 'start' ? 'SubagentStart' : 'SubagentStop'
-    const payload = { hook_event_name: eventName, agent_type: data.agentType, agent_id: data.agentId }
+    // Claude's SubagentStop carries the subagent's final text; agent_transcript_path
+    // stays absent (a --no-session child writes no transcript, see docs/hooks.md).
+    const payload = { hook_event_name: eventName, agent_type: data.agentType, agent_id: data.agentId, ...(data.phase === 'stop' && data.lastAssistantMessage !== undefined ? { last_assistant_message: data.lastAssistantMessage } : {}) }
     try {
       const results = await runNotifyHooks(matchingCommands(config[eventName], data.agentType), payload, boundRunner(ctx))
       surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
@@ -417,13 +422,18 @@ export default function hooksExtension(pi: ExtensionAPI) {
       // additionalContext is delivered alongside the tool result, so stash it for
       // this call's tool_result to append.
       if (decision.context && decision.context.length > 0) pendingToolContext.set(event.toolCallId, decision.context)
+      // Claude's duration_ms excludes PreToolUse hook time, so the clock starts here.
+      toolStartTimes.set(event.toolCallId, Date.now())
       return undefined
     }
     // Claude's "ask": prompt the user and let the call through if they approve.
     // With no UI (headless) the block stands, which is the safe default.
     if (decision.ask && ctx.hasUI) {
       const approved = await ctx.ui.confirm(`Allow ${event.toolName}?`, decision.reason ?? 'A hook asks you to confirm this tool call.')
-      return approved ? undefined : blockedToolCall(decision.reason)
+      if (!approved) return blockedToolCall(decision.reason)
+      // Claude's duration_ms also excludes time in permission prompts.
+      toolStartTimes.set(event.toolCallId, Date.now())
+      return undefined
     }
     return blockedToolCall(decision.reason)
   })
@@ -451,7 +461,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
     if (commands.length === 0 && pending.length === 0) return
     const translatedInput = alias === undefined ? claudeToolInput(event.toolName, event.input, ctx.cwd) : undefined
     const response = (alias === undefined && !event.isError ? claudeToolResponse(event.toolName, event.input, textContent(event.content), event.isError, ctx.cwd) : undefined) ?? { content: event.content, details: event.details, isError: event.isError }
-    const payload = { hook_event_name: eventName, tool_name: translatedName ?? event.toolName, tool_input: translatedInput ?? event.input, tool_response: response }
+    const startedAt = toolStartTimes.get(event.toolCallId)
+    toolStartTimes.delete(event.toolCallId)
+    const payload = { hook_event_name: eventName, tool_name: translatedName ?? event.toolName, tool_input: translatedInput ?? event.input, tool_response: response, ...(startedAt === undefined ? {} : { duration_ms: Date.now() - startedAt }) }
     const run = boundRunner(ctx, { tool_use_id: event.toolCallId })
     const results = await Promise.all(commands.map((command) => run(command, payload, timeoutMs(command))))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
@@ -515,8 +527,10 @@ export default function hooksExtension(pi: ExtensionAPI) {
       return { action: 'handled' }
     }
     // Claude injects a UserPromptSubmit hook's context ahead of the prompt; transform is
-    // pi's seam for rewriting the submitted text.
-    if (decision.context) return { action: 'transform', text: `${decision.context}\n\n${event.text}` }
+    // pi's seam for rewriting the submitted text. With suppressOriginalPrompt the
+    // context replaces the prompt entirely (honored only when context exists, since
+    // an empty submission would be no turn at all).
+    if (decision.context) return { action: 'transform', text: decision.suppress ? decision.context : `${decision.context}\n\n${event.text}` }
     return { action: 'continue' }
   })
 
@@ -609,13 +623,19 @@ export default function hooksExtension(pi: ExtensionAPI) {
 
   pi.on('session_before_compact', async (event, ctx) => {
     const trigger = claudeSpelling(PRECOMPACT_TRIGGER, event.reason)
-    const results = await runNotifyHooks(matchingCommands(config.PreCompact, trigger.names), { hook_event_name: 'PreCompact', trigger: trigger.value }, boundRunner(ctx))
+    // Claude's custom_instructions: the /compact arguments on a manual run, empty
+    // on an automatic one; pi carries them on the event directly.
+    const payload = { hook_event_name: 'PreCompact', trigger: trigger.value, custom_instructions: event.customInstructions ?? '' }
+    const results = await runNotifyHooks(matchingCommands(config.PreCompact, trigger.names), payload, boundRunner(ctx))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
   })
 
   pi.on('session_compact', async (event, ctx) => {
     const trigger = claudeSpelling(PRECOMPACT_TRIGGER, event.reason)
-    const results = await runNotifyHooks(matchingCommands(config.PostCompact, trigger.names), { hook_event_name: 'PostCompact', trigger: trigger.value }, boundRunner(ctx))
+    // Claude's compact_summary: the summary that replaced the compacted history.
+    const summary = (event as { compactionEntry?: { summary?: unknown } }).compactionEntry?.summary
+    const payload = { hook_event_name: 'PostCompact', trigger: trigger.value, ...(typeof summary === 'string' ? { compact_summary: summary } : {}) }
+    const results = await runNotifyHooks(matchingCommands(config.PostCompact, trigger.names), payload, boundRunner(ctx))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
     // Claude also fires SessionStart with source "compact" when the session
     // continues after compaction; its stdout context rides the next agent start,

package/extensions/internal/subagent-events.ts

@@ -10,6 +10,9 @@ export interface SubagentPhaseEvent {
   phase: 'start' | 'stop'
   agentType: string
   agentId: string
+  /** The run's final assistant text, on stop: Claude's SubagentStop delivers it
+   * as last_assistant_message so hooks need not parse a transcript. */
+  lastAssistantMessage?: string
 }
 
 export function isSubagentPhaseEvent(data: unknown): data is SubagentPhaseEvent {

package/extensions/subagent/background.ts

@@ -22,6 +22,8 @@ export interface BackgroundRun {
   turns: number
   /** Last stderr bytes of a failed child; the only diagnostics a boot failure leaves. */
   stderr?: string
+  /** Claude's partial marker: the run stopped at its maxTurns limit. */
+  partial?: boolean
   /** Set while running so the run can be cancelled; cleared on completion. */
   kill?: () => void
   /** True until the child process actually closes: a cancelled child that ignores
@@ -41,7 +43,7 @@ export interface BackgroundSpawn {
   command: string
   args: string[]
   cwd: string
-  /** The --append-system-prompt body, kept so a resume can rebuild the file the
+  /** The --system-prompt body, kept so a resume can rebuild the file the
    * completing run deleted. Without it the resumed child is handed a path that no
    * longer exists, and pi falls back to using that path as the prompt text. */
   promptBody?: string
@@ -191,9 +193,9 @@ export function resumeBackgroundRun(id: string, task: string, onComplete: (run:
   return 'resumed'
 }
 
-/** Re-point --append-system-prompt at a fresh file when the original is gone. */
+/** Re-point --system-prompt at a fresh file when the original is gone. */
 function withRebuiltPrompt(spawnSpec: BackgroundSpawn): string[] {
-  const flag = spawnSpec.args.indexOf('--append-system-prompt')
+  const flag = spawnSpec.args.indexOf('--system-prompt')
   if (flag === -1 || !spawnSpec.promptBody) return spawnSpec.args
   const current = spawnSpec.args[flag + 1]
   if (current && fs.existsSync(current)) return spawnSpec.args
@@ -314,6 +316,8 @@ function driveRun(run: BackgroundRun, invocation: BackgroundSpawn, onComplete: (
     // maxTurns cap ends cleanly with output preserved, so it counts as done, not failed.
     if (run.state !== 'cancelled') run.state = code === 0 || cappedByMaxTurns ? 'done' : 'failed'
     run.exitCode = cappedByMaxTurns ? 0 : (code ?? 0)
+    // Claude marks a maxTurns-capped run's output as partial and offers a resume.
+    if (cappedByMaxTurns) run.partial = true
     run.output = text
     run.turns = turns
     run.stderr = stderrTail.trim() || undefined

package/extensions/subagent/index.ts

@@ -67,6 +67,8 @@ interface SingleResult {
   stopReason?: string
   errorMessage?: string
   step?: number
+  /** Claude's partial marker: the run stopped at its maxTurns limit. */
+  partial?: boolean
 }
 
 interface SubagentDetails {
@@ -157,13 +159,14 @@ interface RunAgentOptions {
   projectApproved?: boolean
 }
 
-/** Publishes a child run's start/stop for the hooks extension's SubagentStart/Stop. */
-type SubagentPhaseSink = (phase: 'start' | 'stop', agentType: string, agentId: string) => void
+/** Publishes a child run's start/stop for the hooks extension's SubagentStart/Stop.
+ * The stop carries the run's final assistant text, which Claude's SubagentStop
+ * delivers as last_assistant_message. */
+type SubagentPhaseSink = (phase: 'start' | 'stop', agentType: string, agentId: string, lastAssistantMessage?: string) => void
 
-/** Tell the parent where a kept worktree lives: appended to the final assistant
- * message so it rides the run's normal output; stderr when there is none. */
-function appendWorktreeNote(result: SingleResult, worktree: AgentWorktree): void {
-  const note = `[isolation: worktree kept at ${worktree.dir} (branch ${worktree.branch}); the agent's changes live there]`
+/** Append a note to the final assistant message so it rides the run's normal
+ * output; stderr when there is none. */
+function appendResultNote(result: SingleResult, note: string): void {
   for (let i = result.messages.length - 1; i >= 0; i--) {
     const msg = result.messages[i]
     if (msg.role === 'assistant') {
@@ -174,15 +177,44 @@ function appendWorktreeNote(result: SingleResult, worktree: AgentWorktree): void
   result.stderr = result.stderr ? `${result.stderr}\n${note}` : note
 }
 
+/** Tell the parent where a kept worktree lives. */
+function appendWorktreeNote(result: SingleResult, worktree: AgentWorktree): void {
+  appendResultNote(result, `[isolation: worktree kept at ${worktree.dir} (branch ${worktree.branch}); the agent's changes live there]`)
+}
+
+/** Claude marks a maxTurns-capped run's output as partial; the note rides the
+ * final assistant message like the worktree note, so the parent model sees it
+ * with the output. A no-op for uncapped runs. */
+function appendPartialNote(result: SingleResult): void {
+  if (result.partial) appendResultNote(result, '[Output is partial: the subagent stopped at its maxTurns limit.]')
+}
+
 async function runSingleAgent(options: RunAgentOptions): Promise<SingleResult> {
   const agent = options.agents.find((a) => a.name === options.agentName)
   if (!agent) return runSingleAgentInner(options)
+  // A refused launch (Claude's zero-tools error) never starts, so no
+  // SubagentStart/Stop pair fires for it.
+  const toolsError = unresolvedToolsError(agent)
+  if (toolsError) {
+    return {
+      agent: agent.name,
+      agentSource: agent.source,
+      task: options.task,
+      exitCode: 1,
+      messages: [],
+      stderr: toolsError,
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+      step: options.step,
+    }
+  }
   const agentId = `fg-${randomUUID().slice(0, 8)}`
   options.onPhase?.('start', agent.name, agentId)
+  let result: SingleResult | undefined
   try {
-    return await runSingleAgentInner(options)
+    result = await runSingleAgentInner(options)
+    return result
   } finally {
-    options.onPhase?.('stop', agent.name, agentId)
+    options.onPhase?.('stop', agent.name, agentId, result ? getFinalOutput(result.messages) || undefined : undefined)
   }
 }
 
@@ -265,7 +297,9 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
       const tmp = await writePromptToTempFile(agent.name, promptBody)
       tmpPromptDir = tmp.dir
       tmpPromptPath = tmp.filePath
-      args.push('--append-system-prompt', tmpPromptPath)
+      // Claude: the agent body IS the subagent's system prompt, replacing the
+      // default, not an addition to it (--system-prompt reads a file path too).
+      args.push('--system-prompt', tmpPromptPath)
     }
 
     args.push(`Task: ${task}`)
@@ -304,8 +338,12 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
             accumulateAssistantMessage(currentResult, msg)
             assistantTurns++
             // Claude's maxTurns cap: end the child at the turn boundary once it has
-            // produced its Nth turn, so the collected output is kept and no turn is cut.
-            if (agent.maxTurns && assistantTurns >= agent.maxTurns) killGroup('SIGTERM')
+            // produced its Nth turn, so the collected output is kept and no turn is
+            // cut; the returned output is marked partial, as Claude documents.
+            if (agent.maxTurns && assistantTurns >= agent.maxTurns) {
+              currentResult.partial = true
+              killGroup('SIGTERM')
+            }
           }
           emitUpdate()
         } else if (event.type === 'tool_result_end') {
@@ -371,6 +409,7 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
 
     currentResult.exitCode = exitCode
     if (wasAborted) throw new Error('Subagent was aborted')
+    appendPartialNote(currentResult)
     return currentResult
   } finally {
     // Cleanup runs on abort too: it only removes a pristine worktree, so an
@@ -452,12 +491,15 @@ 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; stderr?: string }): string {
+export function backgroundCompletionText(run: { id: string; agent: string; state: string; turns: number; output?: string; stderr?: string; partial?: boolean }): string {
   const output = capForContext(run.output ?? '') || '(no output)'
   // A child that dies at boot writes its reason only to stderr; without this the
   // notice reads "failed after 0 turns ... (no output)" with nothing to act on.
   const diagnostics = run.state === 'failed' && run.stderr ? `\n\nstderr tail:\n${capForContext(run.stderr)}` : ''
-  return `Background subagent run ${run.id} (${run.agent}) ${run.state} after ${run.turns} turns.\n\n${output}${diagnostics}`
+  // Claude marks maxTurns-capped output as partial and notes the run can be
+  // resumed to continue from where it stopped.
+  const partialNote = run.partial ? `\n\n[Output is partial: the run stopped at its maxTurns limit. Resume it with {resume: "${run.id}", task: "..."} to continue.]` : ''
+  return `Background subagent run ${run.id} (${run.agent}) ${run.state} after ${run.turns} turns.\n\n${output}${diagnostics}${partialNote}`
 }
 
 /** What to tell the model about a resume request. */
@@ -690,13 +732,31 @@ export function setKnownMcpAliases(aliases: ReadonlyArray<{ pi: string; claude:
   knownMcpAliases = aliases
 }
 
+/** pi's built-in ToolName union (core/tools/index.d.ts; the package's export map
+ * does not expose allToolNames, so this mirrors it) plus the tools pi-code's own
+ * extensions register in a child. Claude's capitalized spellings fold onto these. */
+const CHILD_TOOL_NAMES = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls', 'web_fetch', 'web_search', 'list_mcp_resources', 'read_mcp_resource'])
+
+/** Claude: when no entry in a `tools` list resolves to a tool, the subagent fails
+ * to launch with an error naming the entries, instead of running tool-less. */
+function unresolvedToolsError(agent: AgentConfig): string | undefined {
+  if (!agent.tools || agent.tools.length === 0) return undefined
+  const fold = (name: string): string => name.toLowerCase().replaceAll('-', '_')
+  const known = new Set(knownMcpAliases.map((alias) => fold(alias.pi)))
+  const resolves = expandMcpToolPatterns(agent.tools, knownMcpAliases).some((entry) => CHILD_TOOL_NAMES.has(fold(entry)) || known.has(fold(entry)))
+  if (resolves) return undefined
+  return `Agent "${agent.name}" would launch with zero tools: no entry in [${agent.tools.join(', ')}] resolves to a tool.`
+}
+
 /** CLI args shared by foreground and background children, from the agent's config. */
 function agentInvocationArgs(agent: AgentConfig, aliasModel?: string): string[] {
   const args: string[] = ['--mode', 'json', '-p', '--no-session']
   // 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
+  // this user can actually run; then CLAUDE_CODE_SUBAGENT_MODEL, per Claude's model
+  // order (invocation model, frontmatter model, this variable, the session model).
+  // 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 ?? process.env.CLAUDE_CODE_SUBAGENT_MODEL
   if (model) args.push('--model', agent.effort ? `${model}:${agent.effort}` : model)
   else if (agent.effort) args.push('--thinking', agent.effort)
   // Claude's mcp__<server> / mcp__* patterns expand against the parent's MCP roster;
@@ -758,6 +818,13 @@ async function runBackgroundMode(params: SubagentParamsStatic, context: Backgrou
       details: makeDetails('single')([]),
     }
   }
+  const toolsError = unresolvedToolsError(agent)
+  if (toolsError) {
+    return {
+      content: [{ type: 'text', text: toolsError }],
+      details: makeDetails('single')([]),
+    }
+  }
   if (activeBackgroundRuns() >= MAX_BACKGROUND_RUNS) {
     return backgroundCapResult(makeDetails)
   }
@@ -782,7 +849,9 @@ async function runBackgroundMode(params: SubagentParamsStatic, context: Backgrou
   const promptBody = childPromptBody(agent, skillRoots, memorySection)
   if (promptBody.trim()) {
     tmpPrompt = await writePromptToTempFile(agent.name, promptBody)
-    args.push('--append-system-prompt', tmpPrompt.filePath)
+    // Claude: the agent body replaces the default system prompt (see the
+    // foreground path).
+    args.push('--system-prompt', tmpPrompt.filePath)
   }
   args.push(`Task: ${task}`)
   const invocation = getPiInvocation(args)
@@ -793,7 +862,7 @@ async function runBackgroundMode(params: SubagentParamsStatic, context: Backgrou
       // catch covers the synchronous path, but the worktree branch reaches here from an
       // async continuation outside it, so the guard must live in finish itself.
       try {
-        pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id })
+        pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id, ...(run.output?.trim() ? { lastAssistantMessage: run.output.trim() } : {}) })
         pi.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
       } catch {
         // Session disposed after the run outlived it; nothing to notify.
@@ -1486,7 +1555,17 @@ export default function subagentExtension(pi: ExtensionAPI) {
 
       if (params.background) return runBackgroundMode(params, { agents, defaultCwd: ctx.cwd, pi, makeDetails, skillRoots, availableModels, projectApproved }, (id) => rememberBackgroundRun(id))
 
-      const mode: ModeContext = { agents, defaultCwd: ctx.cwd, signal, onUpdate, makeDetails, skillRoots, availableModels, projectApproved, onPhase: (phase, agentType, agentId) => pi.events.emit(SUBAGENT_CHANNEL, { phase, agentType, agentId }) }
+      const mode: ModeContext = {
+        agents,
+        defaultCwd: ctx.cwd,
+        signal,
+        onUpdate,
+        makeDetails,
+        skillRoots,
+        availableModels,
+        projectApproved,
+        onPhase: (phase, agentType, agentId, lastAssistantMessage) => pi.events.emit(SUBAGENT_CHANNEL, { phase, agentType, agentId, ...(lastAssistantMessage === undefined ? {} : { lastAssistantMessage }) }),
+      }
 
       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": "1.0.30",
+  "version": "1.0.32",
   "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",