pi-code 1.0.32 → 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,14 +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'
     // 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 } : {}) }
+    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
@@ -353,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
@@ -389,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
@@ -560,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-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

@@ -43,6 +43,8 @@ export interface BackgroundSpawn {
   command: string
   args: string[]
   cwd: string
+  /** 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. */
@@ -213,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)}`
@@ -240,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 => {

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'
@@ -151,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. */
@@ -208,10 +213,13 @@ async function runSingleAgent(options: RunAgentOptions): Promise<SingleResult> {
     }
   }
   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 {
-    result = await runSingleAgentInner(options)
+    result = await runSingleAgentInner({ ...options, agentId, startContexts })
     return result
   } finally {
     options.onPhase?.('stop', agent.name, agentId, result ? getFinalOutput(result.messages) || undefined : undefined)
@@ -302,7 +310,7 @@ async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResu
       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) => {
@@ -315,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
@@ -764,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}.` }],
@@ -853,35 +893,45 @@ async function runBackgroundMode(params: SubagentParamsStatic, context: Backgrou
     // 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, ...(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.
+  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)
@@ -1553,7 +1603,7 @@ 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))
+      if (wantsBackground(params, agents)) return runBackgroundMode(params, { agents, defaultCwd: ctx.cwd, pi, makeDetails, skillRoots, availableModels, projectApproved }, (id) => rememberBackgroundRun(id))
 
       const mode: ModeContext = {
         agents,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.32",
+  "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",