pi-code 0.5.0 → 0.7.0

package/README.md

@@ -38,19 +38,19 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 | Global + project rules | `~/.claude/rules`, `.claude/rules` (+ `paths:` frontmatter scoping) | `claude-rules.ts` |
 | Custom slash commands | `.claude/commands/*.md` → pi prompt templates | `commands.ts` |
 | Skills | `.claude/skills` → pi skill discovery (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.ts` |
-| Hooks | `.claude/settings.json` hooks: PreToolUse, PostToolUse, SessionStart, UserPromptSubmit (blocks and injects context), Stop, PreCompact, SessionEnd | `hooks.ts` |
-| Output styles | `.claude/output-styles` + active `outputStyle`, `/output-style` switcher | `output-styles.ts` |
+| Hooks | `.claude/settings.json` hooks: PreToolUse (blocks, rewrites input via `updatedInput`), PostToolUse (feedback and `additionalContext` land next to the tool result), PostToolUseFailure, SessionStart (context injection), UserPromptSubmit (blocks and injects context), Stop (a block continues the conversation), SubagentStart/SubagentStop, PreCompact, PostCompact, SessionEnd; Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort | `hooks.ts` |
+| Output styles | `.claude/output-styles` + active `outputStyle`; Claude replace semantics with `keep-coding-instructions`; bundled Explanatory/Learning/Proactive; `/output-style [name]` | `output-styles.ts` |
 | CLAUDE.md `@imports` | resolves `@path` imports pi's native loader skips; loads `CLAUDE.local.md` (approval-gated) | `context-imports.ts` |
-| MCP servers | user `~/.claude.json` (incl. per-project `projects[cwd]` local scope), `~/.pi/agent/mcp.json`; project `.mcp.json`, `.pi/mcp.json` (once approved); stdio/HTTP/SSE by `type`; `${VAR:-default}` expansion; `MCP_TIMEOUT`/`MCP_TOOL_TIMEOUT` | `mcp.ts` |
+| MCP servers | user `~/.claude.json` (incl. per-project `projects[cwd]` local scope), `~/.pi/agent/mcp.json`; project `.mcp.json`, `.pi/mcp.json` (once approved; `enabledMcpjsonServers`/`disabledMcpjsonServers`/`enableAllProjectMcpServers` honored, consent keys only from non-repo settings); stdio/HTTP/SSE by `type`; `${VAR:-default}` expansion; `MCP_TIMEOUT`/`MCP_TOOL_TIMEOUT` | `mcp.ts` |
 | Project trust | prompts before loading project config (MCP servers, hooks, agents, rules, output styles) that pi would otherwise trust silently | `internal/project-approval.ts` |
-| Subagents / Task | `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents`; background runs | `subagent/` |
+| Subagents / Task | builtin Explore/Plan/general-purpose agents, `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents`; agent roster with descriptions in the system prompt; background runs | `subagent/` |
 | Plan mode | `plan_mode_complete` tool, exact tool snapshot/restore | `plan-mode/` |
 | Todo list | persistent overlay, status machine, compaction-safe | `todo.ts` |
 | Checkpoints / rewind | shadow-repo snapshots; restore overwrites checkpointed files, keeps files created later | `git-checkpoint.ts` |
 | Persistent memory | per-project memories, index injected each session | `memory.ts` |
 | WebSearch / WebFetch | key-free DuckDuckGo search, SSRF-guarded fetch | `web.ts` |
 | AskUserQuestion | one question with `header`, single- or `multiSelect` options, plus free-text; no multi-question batching | `question.ts` |
-| Statusline | turn state + session cost | `status-line.ts` |
+| Statusline | Claude `statusLine` command contract (stdin JSON, `padding`, `refreshInterval`); built-in turn state + session cost fallback | `status-line.ts` |
 | Notifications | vendored example | `notify.ts` |
 
 `CLAUDE.md` itself needs no extension: pi loads `CLAUDE.md` / `AGENTS.md` context files natively (global + walking cwd to root). `context-imports.ts` only adds the `@import` resolution pi's loader lacks, appending the imported files without re-injecting the base.

package/extensions/hooks.ts

@@ -3,17 +3,30 @@
  *
  * Runs Claude Code's `.claude/settings.json` hooks on pi's lifecycle events, so
  * a project's existing hooks work under pi:
- * - PreToolUse      -> pi `tool_call` (can block the tool)
- * - PostToolUse     -> pi `tool_execution_end` (fire-and-forget)
- * - SessionStart    -> pi `session_start` (fire-and-forget)
+ * - PreToolUse      -> pi `tool_call` (can block the tool or rewrite its input)
+ * - PostToolUse     -> pi `tool_result` (block reasons and additionalContext are
+ *                      appended next to the tool result, as Claude documents)
+ * - SessionStart    -> pi `session_start` (stdout/additionalContext is injected as
+ *                      context before the first prompt via `before_agent_start`)
  * - UserPromptSubmit-> pi `input` (can block the prompt via `handled`, or inject
  *                      additional context by transforming the submitted text)
- * - Stop            -> pi `agent_end` (fire-and-forget; cannot prevent stopping)
+ * - Stop            -> pi `agent_end` (a block feeds its reason back as a new turn,
+ *                      with stop_hook_active as the loop guard)
  * - PreCompact      -> pi `session_before_compact` (fire-and-forget)
+ * - PostCompact     -> pi `session_compact` (fire-and-forget)
+ * - PostToolUseFailure -> pi `tool_result` error branch (fire-and-forget)
  * - SessionEnd      -> pi `session_shutdown` (fire-and-forget)
  *
- * Claude's SubagentStop has no pi lifecycle seam (the subagent tool spawns child pi
- * processes, and pi emits no subagent-completion event), so it is not bridged.
+ * Every payload carries session_id, transcript_path (pi's session file), cwd,
+ * permission_mode (plan-mode state off the shared bus) and effort; tool events add
+ * tool_use_id. Every event honors the universal `systemMessage` output (a
+ * user-facing warning).
+ * `suppressOutput` is accepted and inert: pi never echoes hook stdout to the
+ * transcript in the first place.
+ *
+ * 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).
  *
  * 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
@@ -35,10 +48,12 @@ import { type ChildProcess, spawn } from 'node:child_process'
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 
 import { isMcpToolAliases, MCP_TOOLS_CHANNEL } from './internal/mcp-alias.js'
+import { isPlanModeState, PLAN_MODE_CHANNEL } from './internal/plan-mode-state.js'
 import { isProjectApproved } from './internal/project-approval.js'
+import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from './internal/subagent-events.js'
 
 const DEFAULT_TIMEOUT_S = 60
 
@@ -144,7 +159,7 @@ export function matchingCommands(matchers: HookMatcher[] | undefined, names: str
   return result
 }
 
-function tryParseJson(text: string): { hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string; additionalContext?: string }; decision?: string; reason?: string; continue?: boolean; stopReason?: string } | undefined {
+function tryParseJson(text: string): { hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string; additionalContext?: string; updatedInput?: unknown }; decision?: string; reason?: string; continue?: boolean; stopReason?: string; systemMessage?: string } | undefined {
   try {
     return JSON.parse(text)
   } catch {
@@ -242,24 +257,50 @@ function timeoutMs(command: HookCommand): number {
   return seconds * 1000
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Claude's updatedInput replaces the whole tool_input, and pi's tool_call contract is
+ * in-place mutation, so the target object is emptied and refilled rather than reassigned. */
+function replaceRecord(target: Record<string, unknown>, next: Record<string, unknown>): void {
+  for (const key of Object.keys(target)) delete target[key]
+  Object.assign(target, next)
+}
+
 /** Run PreToolUse hooks for a tool; the first blocking verdict wins. For MCP tools the
  * matcher sees both the pi name and the Claude alias, and the payload reports the alias,
- * which is the name a Claude-written hook script expects in tool_name. */
-export async function runPreToolUse(config: HooksConfig, toolName: string, toolInput: unknown, runner: HookRunner, claudeName?: string): Promise<HookDecision> {
+ * which is the name a Claude-written hook script expects in tool_name. A hook's
+ * hookSpecificOutput.updatedInput replaces the tool input in place before the permission
+ * decision applies, and later hooks see the rewritten input in their payload. */
+export async function runPreToolUse(config: HooksConfig, toolName: string, toolInput: unknown, runner: HookRunner, claudeName?: string, onSystemMessage?: SystemMessageSink): Promise<HookDecision> {
   const names = claudeName ? [toolName, claudeName] : [toolName]
   for (const command of matchingCommands(config.PreToolUse, names)) {
     const result = await runner(command.command, { hook_event_name: 'PreToolUse', tool_name: claudeName ?? toolName, tool_input: toolInput }, timeoutMs(command))
     // A killed hook never reached its verdict, and SIGKILL leaves a null exit code that
     // would otherwise read as a clean allow. Fail closed instead.
     if (result.timedOut) return { block: true, reason: `Hook timed out after ${timeoutMs(command)}ms: ${command.command}` }
+    if (onSystemMessage) surfaceSystemMessages([result], onSystemMessage)
+    const updated = tryParseJson(result.stdout)?.hookSpecificOutput?.updatedInput
+    if (isRecord(updated) && isRecord(toolInput)) replaceRecord(toolInput, updated)
     const decision = interpretHookResult(result.code, result.stdout, result.stderr)
     if (decision.block) return decision
   }
   return { block: false }
 }
 
-async function runNotifyHooks(commands: HookCommand[], payload: unknown, runner: HookRunner): Promise<void> {
-  await Promise.all(commands.map((command) => runner(command.command, payload, timeoutMs(command))))
+async function runNotifyHooks(commands: HookCommand[], payload: unknown, runner: HookRunner): Promise<HookRunResult[]> {
+  return await Promise.all(commands.map((command) => runner(command.command, payload, timeoutMs(command))))
+}
+
+type SystemMessageSink = (message: string) => void
+
+/** Claude's universal systemMessage output field: a warning surfaced to the user. */
+function surfaceSystemMessages(results: HookRunResult[], notify: SystemMessageSink): void {
+  for (const result of results) {
+    const message = tryParseJson(result.stdout)?.systemMessage
+    if (message) notify(message)
+  }
 }
 
 export interface PromptDecision {
@@ -278,11 +319,12 @@ function promptContext(stdout: string): string {
 
 /** Run UserPromptSubmit hooks: the first blocking verdict wins; otherwise their
  * additional context is concatenated for injection ahead of the prompt. */
-export async function runUserPromptSubmit(config: HooksConfig, prompt: string, runner: HookRunner): Promise<PromptDecision> {
+export async function runUserPromptSubmit(config: HooksConfig, prompt: string, runner: HookRunner, onSystemMessage?: SystemMessageSink): Promise<PromptDecision> {
   const contexts: string[] = []
   for (const command of matchingCommands(config.UserPromptSubmit, 'UserPromptSubmit')) {
     const result = await runner(command.command, { hook_event_name: 'UserPromptSubmit', prompt }, timeoutMs(command))
     if (result.timedOut) return { block: true, reason: `Hook timed out after ${timeoutMs(command)}ms: ${command.command}`, context: '' }
+    if (onSystemMessage) surfaceSystemMessages([result], onSystemMessage)
     const decision = interpretHookResult(result.code, result.stdout, result.stderr)
     if (decision.block) return { block: true, reason: decision.reason, context: '' }
     const context = promptContext(result.stdout)
@@ -291,9 +333,6 @@ export async function runUserPromptSubmit(config: HooksConfig, prompt: string, r
   return { block: false, context: contexts.join('\n') }
 }
 
-/** Bound on remembered tool inputs, in case a blocked or aborted call never ends. */
-const MAX_PENDING_INPUTS = 100
-
 /** pi's lifecycle vocabularies differ from Claude's documented ones. The matcher is
  * offered both spellings so existing configs keep firing either way, and the payload
  * reports the Claude value, which is what a Claude-written hook script parses. */
@@ -310,10 +349,22 @@ function claudeSpelling(map: Record<string, string>, raw: string): { names: stri
 export default function hooksExtension(pi: ExtensionAPI) {
   let config: HooksConfig = {}
   let projectDir = ''
-  // tool_execution_end does not carry the tool's input, but Claude's PostToolUse
-  // contract does, so remember it from tool_call keyed by the call id.
-  const pendingInputs = new Map<string, unknown>()
-  const runner: HookRunner = (command, payload, ms) => runHookCommand(command, payload, ms, projectDir)
+  let pendingSessionContext: string[] = []
+  let stopHookActive = false
+  let sessionCtx: ExtensionContext | undefined
+  /** Claude sends session_id, transcript_path, cwd and effort on every payload. */
+  const commonPayload = (ctx: ExtensionContext): Record<string, unknown> => {
+    const common: Record<string, unknown> = { session_id: ctx.sessionManager.getSessionId(), cwd: ctx.cwd, permission_mode: permissionMode }
+    const transcript = ctx.sessionManager.getSessionFile()
+    if (transcript) common.transcript_path = transcript
+    if (ctx.thinkingLevel) common.effort = { level: ctx.thinkingLevel }
+    return common
+  }
+  /** A runner bound to the firing context, filling the common fields into each stdin. */
+  const boundRunner =
+    (ctx: ExtensionContext, extra?: Record<string, unknown>): HookRunner =>
+    (command, payload, ms) =>
+      runHookCommand(command, { ...commonPayload(ctx), ...extra, ...(payload as Record<string, unknown>) }, ms, projectDir)
   // Claude matchers name MCP tools mcp__<server>__<tool>; pi-code registers them as
   // <server>_<tool>. The mcp extension publishes the mapping on pi's shared bus.
   const mcpAliases = new Map<string, string>()
@@ -322,8 +373,25 @@ export default function hooksExtension(pi: ExtensionAPI) {
     mcpAliases.clear()
     for (const entry of data) mcpAliases.set(entry.pi, entry.claude)
   })
+  // Claude's permission_mode: pi has no permission system, but pi-code's plan mode is
+  // the documented "plan" mode; its extension publishes the state on the shared bus.
+  let permissionMode = 'default'
+  pi.events.on(PLAN_MODE_CHANNEL, (data) => {
+    if (isPlanModeState(data)) permissionMode = data.active ? 'plan' : 'default'
+  })
+  // 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
+    const ctx = sessionCtx
+    const eventName = data.phase === 'start' ? 'SubagentStart' : 'SubagentStop'
+    const payload = { hook_event_name: eventName, agent_type: data.agentType, agent_id: data.agentId }
+    const results = await runNotifyHooks(matchingCommands(config[eventName], data.agentType), payload, boundRunner(ctx))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+  })
 
   pi.on('session_start', async (event, ctx) => {
+    sessionCtx = ctx
     const trusted = await isProjectApproved(ctx)
     projectDir = ctx.cwd
     config = loadHooks(hookFiles(ctx.cwd, os.homedir(), trusted))
@@ -331,37 +399,77 @@ export default function hooksExtension(pi: ExtensionAPI) {
     // a fork is a genuine session begin, which Claude reports as source "fork".
     if (event.reason === 'reload') return
     const source = claudeSpelling(SESSION_START_SOURCE, event.reason)
-    await runNotifyHooks(matchingCommands(config.SessionStart, source.names), { hook_event_name: 'SessionStart', source: source.value }, runner)
+    const commands = matchingCommands(config.SessionStart, source.names)
+    const payload = { hook_event_name: 'SessionStart', source: source.value }
+    const run = boundRunner(ctx)
+    const results = await Promise.all(commands.map((command) => run(command.command, payload, timeoutMs(command))))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    pendingSessionContext = results.map((result) => promptContext(result.stdout)).filter(Boolean)
   })
 
-  pi.on('tool_call', async (event) => {
-    pendingInputs.set(event.toolCallId, event.input)
-    if (pendingInputs.size > MAX_PENDING_INPUTS) {
-      const oldest = pendingInputs.keys().next().value
-      if (oldest !== undefined) pendingInputs.delete(oldest)
-    }
-    const decision = await runPreToolUse(config, event.toolName, event.input, runner, mcpAliases.get(event.toolName))
+  // Claude adds a SessionStart hook's additionalContext (or plain stdout) to the
+  // conversation before the first prompt; pi's seam for that is a message injected
+  // on the next agent start.
+  pi.on('before_agent_start', async () => {
+    if (pendingSessionContext.length === 0) return
+    const content = pendingSessionContext.join('\n')
+    pendingSessionContext = []
+    return { message: { customType: 'claude-hook-context', content, display: false } }
+  })
+
+  pi.on('tool_call', async (event, ctx) => {
+    const decision = await runPreToolUse(config, event.toolName, event.input, boundRunner(ctx, { tool_use_id: event.toolCallId }), mcpAliases.get(event.toolName), (message) => ctx.ui.notify(message, 'warning'))
     if (!decision.block) return undefined
-    // pi still emits tool_execution_end (isError) for a blocked call, which also
-    // cleans up; deleting here just avoids relying on that host detail.
-    pendingInputs.delete(event.toolCallId)
     return { block: true, reason: decision.reason }
   })
 
-  pi.on('tool_execution_end', async (event) => {
-    const toolInput = pendingInputs.get(event.toolCallId)
-    pendingInputs.delete(event.toolCallId)
-    if (event.isError) return
+  // Claude's PostToolUse runs after a successful call and feeds back into the result:
+  // a decision:block reason (or exit-2 stderr) and additionalContext are appended next
+  // to the tool result, which is where Claude documents they land. Failed executions
+  // are skipped (Claude routes those to PostToolUseFailure, not bridged yet).
+  pi.on('tool_result', async (event, ctx) => {
     const alias = mcpAliases.get(event.toolName)
     const names = alias ? [event.toolName, alias] : [event.toolName]
-    await runNotifyHooks(matchingCommands(config.PostToolUse, names), { hook_event_name: 'PostToolUse', tool_name: alias ?? event.toolName, tool_input: toolInput, tool_response: event.result }, runner)
+    const response = { content: event.content, details: event.details, isError: event.isError }
+    // A failed execution fires Claude's PostToolUseFailure instead: notify-style, no
+    // result patch, since the error content is already what the model sees.
+    if (event.isError) {
+      const failCommands = matchingCommands(config.PostToolUseFailure, names)
+      if (failCommands.length === 0) return
+      const run = boundRunner(ctx, { tool_use_id: event.toolCallId })
+      const failPayload = { hook_event_name: 'PostToolUseFailure', tool_name: alias ?? event.toolName, tool_input: event.input, tool_response: response }
+      const failResults = await Promise.all(failCommands.map((command) => run(command.command, failPayload, timeoutMs(command))))
+      surfaceSystemMessages(failResults, (message) => ctx.ui.notify(message, 'warning'))
+      return
+    }
+    const commands = matchingCommands(config.PostToolUse, names)
+    if (commands.length === 0) return
+    const payload = {
+      hook_event_name: 'PostToolUse',
+      tool_name: alias ?? event.toolName,
+      tool_input: event.input,
+      tool_response: response,
+    }
+    const run = boundRunner(ctx, { tool_use_id: event.toolCallId })
+    const results = await Promise.all(commands.map((command) => run(command.command, payload, timeoutMs(command))))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    const feedback: string[] = []
+    for (const result of results) {
+      const parsed = tryParseJson(result.stdout)
+      if (!result.timedOut && result.code === 2) feedback.push(`PostToolUse hook: ${result.stderr.trim() || 'Blocked by hook'}`)
+      else if (parsed?.decision === 'block') feedback.push(`PostToolUse hook: ${parsed.reason ?? 'Blocked by hook'}`)
+      const context = parsed?.hookSpecificOutput?.additionalContext
+      if (context) feedback.push(context)
+    }
+    if (feedback.length === 0) return
+    return { content: [...event.content, ...feedback.map((text) => ({ type: 'text' as const, text }))] }
   })
 
   pi.on('input', async (event, ctx) => {
     // Only genuine user input; extension-injected messages (plan-mode, subagent) are not
     // prompts the user submitted.
     if (event.source === 'extension') return { action: 'continue' }
-    const decision = await runUserPromptSubmit(config, event.text, runner)
+    const decision = await runUserPromptSubmit(config, event.text, boundRunner(ctx), (message) => ctx.ui.notify(message, 'warning'))
     if (decision.block) {
       // pi's input result has no reason channel, so surface why before consuming it.
       ctx.ui.notify(decision.reason ?? 'Prompt blocked by hook', 'error')
@@ -373,19 +481,48 @@ export default function hooksExtension(pi: ExtensionAPI) {
     return { action: 'continue' }
   })
 
-  // Notify-style Claude events with a matching pi lifecycle seam. None can block: pi's
-  // agent_end, session_before_compact and session_shutdown are fire-and-forget here.
-  pi.on('agent_end', async () => {
-    await runNotifyHooks(matchingCommands(config.Stop, 'Stop'), { hook_event_name: 'Stop' }, runner)
+  // Claude's Stop hook can prevent stopping: a block feeds its reason back as a new
+  // turn, and stop_hook_active in the payload tells the next firing it is already
+  // continuing from a stop hook, which is the hook script's documented loop guard.
+  // Only exit 2 and decision:"block" continue; continue:false means "stay stopped".
+  pi.on('agent_end', async (_event, ctx) => {
+    const commands = matchingCommands(config.Stop, 'Stop')
+    if (commands.length === 0) {
+      stopHookActive = false
+      return
+    }
+    const payload = { hook_event_name: 'Stop', stop_hook_active: stopHookActive }
+    const run = boundRunner(ctx)
+    const results = await Promise.all(commands.map((command) => run(command.command, payload, timeoutMs(command))))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    const block = results
+      .filter((result) => !result.timedOut)
+      .map((result) => {
+        if (result.code === 2) return { block: true, reason: result.stderr.trim() || 'Stop blocked by hook' }
+        const parsed = tryParseJson(result.stdout)
+        if (parsed?.decision === 'block') return { block: true, reason: parsed.reason ?? 'Stop blocked by hook' }
+        return { block: false, reason: '' }
+      })
+      .find((verdict) => verdict.block)
+    stopHookActive = block !== undefined
+    if (block) pi.sendMessage({ customType: 'claude-stop-hook', content: block.reason, display: true }, { triggerTurn: true })
+  })
+
+  pi.on('session_before_compact', async (event, ctx) => {
+    const trigger = claudeSpelling(PRECOMPACT_TRIGGER, event.reason)
+    const results = await runNotifyHooks(matchingCommands(config.PreCompact, trigger.names), { hook_event_name: 'PreCompact', trigger: trigger.value }, boundRunner(ctx))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
   })
 
-  pi.on('session_before_compact', async (event) => {
+  pi.on('session_compact', async (event, ctx) => {
     const trigger = claudeSpelling(PRECOMPACT_TRIGGER, event.reason)
-    await runNotifyHooks(matchingCommands(config.PreCompact, trigger.names), { hook_event_name: 'PreCompact', trigger: trigger.value }, runner)
+    const results = await runNotifyHooks(matchingCommands(config.PostCompact, trigger.names), { hook_event_name: 'PostCompact', trigger: trigger.value }, boundRunner(ctx))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
   })
 
-  pi.on('session_shutdown', async (event) => {
+  pi.on('session_shutdown', async (event, ctx) => {
     const reason = claudeSpelling(SESSION_END_REASON, event.reason)
-    await runNotifyHooks(matchingCommands(config.SessionEnd, reason.names), { hook_event_name: 'SessionEnd', reason: reason.value }, runner)
+    const results = await runNotifyHooks(matchingCommands(config.SessionEnd, reason.names), { hook_event_name: 'SessionEnd', reason: reason.value }, boundRunner(ctx))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
   })
 }

package/extensions/internal/builtin-styles/explanatory.md

@@ -0,0 +1,15 @@
+---
+name: Explanatory
+description: Educational insights while completing tasks
+keep-coding-instructions: true
+---
+
+Between completing software engineering tasks, provide brief educational "Insights" that help the user understand implementation choices and codebase patterns.
+
+Mark each one clearly:
+
+`✻ Insight ─────`
+(2-3 sentences on why this approach, what pattern it follows, or what tradeoff it makes)
+`─────`
+
+Share an insight when there is a genuine decision or pattern worth understanding, not after every step. Keep the work itself unchanged: insights are commentary, never a substitute for doing the task.

package/extensions/internal/builtin-styles/learning.md

@@ -0,0 +1,15 @@
+---
+name: Learning
+description: Collaborative learn-by-doing with small human-written pieces
+keep-coding-instructions: true
+---
+
+Work collaboratively, learn-by-doing style: share brief "Insights" explaining implementation choices as you work, and regularly ask the user to contribute small, strategic pieces of code themselves.
+
+When a piece is well-scoped for the user to write (a condition, a small function body, a test assertion), leave a marker instead of writing it:
+
+```
+// TODO(human): <one sentence describing exactly what to implement here>
+```
+
+Then stop and ask the user to fill it in, explaining what the piece needs to do and why it matters. Choose pieces that teach something about the codebase or the problem, not busywork. Keep your own contributions moving the task forward between their turns.

package/extensions/internal/builtin-styles/proactive.md

@@ -0,0 +1,9 @@
+---
+name: Proactive
+description: Execute immediately, prefer action over planning
+keep-coding-instructions: true
+---
+
+Execute immediately. Make reasonable assumptions instead of pausing for routine decisions, and prefer action over planning: when a step is reversible and follows from the task, do it rather than proposing it.
+
+Ask only when a decision is genuinely the user's to make (destructive actions, real scope changes). Report what you did and why afterward, concisely.

package/extensions/internal/plan-mode-state.ts

@@ -0,0 +1,15 @@
+/**
+ * Channel and payload for the plan-mode state the plan-mode extension publishes on
+ * pi's shared extension event bus. Hooks report Claude's permission_mode from it;
+ * pi loads extensions without a shared module cache, so state rides the bus.
+ */
+
+export const PLAN_MODE_CHANNEL = 'pi-code:plan-mode'
+
+export interface PlanModeState {
+  active: boolean
+}
+
+export function isPlanModeState(data: unknown): data is PlanModeState {
+  return typeof (data as PlanModeState)?.active === 'boolean'
+}

package/extensions/internal/project-approval.ts

@@ -69,6 +69,16 @@ const APPROVAL_BODY = 'It ships Claude Code configuration that pi-code loads. MC
  * `defaultProjectTrust` at all, so there is no user preference to fall back on. A run
  * that cannot ask has not been approved.
  */
+/** The same decision as isProjectApproved, but never prompts: an undecided project
+ * reads as unapproved. For surfaces that only display project config, like the
+ * subagent roster, where a mid-turn dialog would be wrong. */
+export function isProjectApprovedSilently(ctx: Pick<ApprovalContext, 'cwd' | 'isProjectTrusted'>, deps: ApprovalDeps = defaultDeps): boolean {
+  if (ctx.isProjectTrusted?.() !== true) return false
+  if (!deps.hasClaudeShaped(ctx.cwd)) return true
+  if (deps.piWouldAsk(ctx.cwd)) return true
+  return deps.savedDecision(ctx.cwd) === true
+}
+
 export async function isProjectApproved(ctx: ApprovalContext, deps: ApprovalDeps = defaultDeps): Promise<boolean> {
   if (ctx.isProjectTrusted?.() !== true) return false // pi already declined, or never trusted
   if (!deps.hasClaudeShaped(ctx.cwd)) return true // nothing here pi's own check would miss

package/extensions/internal/subagent-events.ts

@@ -0,0 +1,18 @@
+/**
+ * Channel and payload for subagent lifecycle events the subagent extension publishes
+ * on pi's shared extension event bus. Hooks bridge them to Claude's SubagentStart and
+ * SubagentStop; pi loads extensions without a shared module cache, so state rides the bus.
+ */
+
+export const SUBAGENT_CHANNEL = 'pi-code:subagent'
+
+export interface SubagentPhaseEvent {
+  phase: 'start' | 'stop'
+  agentType: string
+  agentId: string
+}
+
+export function isSubagentPhaseEvent(data: unknown): data is SubagentPhaseEvent {
+  const event = data as SubagentPhaseEvent
+  return (event?.phase === 'start' || event?.phase === 'stop') && typeof event.agentType === 'string' && typeof event.agentId === 'string'
+}

package/extensions/mcp.ts

@@ -92,6 +92,37 @@ export function projectConfigPaths(cwd: string): string[] {
   return [path.join(cwd, '.mcp.json'), path.join(cwd, '.pi', 'mcp.json')]
 }
 
+export interface ProjectServerPolicy {
+  disabled: Set<string>
+  consented: Set<string>
+  consentAll: boolean
+}
+
+/** Claude's per-server approvals for project .mcp.json servers. Consent-granting keys
+ * (enabledMcpjsonServers, enableAllProjectMcpServers) count only from files the repo
+ * does not control (user settings and settings.local.json), so a checked-in
+ * settings.json cannot approve its own servers. disabledMcpjsonServers counts from
+ * every file and wins over consent. Lists union across files: for denies the union is
+ * the restrictive reading, and consent is the union of the user's own two files. */
+export function projectServerPolicy(cwd: string, home: string): ProjectServerPolicy {
+  const read = (file: string): Record<string, unknown> => {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf-8'))
+    } catch {
+      return {}
+    }
+  }
+  const names = (value: unknown): string[] => (Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [])
+  const userSettings = read(path.join(home, '.claude', 'settings.json'))
+  const projectSettings = read(path.join(cwd, '.claude', 'settings.json'))
+  const localSettings = read(path.join(cwd, '.claude', 'settings.local.json'))
+  const disabled = new Set([...names(userSettings.disabledMcpjsonServers), ...names(projectSettings.disabledMcpjsonServers), ...names(localSettings.disabledMcpjsonServers)])
+  const consentSources = [userSettings, localSettings]
+  const consented = new Set(consentSources.flatMap((settings) => names(settings.enabledMcpjsonServers)))
+  const consentAll = consentSources.some((settings) => settings.enableAllProjectMcpServers === true)
+  return { disabled, consented, consentAll }
+}
+
 export function loadConfigFrom(files: string[]): Record<string, ServerConfig> {
   const servers: Record<string, ServerConfig> = {}
   for (const file of files) {
@@ -325,11 +356,27 @@ export default async function mcpExtension(pi: ExtensionAPI) {
       userConnected = true
       await connectServers(loadUserScope(os.homedir(), ctx.cwd))
     }
-    // A project .mcp.json can run arbitrary commands on connect, so only honor it once the project is trusted.
-    // isProjectTrusted alone is true for a repo pi never asked about; see project-approval.
-    if (!projectConnected && (await isProjectApproved(ctx))) {
-      projectConnected = true
-      await connectServers(loadConfigFrom(projectConfigPaths(ctx.cwd)))
+    // A project .mcp.json can run arbitrary commands on connect, so only honor it once
+    // the project is trusted. Per-server settings refine that: disabled servers never
+    // connect, servers the user consented to individually connect without the
+    // whole-project confirm, and the rest stay behind it. Reconnect attempts after a
+    // refusal are safe: connectServers skips names that already connected.
+    if (!projectConnected) {
+      const policy = projectServerPolicy(ctx.cwd, os.homedir())
+      const candidates = loadConfigFrom(projectConfigPaths(ctx.cwd))
+      const consented: Record<string, ServerConfig> = {}
+      const gated: Record<string, ServerConfig> = {}
+      for (const [name, config] of Object.entries(candidates)) {
+        if (policy.disabled.has(name)) continue
+        if (policy.consentAll || policy.consented.has(name)) consented[name] = config
+        else gated[name] = config
+      }
+      if (Object.keys(consented).length > 0) await connectServers(consented)
+      if (Object.keys(gated).length === 0) projectConnected = true
+      else if (await isProjectApproved(ctx)) {
+        projectConnected = true
+        await connectServers(gated)
+      }
     }
 
     pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])

package/extensions/output-styles.ts

@@ -8,8 +8,11 @@
  * tone and role. `/output-style` lists the styles and persists a choice to the
  * project's settings.local.json.
  *
- * pi keeps its own base system prompt (tools, safety); the style is layered on
- * top rather than replacing it wholesale.
+ * Claude semantics: a style replaces the built-in coding instructions unless its
+ * frontmatter sets `keep-coding-instructions: true`. The replacement excises pi's
+ * default coding prose up to a stable marker line and keeps everything after it
+ * (append text, project context, skills, other extensions' additions); when the
+ * marker is absent (custom SYSTEM.md), the style falls back to appending.
  *
  * Docs: https://code.claude.com/docs/en/output-styles.md
  */
@@ -25,6 +28,7 @@ export interface OutputStyle {
   name: string
   description: string
   body: string
+  keepCodingInstructions: boolean
 }
 
 function field(frontmatter: string, key: string): string {
@@ -37,7 +41,27 @@ 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() }
+  return { name: field(frontmatter, 'name') || fallbackName, description: field(frontmatter, 'description'), body: body.trim(), keepCodingInstructions: field(frontmatter, 'keep-coding-instructions') === 'true' }
+}
+
+/** Equivalents of Claude's built-in styles, shipped with pi-code as the
+ * lowest-precedence source: a user or project style of the same name wins. */
+export const BUILTIN_STYLES_DIR = path.join(import.meta.dirname, 'internal', 'builtin-styles')
+
+/** The last line of pi's default coding instructions. Everything after it (append
+ * text, project context, skills, cwd, other extensions' additions) survives a style
+ * replacement. Tracks pi's dist/core/system-prompt.js; a canary test pins it. */
+export const CODING_BASE_MARKER = '- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)'
+
+/** Apply a style per Claude semantics: replace the coding instructions unless the
+ * style keeps them; fall back to appending when the marker is absent. */
+export function applyStyle(systemPrompt: string, style: OutputStyle): string {
+  const styleSection = `## Output Style: ${style.name}\n\n${style.body}`
+  if (!style.keepCodingInstructions) {
+    const idx = systemPrompt.indexOf(CODING_BASE_MARKER)
+    if (idx !== -1) return `${styleSection}${systemPrompt.slice(idx + CODING_BASE_MARKER.length)}`
+  }
+  return `${systemPrompt}\n\n${styleSection}`
 }
 
 function isDirectory(target: string): boolean {
@@ -132,7 +156,7 @@ export default function outputStylesExtension(pi: ExtensionAPI) {
     // project styles / selection once the project is approved. isProjectTrusted alone
     // is true for a repo pi never asked about; see project-approval.
     const trusted = await isProjectApproved(ctx)
-    styles = loadStyles(styleDirs(ctx.cwd, home, trusted))
+    styles = loadStyles([BUILTIN_STYLES_DIR, ...styleDirs(ctx.cwd, home, trusted)])
     localSettingsPath = path.join(ctx.cwd, '.claude', 'settings.local.json')
     activeName = readActiveStyleName(settingsFiles(ctx.cwd, home, trusted))
     const active = styleForName(styles, activeName)
@@ -142,12 +166,24 @@ export default function outputStylesExtension(pi: ExtensionAPI) {
   pi.on('before_agent_start', async (event) => {
     const active = styleForName(styles, activeName)
     if (!active || active.body.length === 0) return
-    return { systemPrompt: `${event.systemPrompt}\n\n## Output Style: ${active.name}\n\n${active.body}` }
+    return { systemPrompt: applyStyle(event.systemPrompt, active) }
   })
 
   pi.registerCommand('output-style', {
-    description: 'Choose the active Claude output style',
-    handler: async (_args, ctx) => {
+    description: 'Choose the active Claude output style (or /output-style <name>)',
+    handler: async (args, ctx) => {
+      const requested = args.trim()
+      if (requested) {
+        const picked = styles.find((style) => style.name.toLowerCase() === requested.toLowerCase())
+        if (!picked) {
+          ctx.ui.notify(`Unknown output style: ${requested}. Available: ${styles.map((style) => style.name).join(', ')}`, 'error')
+          return
+        }
+        activeName = picked.name
+        persistActiveStyle(localSettingsPath, picked.name)
+        ctx.ui.notify(`Output style set to ${picked.name} (applies next turn)`, 'info')
+        return
+      }
       if (!ctx.hasUI) {
         ctx.ui.notify('/output-style requires interactive mode', 'error')
         return