pi-code 1.0.32 → 1.0.34

package/extensions/context-imports.ts

@@ -81,6 +81,21 @@ import { fenceMarker, stripBlockComments } from './internal/strip-comments.js'
 
 /** Claude documents "a maximum depth of four hops" for recursive imports. */
 const MAX_IMPORT_DEPTH = 4
+
+/** Claude loads a context file (CLAUDE.md and friends) of up to 4 MiB in full and
+ * skips a larger one. */
+const CONTEXT_FILE_MAX_BYTES = 4 * 1024 * 1024
+
+/** One context file's content, or undefined when it is absent, unreadable, or over
+ * the 4 MiB limit Claude documents. */
+function readContextFile(filePath: string): string | undefined {
+  try {
+    if (fs.statSync(filePath).size > CONTEXT_FILE_MAX_BYTES) return undefined
+    return fs.readFileSync(filePath, 'utf-8')
+  } catch {
+    return undefined
+  }
+}
 export const MAX_IMPORT_FILES = 50
 export const MAX_IMPORT_BYTES = 256 * 1024
 
@@ -292,11 +307,8 @@ export function additionalDirContextFiles(dir: string, includeLocal: boolean): A
   if (includeLocal) candidates.push(path.join(dir, 'CLAUDE.local.md'))
   const files: Array<{ path: string; content: string }> = []
   for (const candidate of candidates) {
-    try {
-      files.push({ path: candidate, content: fs.readFileSync(candidate, 'utf-8') })
-    } catch {
-      // absent or unreadable: treat as not there
-    }
+    const content = readContextFile(candidate)
+    if (content !== undefined) files.push({ path: candidate, content })
   }
   return files
 }
@@ -717,12 +729,9 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
 
     // ~/.claude/CLAUDE.md, Claude's user-scope memory. The user's own file, so no
     // project approval is required; a missing file simply leaves it unset.
-    try {
-      const userClaudeMd = path.join(claudeConfigDir(os.homedir()), 'CLAUDE.md')
-      userContext = { path: userClaudeMd, content: fs.readFileSync(userClaudeMd, 'utf-8') }
-    } catch {
-      // no user CLAUDE.md
-    }
+    const userClaudeMd = path.join(claudeConfigDir(os.homedir()), 'CLAUDE.md')
+    const userContent = readContextFile(userClaudeMd)
+    if (userContent !== undefined) userContext = { path: userClaudeMd, content: userContent }
 
     // CLAUDE.local.md is Claude Code's personal sidecar of CLAUDE.md; pi's own loader
     // skips it. A cloned repo can ship one, so it is gated like other project config.
@@ -735,18 +744,12 @@ export default function contextImportsExtension(pi: ExtensionAPI) {
     const dotClaudeMd = findNearestFile(ctx.cwd, path.join('.claude', 'CLAUDE.md'))
     if ((candidates.length > 0 || dotClaudeMd !== null) && (await isProjectApproved(ctx))) {
       for (const candidate of candidates) {
-        try {
-          localContexts.push({ path: candidate, content: fs.readFileSync(candidate, 'utf-8') })
-        } catch {
-          // unreadable: treat as absent
-        }
+        const content = readContextFile(candidate)
+        if (content !== undefined) localContexts.push({ path: candidate, content })
       }
       if (dotClaudeMd !== null) {
-        try {
-          projectDotClaude = { path: dotClaudeMd, content: fs.readFileSync(dotClaudeMd, 'utf-8') }
-        } catch {
-          // unreadable: treat as absent
-        }
+        const content = readContextFile(dotClaudeMd)
+        if (content !== undefined) projectDotClaude = { path: dotClaudeMd, content }
       }
     }
     // Read after the local-context flow so an approval it just recorded is honored.

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/builtin-styles/concise.md

@@ -0,0 +1,13 @@
+---
+name: Concise
+description: Leads with the result and keeps responses short by default, without cutting the engineering work
+keep-coding-instructions: true
+---
+
+Lead with the result. Skip preamble, narration, and restating the request; answer first, support after.
+
+Keep responses short by default while doing the engineering work as thoroughly as ever: brevity applies to the writing, never to the analysis, testing, or care taken.
+
+When the user asks for an explanation or more detail, answer in full.
+
+Always keep the complete content of error reports, security warnings, and confirmations for destructive actions; never shorten those.

package/extensions/internal/path-rules.ts

@@ -198,9 +198,14 @@ export function globCompileStats(): { compiled: number; evaluated: number } {
 /** Rule `paths:` globs compiled once for repeated matching, with claude-rules'
  * pathMatchesGlobs semantics: `./` and leading `/` anchors are stripped, a trailing
  * slash scopes to the directory's contents, and blank entries drop out. */
+/** Claude's shared list budget: rule patterns past ~1000 compiled entries are
+ * ignored rather than compiled without bound. */
+const LIST_PATTERN_BUDGET = 1000
+
 export function compileGlobs(globs: string[]): CompiledGlob[] {
   const compiled: CompiledGlob[] = []
   for (const raw of globs) {
+    if (compiled.length >= LIST_PATTERN_BUDGET) break
     let glob = raw.trim()
     if (!glob) continue
     if (glob.startsWith('./')) glob = glob.slice(2)

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/memory.ts

@@ -15,6 +15,7 @@ import { StringEnum } from '@earendil-works/pi-ai'
 import { type ExtensionAPI, withFileMutationQueue } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
 import { claudeConfigDir } from './internal/config-dir.js'
+import { readManagedSettings } from './internal/managed-settings.js'
 import { capForContext } from './internal/output-guard.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { repoRoot } from './internal/project-root.js'
@@ -141,6 +142,18 @@ export function indexWouldOverflow(index: string, name: string, description: str
   return next.split('\n').length > INDEX_MAX_LINES || Buffer.byteLength(next, 'utf-8') > INDEX_MAX_BYTES
 }
 
+/** Where the index stands against the read limits, measured on the loaded content
+ * (frontmatter and comments stripped): 'over' past either bound, 'near' within
+ * 10% of one, else 'ok'. Claude reminds near a limit and errors over it. */
+export function indexReadState(index: string): 'ok' | 'near' | 'over' {
+  const loaded = stripNonLoaded(index)
+  const lines = loaded.split('\n').length
+  const bytes = Buffer.byteLength(loaded, 'utf-8')
+  if (lines > INDEX_MAX_LINES || bytes > INDEX_MAX_BYTES) return 'over'
+  if (lines > INDEX_MAX_LINES * 0.9 || bytes > INDEX_MAX_BYTES * 0.9) return 'near'
+  return 'ok'
+}
+
 type MemoryToolResult = { content: Array<{ type: 'text'; text: string }>; details: Record<string, never> }
 
 /** Write a memory and its index line, or say why it cannot be written. The whole
@@ -156,18 +169,29 @@ async function saveMemory(dir: string, indexPath: string, name: string | undefin
   }
   return withFileMutationQueue(indexPath, async (): Promise<MemoryToolResult> => {
     const index = readIndex(dir)
-    // Claude reports an explicit error rather than writing a memory the next session
-    // would never load, and says what to do about it.
-    if (indexWouldOverflow(index, name, description)) {
+    fs.mkdirSync(dir, { recursive: true })
+    // A memory with frontmatter records its write time; one without is left as-is.
+    fs.writeFileSync(path.join(dir, `${name}.md`), stampModified(content, now))
+    const nextIndex = upsertIndexLine(index, name, description)
+    writeIndex(indexPath, nextIndex)
+    // Claude measures the index after the write: over a read limit the write still
+    // succeeds, but an error tells Claude to rewrite the index (everything past
+    // the limit is dropped on the next load); near a limit, a reminder to shorten.
+    const state = indexReadState(nextIndex)
+    if (state === 'over') {
       return {
-        content: [{ type: 'text', text: `Memory index is full (${INDEX_MAX_LINES} entries or ${INDEX_MAX_BYTES} bytes). Delete or consolidate memories before saving ${name}.` }],
+        content: [
+          {
+            type: 'text',
+            text: `Saved memory ${name}, but the memory index is over its read limit (${INDEX_MAX_LINES} lines / ${INDEX_MAX_BYTES} bytes): rewrite MEMORY.md now. Keep one line per entry, move detail into topic files, and merge or drop stale entries; everything past the limit is dropped on the next load.`,
+          },
+        ],
         details: {},
       }
     }
-    fs.mkdirSync(dir, { recursive: true })
-    // A memory with frontmatter records its write time; one without is left as-is.
-    fs.writeFileSync(path.join(dir, `${name}.md`), stampModified(content, now))
-    writeIndex(indexPath, upsertIndexLine(index, name, description))
+    if (state === 'near') {
+      return { content: [{ type: 'text', text: `Saved memory ${name}. The memory index is near its read limit; shorten it: keep one line per entry, move detail into topic files, and merge or drop stale entries.` }], details: {} }
+    }
     return { content: [{ type: 'text', text: `Saved memory ${name}.` }], details: {} }
   })
 }
@@ -294,8 +318,9 @@ export function memorySettingsFiles(cwd: string, home: string, approved: boolean
   return claudeSettingsChain(cwd, home, approved)
 }
 
-/** Merge the two memory settings across the chain, later files winning per key. */
-export function readMemorySettings(files: string[]): { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } {
+/** Merge the two memory settings across the chain, later files winning per key;
+ * managed policy settings win over every file, per Claude's settings precedence. */
+export function readMemorySettings(files: string[], managed: Record<string, unknown> = readManagedSettings()): { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } {
   const merged: { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } = {}
   for (const file of files) {
     try {
@@ -307,6 +332,8 @@ export function readMemorySettings(files: string[]): { autoMemoryEnabled?: unkno
       // missing or invalid settings file: skip
     }
   }
+  if ('autoMemoryEnabled' in managed) merged.autoMemoryEnabled = managed.autoMemoryEnabled
+  if ('autoMemoryDirectory' in managed) merged.autoMemoryDirectory = managed.autoMemoryDirectory
   return merged
 }
 
@@ -405,7 +432,8 @@ export default function memoryExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: 'memory',
     label: 'Memory',
-    description: 'Persistent memory across sessions. Save durable facts, user preferences, corrections, and project decisions that are not derivable from the code. Actions: save (name + description + content), read (name), delete (name), list.',
+    description:
+      'Persistent memory across sessions. Save durable facts, user preferences, corrections, and project decisions that are not derivable from the code. Give each saved memory `type` frontmatter from the documented vocabulary: user (who the user is), feedback (guidance on how to work), project (ongoing work and constraints), or reference (pointers to external resources). Actions: save (name + description + content), read (name), delete (name), list.',
     parameters: MemoryParams,
     async execute(_id, params) {
       if (inSubagent()) {
@@ -492,6 +520,10 @@ export default function memoryExtension(pi: ExtensionAPI) {
         `  Index:       ${path.join(store, INDEX_FILE)}`,
         `  User memory (CLAUDE.md):    ${path.join(home, '.claude', 'CLAUDE.md')}`,
         `  Project memory (CLAUDE.md): ${path.join(ctx.cwd, 'CLAUDE.md')}`,
+        // Claude's /memory lists every documented location, including files that
+        // do not exist yet.
+        `  Project memory (CLAUDE.local.md): ${path.join(ctx.cwd, 'CLAUDE.local.md')}`,
+        `  Project memory (alternate):       ${path.join(ctx.cwd, '.claude', 'CLAUDE.md')}`,
         'Toggle with /memory on or /memory off.',
       ]
       ctx.ui.notify(lines.join('\n'), 'info')

package/extensions/output-styles.ts

@@ -25,6 +25,7 @@ import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
 import { claudeConfigDir } from './internal/config-dir.js'
+import { readManagedSettings } from './internal/managed-settings.js'
 import { installedPlugins } from './internal/plugins.js'
 import { isProjectApproved } from './internal/project-approval.js'
 import { ancestorDirs, findNearestDir, findNearestFile } from './internal/project-root.js'
@@ -35,6 +36,8 @@ export interface OutputStyle {
   description: string
   body: string
   keepCodingInstructions: boolean
+  /** Claude's `force-for-plugin`: a plugin style applying automatically. */
+  forceForPlugin: boolean
 }
 
 function field(frontmatter: string, key: string): string {
@@ -47,7 +50,20 @@ export function parseStyle(content: string, fallbackName: string): OutputStyle {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)
   const frontmatter = match ? match[1] : ''
   const body = match ? content.slice(match[0].length) : content
-  return { name: field(frontmatter, 'name') || fallbackName, description: field(frontmatter, 'description'), body: body.trim(), keepCodingInstructions: field(frontmatter, 'keep-coding-instructions') === 'true' }
+  return {
+    name: field(frontmatter, 'name') || fallbackName,
+    description: field(frontmatter, 'description'),
+    body: body.trim(),
+    keepCodingInstructions: field(frontmatter, 'keep-coding-instructions') === 'true',
+    forceForPlugin: field(frontmatter, 'force-for-plugin') === 'true',
+  }
+}
+
+/** Claude's `force-for-plugin` (plugin output styles only): the first loaded style
+ * carrying it applies automatically, overriding the outputStyle setting. The
+ * caller passes only plugin-loaded styles. */
+export function forcedPluginStyle(styles: OutputStyle[]): OutputStyle | undefined {
+  return styles.find((style) => style.forceForPlugin)
 }
 
 /** Equivalents of Claude's built-in styles, shipped with pi-code as the
@@ -137,8 +153,10 @@ export function settingsFiles(cwd: string, home: string, trusted: boolean): stri
   return claudeSettingsChain(cwd, home, trusted)
 }
 
-/** The `outputStyle` recorded in settings, last file winning. */
-export function readActiveStyleName(files: string[]): string | undefined {
+/** The `outputStyle` recorded in settings, last file winning; a managed policy
+ * value wins over every file, per Claude's settings precedence. */
+export function readActiveStyleName(files: string[], managed: Record<string, unknown> = readManagedSettings()): string | undefined {
+  if (typeof managed.outputStyle === 'string') return managed.outputStyle
   let name: string | undefined
   for (const file of files) {
     try {
@@ -186,7 +204,10 @@ export default function outputStylesExtension(pi: ExtensionAPI) {
     const nearestLocal = findNearestFile(ctx.cwd, path.join('.claude', 'settings.local.json'))
     const claudeDir = findNearestDir(ctx.cwd, '.claude') ?? path.join(ctx.cwd, '.claude')
     localSettingsPath = nearestLocal ?? path.join(claudeDir, 'settings.local.json')
-    activeName = readActiveStyleName(settingsFiles(ctx.cwd, home, trusted))
+    // Claude's force-for-plugin: the first loaded forced plugin style applies
+    // automatically, overriding the outputStyle setting.
+    const forced = forcedPluginStyle(loadStyles(pluginStyleDirs(home)))
+    activeName = forced?.name ?? readActiveStyleName(settingsFiles(ctx.cwd, home, trusted))
     const active = styleForName(styles, activeName)
     if (active) ctx.ui.notify(`Output style: ${active.name}`, 'info')
   })

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.34",
   "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",