pi-code 0.4.2 → 0.6.0

package/README.md

@@ -38,7 +38,7 @@ 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` |
+| 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`, `/output-style` switcher | `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` |

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
@@ -22,9 +35,11 @@
  *
  * Config is merged from ~/.claude/settings.json (always) plus the project's
  * .claude/settings.json and settings.local.json (only when the project is
- * trusted, since hooks execute arbitrary shell). Claude tool matchers are
- * PascalCase (`Bash`); pi tool names are lowercase (`bash`), so matchers are
- * applied case-insensitively.
+ * trusted, since hooks execute arbitrary shell). Matchers follow Claude's rule:
+ * `*`/empty match all, plain names are exact (with `|`/`,` list separators), and
+ * anything with other regex characters is an unanchored regex. Claude matchers
+ * are PascalCase (`Bash`); pi tool names are lowercase (`bash`), so comparison
+ * is case-insensitive and folds `-` to `_`.
  *
  * Docs: https://code.claude.com/docs/en/hooks.md
  */
@@ -33,9 +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
 
@@ -86,12 +104,34 @@ export function loadHooks(files: string[]): HooksConfig {
   return config
 }
 
-function matcherApplies(matcher: string | undefined, name: string): boolean {
+/** Claude's rule: a matcher of only letters, digits, `_`, `-`, spaces, `,` and `|`
+ * is a list of exact names; anything else is an unanchored regex. */
+const EXACT_MATCHER = /^[\w\- ,|]*$/
+
+/** Claude names are PascalCase and keep dashes (`Bash`, `mcp__brave-search__x`);
+ * pi names are lowercase with underscores, so comparison folds both. */
+function foldName(name: string): string {
+  return name.toLowerCase().replaceAll('-', '_')
+}
+
+function exactListApplies(matcher: string, names: readonly string[]): boolean {
+  const tokens = new Set(
+    matcher
+      .split(/[|,]/)
+      .map((token) => foldName(token.trim()))
+      .filter(Boolean),
+  )
+  return names.some((name) => tokens.has(foldName(name)))
+}
+
+function matcherApplies(matcher: string | undefined, names: readonly string[]): boolean {
   if (!matcher || matcher === '*') return true
+  if (EXACT_MATCHER.test(matcher)) return exactListApplies(matcher, names)
   try {
-    return new RegExp(`^(?:${matcher})$`, 'i').test(name)
+    const regex = new RegExp(matcher, 'i')
+    return names.some((name) => regex.test(name))
   } catch {
-    return matcher.toLowerCase() === name.toLowerCase()
+    return exactListApplies(matcher, names)
   }
 }
 
@@ -101,16 +141,25 @@ function isRunnableHook(hook: HookCommand): boolean {
   return typeof hook.command === 'string' && (hook.type === undefined || hook.type === 'command')
 }
 
-/** Command specs whose matcher applies to the given tool/source name. */
-export function matchingCommands(matchers: HookMatcher[] | undefined, name: string): HookCommand[] {
+/** Command specs whose matcher applies to any of the given tool/source names.
+ * Multiple candidates let one event offer both the pi name and its Claude alias. */
+export function matchingCommands(matchers: HookMatcher[] | undefined, names: string | readonly string[]): HookCommand[] {
+  const candidates = typeof names === 'string' ? [names] : names
   const result: HookCommand[] = []
+  const seen = new Set<string>()
   for (const entry of matchers ?? []) {
-    if (matcherApplies(entry.matcher, name)) result.push(...(entry.hooks ?? []).filter(isRunnableHook))
+    if (!matcherApplies(entry.matcher, candidates)) continue
+    for (const hook of (entry.hooks ?? []).filter(isRunnableHook)) {
+      // Claude runs a handler defined in more than one settings file once.
+      if (seen.has(hook.command)) continue
+      seen.add(hook.command)
+      result.push(hook)
+    }
   }
   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 {
@@ -208,21 +257,50 @@ function timeoutMs(command: HookCommand): number {
   return seconds * 1000
 }
 
-/** Run PreToolUse hooks for a tool; the first blocking verdict wins. */
-export async function runPreToolUse(config: HooksConfig, toolName: string, toolInput: unknown, runner: HookRunner): Promise<HookDecision> {
-  for (const command of matchingCommands(config.PreToolUse, toolName)) {
-    const result = await runner(command.command, { hook_event_name: 'PreToolUse', tool_name: toolName, tool_input: toolInput }, timeoutMs(command))
+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. 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 {
@@ -241,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)
@@ -254,53 +333,143 @@ 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. */
+const SESSION_START_SOURCE: Record<string, string> = { startup: 'startup', new: 'clear', resume: 'resume', fork: 'fork' }
+const PRECOMPACT_TRIGGER: Record<string, string> = { manual: 'manual', threshold: 'auto', overflow: 'auto' }
+const SESSION_END_REASON: Record<string, string> = { quit: 'prompt_input_exit', new: 'clear', resume: 'resume', reload: 'other', fork: 'other' }
+
+/** The raw pi value plus its Claude spelling, deduplicated, for matcher candidates. */
+function claudeSpelling(map: Record<string, string>, raw: string): { names: string[]; value: string } {
+  const value = map[raw] ?? raw
+  return { names: value === raw ? [raw] : [raw, value], value }
+}
 
 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>()
+  pi.events.on(MCP_TOOLS_CHANNEL, (data) => {
+    if (!isMcpToolAliases(data)) return
+    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))
-    // Only fire SessionStart hooks on a genuine session begin, matched by source (Claude uses
-    // "startup"/"resume"/...). "reload" and "fork" re-fire in-process and would double-run hooks.
-    if (event.reason === 'reload' || event.reason === 'fork') return
-    await runNotifyHooks(matchingCommands(config.SessionStart, event.reason), { hook_event_name: 'SessionStart', source: event.reason }, runner)
+    // "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
+    const source = claudeSpelling(SESSION_START_SOURCE, event.reason)
+    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)
+  // 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
-    await runNotifyHooks(matchingCommands(config.PostToolUse, event.toolName), { hook_event_name: 'PostToolUse', tool_name: event.toolName, tool_input: toolInput, tool_response: event.result }, runner)
+  // 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]
+    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')
@@ -312,17 +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) => {
-    await runNotifyHooks(matchingCommands(config.PreCompact, event.reason), { hook_event_name: 'PreCompact', trigger: event.reason }, runner)
+  pi.on('session_compact', async (event, ctx) => {
+    const trigger = claudeSpelling(PRECOMPACT_TRIGGER, event.reason)
+    const results = await runNotifyHooks(matchingCommands(config.PostCompact, trigger.names), { hook_event_name: 'PostCompact', trigger: trigger.value }, boundRunner(ctx))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
   })
 
-  pi.on('session_shutdown', async (event) => {
-    await runNotifyHooks(matchingCommands(config.SessionEnd, event.reason), { hook_event_name: 'SessionEnd', reason: event.reason }, runner)
+  pi.on('session_shutdown', async (event, ctx) => {
+    const reason = claudeSpelling(SESSION_END_REASON, event.reason)
+    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/mcp-alias.ts

@@ -0,0 +1,21 @@
+/**
+ * Channel and payload for the MCP tool-name registry the mcp extension publishes on
+ * pi's shared extension event bus. Claude Code names MCP tools `mcp__<server>__<tool>`
+ * (original names, dashes preserved); pi-code registers them as `<server>_<tool>` with
+ * dashes folded to underscores. Hook matchers written for Claude need the mapping, and
+ * pi loads every extension without a shared module cache, so cross-extension state must
+ * ride the bus rather than a module singleton.
+ */
+
+export const MCP_TOOLS_CHANNEL = 'pi-code:mcp-tools'
+
+export interface McpToolAlias {
+  /** Tool name as registered in pi, e.g. `github_create_issue`. */
+  pi: string
+  /** Claude Code's name for the same tool, e.g. `mcp__github__create_issue`. */
+  claude: string
+}
+
+export function isMcpToolAliases(data: unknown): data is McpToolAlias[] {
+  return Array.isArray(data) && data.every((entry) => typeof (entry as McpToolAlias)?.pi === 'string' && typeof (entry as McpToolAlias)?.claude === 'string')
+}

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/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

@@ -29,6 +29,7 @@ import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js' //
 import { getDefaultEnvironment, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
 import { Type } from 'typebox'
+import { MCP_TOOLS_CHANNEL, type McpToolAlias } from './internal/mcp-alias.js'
 import { capForContext } from './internal/output-guard.js'
 import { isProjectApproved } from './internal/project-approval.js'
 
@@ -261,6 +262,8 @@ export default async function mcpExtension(pi: ExtensionAPI) {
   const clients = new Map<string, Client>()
   const status = new Map<string, { state: string; tools: number }>()
   const registered = new Set<string>()
+  // Original server/tool names per registered pi name, for Claude-style hook matchers.
+  const aliases: McpToolAlias[] = []
 
   async function connectServers(servers: Record<string, ServerConfig>): Promise<void> {
     for (const [name, config] of Object.entries(servers)) {
@@ -283,6 +286,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
             continue
           }
           registered.add(toolName)
+          aliases.push({ pi: toolName, claude: `mcp__${name}__${tool.name}` })
           count++
           pi.registerTool({
             name: toolName,
@@ -328,6 +332,8 @@ export default async function mcpExtension(pi: ExtensionAPI) {
       await connectServers(loadConfigFrom(projectConfigPaths(ctx.cwd)))
     }
 
+    pi.events.emit(MCP_TOOLS_CHANNEL, [...aliases])
+
     const connected = [...status.values()].filter((s) => s.state === 'connected')
     const failed = [...status.entries()].filter(([, s]) => s.state !== 'connected')
     if (connected.length > 0 || failed.length > 0) {

package/extensions/memory.ts

@@ -18,7 +18,10 @@ import { capForContext } from './internal/output-guard.js'
 const INDEX_FILE = 'MEMORY.md'
 
 export function projectSlug(cwd: string): string {
-  return cwd.replace(/[/\\]/g, '-').replace(/^-+/, '-')
+  return cwd
+    .replace(/^([A-Za-z]):(?=[/\\])/, '$1')
+    .replace(/[/\\]/g, '-')
+    .replace(/^-+/, '-')
 }
 
 export function memoryDir(cwd: string): string {

package/extensions/plan-mode/index.ts

@@ -17,6 +17,8 @@ import type { AssistantMessage, TextContent } from '@earendil-works/pi-ai'
 import type { ExtensionAPI, ExtensionContext, SessionEntry } from '@earendil-works/pi-coding-agent'
 import { Key } from '@earendil-works/pi-tui'
 import { Type } from 'typebox'
+
+import { PLAN_MODE_CHANNEL } from '../internal/plan-mode-state.js'
 import { extractTodoItems, isSafeCommand, markCompletedSteps, planToTodos, type TodoItem } from './utils.js'
 
 // Tools
@@ -70,6 +72,11 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     }
   }
 
+  /** Hooks report Claude's permission_mode from this bus state. */
+  function publishPlanState(): void {
+    pi.events.emit(PLAN_MODE_CHANNEL, { active: planModeEnabled })
+  }
+
   pi.registerFlag('plan', {
     description: 'Start in plan mode (read-only exploration)',
     type: 'boolean',
@@ -116,6 +123,7 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     }
     // Persist the toggle so a resume does not restore a state the user left.
     persistState()
+    publishPlanState()
     updateStatus(ctx)
   }
 
@@ -158,6 +166,7 @@ export default function planModeExtension(pi: ExtensionAPI): void {
       executionMode = todoItems.length > 0
       planFromTool = false
       restoreTools()
+      publishPlanState()
       updateStatus(ctx)
 
       // Persist before the turn: a crash before the first turn_end must resume into
@@ -377,6 +386,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
       todoItems = planModeEntry.data.todos ?? todoItems
       executionMode = planModeEntry.data.executing ?? executionMode
     }
+    publishPlanState()
 
     // On resume: re-scan messages after the last "plan-mode-execute" to rebuild
     // completion state without picking up [DONE:n] from previous plans

package/extensions/subagent/index.ts

@@ -13,6 +13,7 @@
  */
 
 import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
@@ -24,6 +25,7 @@ import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui'
 import { type Static, Type } from 'typebox'
 import { capForContext } from '../internal/output-guard.js'
 import { isProjectApproved } from '../internal/project-approval.js'
+import { SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
 import { type AgentConfig, type AgentScope, discoverAgents } from './agents.js'
 import { activeBackgroundRuns, backgroundStatusText, MAX_BACKGROUND_RUNS, startBackgroundRun } from './background.js'
 
@@ -256,9 +258,25 @@ interface RunAgentOptions {
   signal?: AbortSignal
   onUpdate?: OnUpdateCallback
   makeDetails: (results: SingleResult[]) => SubagentDetails
+  onPhase?: SubagentPhaseSink
 }
 
+/** Publishes a child run's start/stop for the hooks extension's SubagentStart/Stop. */
+type SubagentPhaseSink = (phase: 'start' | 'stop', agentType: string, agentId: string) => void
+
 async function runSingleAgent(options: RunAgentOptions): Promise<SingleResult> {
+  const agent = options.agents.find((a) => a.name === options.agentName)
+  if (!agent) return runSingleAgentInner(options)
+  const agentId = `fg-${randomUUID().slice(0, 8)}`
+  options.onPhase?.('start', agent.name, agentId)
+  try {
+    return await runSingleAgentInner(options)
+  } finally {
+    options.onPhase?.('stop', agent.name, agentId)
+  }
+}
+
+async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResult> {
   const { defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails } = options
   const agent = agents.find((a) => a.name === agentName)
 
@@ -478,6 +496,7 @@ interface ModeContext {
   signal: AbortSignal | undefined
   onUpdate: OnUpdateCallback | undefined
   makeDetails: MakeDetails
+  onPhase?: SubagentPhaseSink
 }
 
 async function checkProjectAgentGate(params: SubagentParamsStatic, agents: AgentConfig[], ctx: ExtensionContext, projectAgentsDir: string | null, gateMode: SubagentMode, makeDetails: MakeDetails): Promise<ToolResult | null> {
@@ -572,6 +591,7 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
   const invocation = getPiInvocation(args)
   const id = startBackgroundRun(agent.name, task, { command: invocation.command, args: invocation.args, cwd: params.cwd ?? defaultCwd }, (run) => {
     removeTmpPrompt(tmpPrompt)
+    pi.events.emit(SUBAGENT_CHANNEL, { phase: 'stop', agentType: run.agent, agentId: run.id })
     const output = capForContext(run.output ?? '') || '(no output)'
     pi.sendMessage(
       {
@@ -587,6 +607,7 @@ async function runBackgroundMode(params: SubagentParamsStatic, agents: AgentConf
     removeTmpPrompt(tmpPrompt)
     return backgroundCapResult(makeDetails)
   }
+  pi.events.emit(SUBAGENT_CHANNEL, { phase: 'start', agentType: agent.name, agentId: id })
   return {
     content: [{ type: 'text', text: `Started background run ${id} (${agent.name}). A notification will arrive on completion; check progress with {status: true}.` }],
     details: makeDetails('single')([]),
@@ -628,6 +649,7 @@ async function runChainMode(chain: ChainStepParam[], mode: ModeContext): Promise
       signal,
       onUpdate: chainUpdate,
       makeDetails: makeDetails('chain'),
+      onPhase: mode.onPhase,
     })
     results.push(result)
 
@@ -695,6 +717,7 @@ async function runParallelMode(tasks: TaskItemParam[], mode: ModeContext): Promi
       task: t.task,
       cwd: t.cwd,
       signal,
+      onPhase: mode.onPhase,
       // Per-task update callback
       onUpdate: (partial) => {
         const live = partial.details?.results[0]
@@ -741,6 +764,7 @@ async function runSingleMode(agentName: string, task: string, cwd: string | unde
     signal,
     onUpdate,
     makeDetails: makeDetails('single'),
+    onPhase: mode.onPhase,
   })
   const isError = result.exitCode !== 0 || result.stopReason === 'error' || result.stopReason === 'aborted'
   if (isError) {
@@ -1109,7 +1133,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 
       if (params.background) return runBackgroundMode(params, agents, ctx.cwd, pi, makeDetails)
 
-      const mode: ModeContext = { agents, defaultCwd: ctx.cwd, signal, onUpdate, makeDetails }
+      const mode: ModeContext = { agents, defaultCwd: ctx.cwd, signal, onUpdate, makeDetails, onPhase: (phase, agentType, agentId) => pi.events.emit(SUBAGENT_CHANNEL, { phase, agentType, agentId }) }
 
       if (params.chain?.length) return runChainMode(params.chain, mode)
       if (params.tasks?.length) return runParallelMode(params.tasks, mode)

package/package.json

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