pi-code 1.0.31 → 1.0.33

package/extensions/hooks/config.ts

@@ -115,6 +115,25 @@ export function mergeSkillHooks(config: HooksConfig, skillName: string, hooks: u
   mergeHooksJson(config, JSON.stringify({ hooks }), `${skillName} (skill)`, sources, `skill:${skillName}`)
 }
 
+/** Claude's agent-frontmatter hooks, inside the subagent child: the parent passes
+ * them via PI_CODE_AGENT_HOOKS (Stop already converted to SubagentStop), and they
+ * run only while this child runs because they die with the process. Returns the
+ * agent identity for the child's SubagentStop firing, or undefined outside a
+ * subagent or with no hooks passed. */
+export function mergeAgentEnvHooks(config: HooksConfig, sources?: Map<HookMatcher, string>): { agent: string; id?: string } | undefined {
+  if (process.env.PI_CODE_SUBAGENT !== '1') return undefined
+  const raw = process.env.PI_CODE_AGENT_HOOKS
+  if (!raw) return undefined
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (!isRecord(parsed) || typeof parsed.agent !== 'string' || !isRecord(parsed.hooks)) return undefined
+    mergeHooksJson(config, JSON.stringify({ hooks: parsed.hooks }), `${parsed.agent} (agent)`, sources, `agent:${parsed.agent}`)
+    return { agent: parsed.agent, ...(typeof parsed.id === 'string' ? { id: parsed.id } : {}) }
+  } catch {
+    return undefined
+  }
+}
+
 /** Claude's `allowedHttpHookUrls` setting: URL patterns http hooks may target, with
  * `*` as a wildcard. Per Claude's documentation: undefined (no source sets the key)
  * means no restrictions, an empty array blocks every http hook, and arrays merge

package/extensions/hooks/index.ts

@@ -64,9 +64,13 @@
  * (asyncRewake keeps its own), and hooks still running at session end are killed,
  * as Claude does at teardown.
  *
- * SubagentStart/SubagentStop ride pi-code's own subagent extension, which publishes
- * child-run lifecycle on the shared bus (notify-style: a child has already exited by
- * the time SubagentStop fires, so its exit-2 block semantics cannot be honored).
+ * SubagentStart runs through the pre-spawn seam (internal/subagent-hooks) so its
+ * additionalContext reaches the child before its first prompt; it cannot block a
+ * spawn, as Claude documents. SubagentStop rides the subagent extension's bus stop
+ * event (notify-style: the child has already exited, so exit-2 block semantics
+ * cannot be honored) and carries last_assistant_message. Inside a subagent child,
+ * agent-frontmatter hooks arrive via PI_CODE_AGENT_HOOKS (Stop pre-converted to
+ * SubagentStop, fired at the child's own agent end) and die with the process.
  *
  * Hook commands run via `sh -c` with the event JSON on stdin. A PreToolUse
  * hook blocks the tool by exiting 2 (stderr becomes the reason) or by printing
@@ -99,8 +103,9 @@ import { isProjectApproved } from '../internal/project-approval.js'
 import { repoRoot } from '../internal/project-root.js'
 import { isSkillHooksEvent, SKILL_HOOKS_CHANNEL } from '../internal/skill-hooks.js'
 import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
+import { setSubagentStartHookRunner } from '../internal/subagent-hooks.js'
 import { claudeToolInput, claudeToolName, claudeToolResponse, piToolOutput } from './claude-tools.js'
-import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, isBackgroundHook, loadHooks, loadManagedHooks, loadPluginHooks, mergeSkillHooks, readAllowedHttpHookUrls, readDisableAllHooks, readSettingsDisableAllHooks } from './config.js'
+import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, isBackgroundHook, loadHooks, loadManagedHooks, loadPluginHooks, mergeAgentEnvHooks, mergeSkillHooks, readAllowedHttpHookUrls, readDisableAllHooks, readSettingsDisableAllHooks } from './config.js'
 import { blockedToolCall, jsonBlockVerdict, postToolFeedback, promptContext, runPreToolUse, runUserPromptSubmit, surfaceSystemMessages, tryParseJson } from './decisions.js'
 import { allCommands, matchingCommands, passesIfFilter } from './matcher.js'
 import { type HookRunner, type HookRunResult, runAgentHook, runHookCommand, runHttpHook, runMcpToolHook, runPromptHook, sessionEndTimeoutMs, timeoutMs } from './runners.js'
@@ -199,6 +204,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
     idlePromptTimer = undefined
   }
   let sessionCtx: ExtensionContext | undefined
+  /** Set inside a subagent child that carries agent-frontmatter hooks: the child's
+   * own agent end fires their SubagentStop, per Claude's Stop conversion. */
+  let agentIdentity: { agent: string; id?: string } | undefined
   /** Claude's disableAllHooks escape hatch was set somewhere in the honored chain. */
   let hooksDisabled = false
   /** Which settings file each resolved entry came from, for the /hooks viewer. */
@@ -337,12 +345,16 @@ export default function hooksExtension(pi: ExtensionAPI) {
   // Subagent lifecycle arrives over the bus without a pi context; the session context
   // captured at session_start supplies the common payload fields.
   pi.events.on(SUBAGENT_CHANNEL, async (data) => {
-    if (!isSubagentPhaseEvent(data) || !sessionCtx) return
+    // SubagentStart runs through the pre-spawn seam below (so its context can
+    // reach the child before its first prompt); the bus start event would
+    // double-run it, so only the stop phase is handled here.
+    if (!isSubagentPhaseEvent(data) || data.phase !== 'stop' || !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: 'SubagentStop', agent_type: data.agentType, agent_id: data.agentId, ...(data.lastAssistantMessage !== undefined ? { last_assistant_message: data.lastAssistantMessage } : {}) }
     try {
-      const results = await runNotifyHooks(matchingCommands(config[eventName], data.agentType), payload, boundRunner(ctx))
+      const results = await runNotifyHooks(matchingCommands(config.SubagentStop, data.agentType), payload, boundRunner(ctx))
       surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
     } catch {
       // The bus outlives the session: an event landing between /new disposing this
@@ -351,6 +363,19 @@ export default function hooksExtension(pi: ExtensionAPI) {
     }
   })
 
+  // Claude's SubagentStart hooks inject additionalContext into the subagent before
+  // its first prompt, so they must run before the spawn: the subagent extension
+  // calls this seam pre-spawn and prepends the returned context to the child's task.
+  setSubagentStartHookRunner(async (agentType, agentId) => {
+    if (!sessionCtx) return []
+    const ctx = sessionCtx
+    const commands = matchingCommands(config.SubagentStart, agentType)
+    if (commands.length === 0) return []
+    const results = await runNotifyHooks(commands, { hook_event_name: 'SubagentStart', agent_type: agentType, agent_id: agentId }, boundRunner(ctx))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    return results.map((result) => promptContext(result.stdout)).filter(Boolean)
+  })
+
   pi.on('session_start', async (event, ctx) => {
     sessionCtx = ctx
     // One extension instance serves every session. A mid-turn /new fires session_start on
@@ -387,6 +412,10 @@ export default function hooksExtension(pi: ExtensionAPI) {
     // Plugins are user-installed and enabled by user settings (see installedPlugins),
     // so a checked-out repo cannot toggle which code-bearing plugin hooks run.
     loadPluginHooks(config, installedPlugins(os.homedir()), hookSources)
+    // Inside a subagent child, the parent passes the agent's frontmatter hooks via
+    // env (Stop already converted to SubagentStop, per Claude); they run only for
+    // this child process.
+    agentIdentity = mergeAgentEnvHooks(config, hookSources)
     // "reload" re-fires in-process with the same conversation and would double-run hooks;
     // a fork is a genuine session begin, which Claude reports as source "fork".
     if (event.reason === 'reload') return
@@ -558,6 +587,18 @@ export default function hooksExtension(pi: ExtensionAPI) {
       idlePromptTimer.unref?.()
     }
 
+    // In a subagent child, the agent-frontmatter Stop hooks were converted to
+    // SubagentStop and fire here, at the child's own end, notify-style; before the
+    // Stop early-returns, which do not apply to them.
+    if (agentIdentity) {
+      const subStop = matchingCommands(config.SubagentStop, agentIdentity.agent)
+      if (subStop.length > 0) {
+        const subText = lastAssistantText((event as { messages?: Array<{ role: string; content: unknown }> }).messages ?? [])
+        const subPayload = { hook_event_name: 'SubagentStop', agent_type: agentIdentity.agent, ...(agentIdentity.id ? { agent_id: agentIdentity.id } : {}), stop_hook_active: false, ...(subText ? { last_assistant_message: subText } : {}) }
+        await runNotifyHooks(subStop, subPayload, boundRunner(ctx)).catch(() => {})
+      }
+    }
+
     // Stop has no matcher support (a stray matcher is ignored, as Claude documents)
     // and an `if`-carrying hook never runs on a non-tool event.
     const commands = allCommands(config.Stop).filter((command) => passesIfFilter(command, undefined))

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/internal/subagent-hooks.ts

@@ -0,0 +1,26 @@
+/**
+ * Pre-spawn seam for Claude's SubagentStart hooks. The hooks extension registers
+ * the runner; the subagent extension calls it before spawning a child, so the
+ * hooks' additionalContext can be injected before the child's first prompt,
+ * which the after-the-fact bus event structurally cannot do. Same module-seam
+ * pattern as mcp-call.
+ */
+
+export type SubagentStartHookRunner = (agentType: string, agentId: string) => Promise<string[]>
+
+let runner: SubagentStartHookRunner | undefined
+
+export function setSubagentStartHookRunner(fn: SubagentStartHookRunner | undefined): void {
+  runner = fn
+}
+
+/** Context strings SubagentStart hooks contribute; empty when no runner is
+ * registered or the runner fails (hooks must never block a spawn). */
+export async function runSubagentStartHooks(agentType: string, agentId: string): Promise<string[]> {
+  if (!runner) return []
+  try {
+    return await runner(agentType, agentId)
+  } catch {
+    return []
+  }
+}

package/extensions/subagent/agents.ts

@@ -157,8 +157,23 @@ function readSkillBody(name: string, skillDirs: string[]): string | undefined {
  * the intent into a read-only toolset unless the file pins tools itself. */
 const READ_ONLY_TOOLS = ['read', 'grep', 'find', 'ls']
 
+/** The agent's name per Claude's naming rules: a plugin agent registers under the
+ * scoped id `<plugin>:<name>` with the filename standing in for a missing name;
+ * elsewhere the frontmatter name is required and `:` is reserved for plugin ids,
+ * so a file carrying one is not loaded. */
+function agentName(frontmatter: Record<string, unknown>, filePath: string, pluginName?: string): string | null {
+  const declared = typeof frontmatter.name === 'string' ? frontmatter.name.trim() : ''
+  if (pluginName !== undefined) return `${pluginName}:${declared || path.basename(filePath, '.md')}`
+  if (!declared) return null
+  if (declared.includes(':')) {
+    console.warn(`pi-code-subagent: ignoring agent ${filePath}: names cannot contain ":", which is reserved for plugin-scoped identifiers`)
+    return null
+  }
+  return declared
+}
+
 /** Parse one agent markdown file; null when it is not a usable agent definition. */
-function parseAgentFile(content: string, source: AgentSource, filePath: string): AgentConfig | null {
+function parseAgentFile(content: string, source: AgentSource, filePath: string, pluginName?: string): AgentConfig | null {
   let parsed: { frontmatter: Record<string, unknown>; body: string }
   try {
     parsed = parseFrontmatter<Record<string, unknown>>(content)
@@ -166,7 +181,7 @@ function parseAgentFile(content: string, source: AgentSource, filePath: string):
     return null // malformed YAML must not abort discovery for the whole directory
   }
   const { frontmatter, body } = parsed
-  const name = typeof frontmatter.name === 'string' ? frontmatter.name : ''
+  const name = agentName(frontmatter, filePath, pluginName)
   const description = typeof frontmatter.description === 'string' ? frontmatter.description : ''
   if (!name || !description) return null
   const tools = parseToolsField(frontmatter.tools, true)
@@ -198,6 +213,8 @@ function parseAgentFile(content: string, source: AgentSource, filePath: string):
     memory: parseMemoryField(frontmatter.memory),
     maxTurns: parseMaxTurns(frontmatter.maxTurns),
     isolation,
+    hooks: frontmatter.hooks !== null && typeof frontmatter.hooks === 'object' && !Array.isArray(frontmatter.hooks) ? (frontmatter.hooks as Record<string, unknown>) : undefined,
+    background: frontmatter.background === true ? true : undefined,
     systemPrompt: body,
     source,
     filePath,
@@ -262,6 +279,12 @@ export interface AgentConfig {
   maxTurns?: number
   /** Claude's `isolation: worktree`: run the child in a temporary git worktree. */
   isolation?: 'worktree'
+  /** Claude's frontmatter `hooks`, scoped to this subagent: passed to the child
+   * via env, with Stop converted to SubagentStop (see agentHooksEnv). */
+  hooks?: Record<string, unknown>
+  /** Claude's `background: true`: keep this agent in the background even when
+   * asked to run it in the foreground. */
+  background?: boolean
   systemPrompt: string
   source: AgentSource
   filePath: string
@@ -274,7 +297,7 @@ export interface AgentDiscoveryResult {
 
 /** Claude scans .claude/agents recursively so agents can be organized into
  * subfolders (agents/review/, agents/research/); the walk mirrors that. */
-function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
+function loadAgentsFromDir(dir: string, source: AgentSource, pluginName?: string): AgentConfig[] {
   const agents: AgentConfig[] = []
 
   let entries: fs.Dirent[]
@@ -287,7 +310,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
   for (const entry of entries) {
     const filePath = path.join(dir, entry.name)
     if (entry.isDirectory()) {
-      agents.push(...loadAgentsFromDir(filePath, source))
+      agents.push(...loadAgentsFromDir(filePath, source, pluginName))
       continue
     }
     if (!entry.name.endsWith('.md')) continue
@@ -300,7 +323,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
       continue
     }
 
-    const agent = parseAgentFile(content, source, filePath)
+    const agent = parseAgentFile(content, source, filePath, pluginName)
     if (agent) agents.push(agent)
   }
 
@@ -323,13 +346,14 @@ export type AgentSource = 'user' | 'project' | 'builtin' | 'plugin'
 /** Bundled default agents (Explore, Plan, general-purpose), lowest precedence. */
 const BUILTIN_AGENTS_DIR = path.join(import.meta.dirname, 'agents')
 
-/** Agent directories of every enabled plugin: `agents/` unless the manifest
+/** Agent directories of every enabled plugin, each with its plugin name (Claude
+ * scopes plugin agent ids as `<plugin>:<name>`): `agents/` unless the manifest
  * points elsewhere. Plugins are user-installed, so user scope only decides. */
-function pluginAgentDirs(home: string): string[] {
+function pluginAgentDirs(home: string): Array<{ dir: string; pluginName: string }> {
   return installedPlugins(home).flatMap((plugin) => {
     const declared = plugin.manifest.agents
     const dirs = Array.isArray(declared) ? declared : [typeof declared === 'string' ? declared : 'agents']
-    return dirs.map((dir) => path.resolve(plugin.root, String(dir)))
+    return dirs.map((dir) => ({ dir: path.resolve(plugin.root, String(dir)), pluginName: plugin.name }))
   })
 }
 
@@ -344,7 +368,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 
   // Plugins load after builtins and before the user's own dirs, so a user agent
   // wins a name clash with a plugin's, and ~/.pi/agent/agents wins over ~/.claude.
-  const userAgents = scope === 'project' ? [] : [...loadAgentsFromDir(BUILTIN_AGENTS_DIR, 'builtin'), ...pluginAgentDirs(os.homedir()).flatMap((dir) => loadAgentsFromDir(dir, 'plugin')), ...loadAgentsFromDir(claudeUserDir, 'user'), ...loadAgentsFromDir(userDir, 'user')]
+  const userAgents = scope === 'project' ? [] : [...loadAgentsFromDir(BUILTIN_AGENTS_DIR, 'builtin'), ...pluginAgentDirs(os.homedir()).flatMap((entry) => loadAgentsFromDir(entry.dir, 'plugin', entry.pluginName)), ...loadAgentsFromDir(claudeUserDir, 'user'), ...loadAgentsFromDir(userDir, 'user')]
   // project .claude/agents loads first so project .pi/agents wins on name conflicts
   const projectAgents = scope === 'user' ? [] : [...projectClaudeDirs.flatMap((dir) => loadAgentsFromDir(dir, 'project')), ...(projectPiDir ? loadAgentsFromDir(projectPiDir, 'project') : [])]
 

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,9 @@ export interface BackgroundSpawn {
   command: string
   args: string[]
   cwd: string
-  /** The --append-system-prompt body, kept so a resume can rebuild the file the
+  /** Extra child environment (agent-frontmatter hooks ride here). */
+  env?: Record<string, string>
+  /** 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 +195,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
@@ -211,12 +215,14 @@ function withRebuiltPrompt(spawnSpec: BackgroundSpawn): string[] {
   }
 }
 
-export function startBackgroundRun(agent: string, task: string, invocation: BackgroundSpawn, onComplete: (run: BackgroundRun) => void): string | null {
+export function startBackgroundRun(agent: string, task: string, invocation: BackgroundSpawn, onComplete: (run: BackgroundRun) => void, presetId?: string): 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)}`
+  // A preset id lets the caller run SubagentStart hooks pre-spawn with the same
+  // id the run will carry.
+  const id = presetId ?? `bg-${randomUUID().slice(0, 8)}`
   // 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)}`
@@ -238,7 +244,7 @@ function driveRun(run: BackgroundRun, invocation: BackgroundSpawn, onComplete: (
     // Its own group, so cancelling reaches any grandchild the agent spawned.
     detached: true,
     // The marker lets the child's subagent tool refuse to nest further.
-    env: { ...process.env, PI_CODE_SUBAGENT: '1' },
+    env: { ...process.env, PI_CODE_SUBAGENT: '1', ...invocation.env },
   })
   run.live = true
   const killGroup = (signal: NodeJS.Signals): void => {
@@ -314,6 +320,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

@@ -30,6 +30,7 @@ import { capForContext } from '../internal/output-guard.js'
 import { isProjectApproved, isProjectApprovedSilently } from '../internal/project-approval.js'
 import { repoRoot } from '../internal/project-root.js'
 import { SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
+import { runSubagentStartHooks } from '../internal/subagent-hooks.js'
 import { autoMemoryEnabled, capIndexForPrompt, INDEX_MAX_BYTES, INDEX_MAX_LINES, memorySettingsFiles, readMemorySettings } from '../memory.js'
 import { skillDirs } from '../skills.js'
 import { type AgentConfig, type AgentMemoryScope, type AgentScope, type AgentSource, discoverAgents, expandMcpToolPatterns, resolveModelAlias, withPreloadedSkills } from './agents.js'
@@ -67,6 +68,8 @@ interface SingleResult {
   stopReason?: string
   errorMessage?: string
   step?: number
+  /** Claude's partial marker: the run stopped at its maxTurns limit. */
+  partial?: boolean
 }
 
 interface SubagentDetails {
@@ -149,6 +152,10 @@ interface RunAgentOptions {
   onUpdate?: OnUpdateCallback
   makeDetails: (results: SingleResult[]) => SubagentDetails
   onPhase?: SubagentPhaseSink
+  /** The child's run id, set by the wrapper so the spawn env can carry it. */
+  agentId?: string
+  /** SubagentStart hook context, injected ahead of the child's first prompt. */
+  startContexts?: string[]
   /** Skill directories to preload from, resolved where project trust is known. */
   skillRoots?: string[]
   /** Models this user can actually run, for resolving a tier alias. */
@@ -157,13 +164,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 +182,47 @@ 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)}`
+  // SubagentStart hooks run pre-spawn through the seam so their additionalContext
+  // reaches the child before its first prompt.
+  const startContexts = await runSubagentStartHooks(agent.name, agentId)
   options.onPhase?.('start', agent.name, agentId)
+  let result: SingleResult | undefined
   try {
-    return await runSingleAgentInner(options)
+    result = await runSingleAgentInner({ ...options, agentId, startContexts })
+    return result
   } finally {
-    options.onPhase?.('stop', agent.name, agentId)
+    options.onPhase?.('stop', agent.name, agentId, result ? getFinalOutput(result.messages) || undefined : undefined)
   }
 }
 
@@ -265,10 +305,12 @@ 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}`)
+    args.push(taskWithStartContext(task, options.startContexts ?? []))
     let wasAborted = false
 
     const exitCode = await new Promise<number>((resolve) => {
@@ -281,7 +323,7 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
         // direct child orphans a build or dev server the agent started.
         detached: true,
         // The marker lets the child's subagent tool refuse to nest further.
-        env: { ...process.env, PI_CODE_SUBAGENT: '1' },
+        env: { ...process.env, PI_CODE_SUBAGENT: '1', ...agentHooksEnv(agent, options.agentId ?? '') },
       })
       let buffer = ''
       let assistantTurns = 0
@@ -304,8 +346,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 +417,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 +499,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 +740,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;
@@ -704,9 +772,41 @@ function agentInvocationArgs(agent: AgentConfig, aliasModel?: string): string[]
   // grant granted nothing.
   if (agent.tools && agent.tools.length > 0) args.push('--tools', expandMcpToolPatterns(agent.tools, knownMcpAliases).join(','))
   if (agent.disallowedTools && agent.disallowedTools.length > 0) args.push('--exclude-tools', expandMcpToolPatterns(agent.disallowedTools, knownMcpAliases).join(','))
+  // Claude: "Explore and Plan are the only subagents that omit CLAUDE.md" (and no
+  // field or setting changes which agents skip them), to keep research fast.
+  if (agent.source === 'builtin' && (agent.name === 'Explore' || agent.name === 'Plan')) args.push('--no-context-files')
   return args
 }
 
+/** Claude's agent-frontmatter hooks ride to the child as env; the child's hooks
+ * extension merges them for the run only (they die with the process, matching
+ * "only while that subagent is running"). Stop converts to SubagentStop, the
+ * event the child fires when it completes, as Claude documents. */
+function agentHooksEnv(agent: AgentConfig, agentId: string): Record<string, string> {
+  if (!agent.hooks) return {}
+  const hooks: Record<string, unknown> = { ...agent.hooks }
+  const stop = hooks.Stop
+  delete hooks.Stop
+  if (Array.isArray(stop)) hooks.SubagentStop = [...(Array.isArray(hooks.SubagentStop) ? (hooks.SubagentStop as unknown[]) : []), ...stop]
+  return { PI_CODE_AGENT_HOOKS: JSON.stringify({ agent: agent.name, id: agentId, hooks }) }
+}
+
+/** Whether a run belongs in the background: the caller asked, or Claude's
+ * `background: true` frontmatter keeps the agent there even on a foreground ask
+ * (single mode). */
+function wantsBackground(params: { background?: boolean; agent?: string }, agents: AgentConfig[]): boolean {
+  if (params.background) return true
+  return params.agent !== undefined && agents.find((a) => a.name === params.agent)?.background === true
+}
+
+/** The task argument with any SubagentStart hook context ahead of it, per Claude:
+ * "added to the subagent's context at the start of its conversation, before its
+ * first prompt". */
+function taskWithStartContext(task: string, contexts: string[]): string {
+  const context = contexts.filter(Boolean).join('\n')
+  return context ? `${context}\n\nTask: ${task}` : `Task: ${task}`
+}
+
 function backgroundCapResult(makeDetails: MakeDetails): ToolResult {
   return {
     content: [{ type: 'text', text: `Too many background runs (max ${MAX_BACKGROUND_RUNS} running). Wait for one to finish; check progress with {status: true}.` }],
@@ -758,6 +858,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,37 +889,49 @@ 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}`)
+  // The id is preset so SubagentStart hooks run pre-spawn with the id the run
+  // will actually carry, and their context lands before the child's first prompt.
+  const presetId = `bg-${randomUUID().slice(0, 8)}`
+  const startContexts = await runSubagentStartHooks(agent.name, presetId)
+  args.push(taskWithStartContext(task, startContexts))
   const invocation = getPiInvocation(args)
-  const id = startBackgroundRun(agent.name, task, { command: invocation.command, args: invocation.args, cwd: worktree?.dir ?? runCwd, promptBody: tmpPrompt ? promptBody : undefined, maxTurns: agent.maxTurns }, (run) => {
-    removeTmpPrompt(tmpPrompt)
-    const finish = (): void => {
-      // Both calls throw once the session that started the run is disposed. driveRun's
-      // 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.sendMessage({ customType: 'subagent-background', content: backgroundCompletionText(run), display: true }, { triggerTurn: true })
-      } catch {
-        // Session disposed after the run outlived it; nothing to notify.
+  const id = startBackgroundRun(
+    agent.name,
+    task,
+    { command: invocation.command, args: invocation.args, cwd: worktree?.dir ?? runCwd, env: agentHooksEnv(agent, presetId), promptBody: tmpPrompt ? promptBody : undefined, maxTurns: agent.maxTurns },
+    (run) => {
+      removeTmpPrompt(tmpPrompt)
+      const finish = (): void => {
+        // Both calls throw once the session that started the run is disposed. driveRun's
+        // 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, ...(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.
+        }
       }
-    }
-    if (!worktree) {
-      finish()
-      return
-    }
-    // Cleanup only removes a pristine worktree; a kept one is reported in the
-    // completion text so the parent knows where the changes live.
-    const keptWorktree = worktree
-    void cleanupAgentWorktree(runCwd, keptWorktree)
-      .then((outcome) => {
-        if (outcome === 'kept') run.output = `${run.output ?? ''}\n[isolation: worktree kept at ${keptWorktree.dir} (branch ${keptWorktree.branch}); the agent's changes live there]`.trim()
-      })
-      .catch(() => {})
-      .finally(finish)
-  })
+      if (!worktree) {
+        finish()
+        return
+      }
+      // Cleanup only removes a pristine worktree; a kept one is reported in the
+      // completion text so the parent knows where the changes live.
+      const keptWorktree = worktree
+      void cleanupAgentWorktree(runCwd, keptWorktree)
+        .then((outcome) => {
+          if (outcome === 'kept') run.output = `${run.output ?? ''}\n[isolation: worktree kept at ${keptWorktree.dir} (branch ${keptWorktree.branch}); the agent's changes live there]`.trim()
+        })
+        .catch(() => {})
+        .finally(finish)
+    },
+    presetId,
+  )
   if (id === null) {
     // Lost the cap race to a parallel batch: the atomic check inside startBackgroundRun refused.
     removeTmpPrompt(tmpPrompt)
@@ -1484,9 +1603,19 @@ export default function subagentExtension(pi: ExtensionAPI) {
       // unavailable tier still falls back to the session model.
       const availableModels = ctx.modelRegistry?.getAvailable?.() ?? []
 
-      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 }) }
+      if (wantsBackground(params, agents)) 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, 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.31",
+  "version": "1.0.33",
   "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",