pi-code 0.5.0 → 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
@@ -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/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/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.5.0",
+  "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",