pi-code 1.0.14 → 1.0.15

package/README.md

@@ -45,7 +45,7 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 | Custom slash commands | `.claude/commands/**/*.md` (namespaced `/dir:name`); `$ARGUMENTS` (with the `ARGUMENTS:` append when unused), 0-based `$ARGUMENTS[N]`/`$N`, named `arguments:` frontmatter, `${CLAUDE_SESSION_ID}`/`${CLAUDE_EFFORT}`/`${CLAUDE_SKILL_DIR}`/`${CLAUDE_PROJECT_DIR}` (in bodies and `allowed-tools` rules); `` !`cmd` `` and multi-line ```` ```! ```` bash (whitespace-bounded, merged stderr, 2-minute budget, a failure aborts the invocation with the documented exit-1 carveout), `@file` inlining; `allowed-tools` with `Bash(...)` and `Read`/`Edit`/`Write` path scopes enforced at call time (gitignore anchors, Edit governs writes), `disallowed-tools`, `argument-hint`, `model` (switches the session model for the command's turn, restored after), `effort` (raises reasoning for the turn, restored after), `shell: powershell` (injected spans run through PowerShell when a `pwsh` binary is present, else `/bin/sh`); the model can also run a command itself through the `SlashCommand` tool (Claude's `SlashCommand` in `allowed-tools`), steered by `when_to_use` and opted out per file with `disable-model-invocation` (`user-invocable: false` hides a command from the menu while still exposing it to the model); `disableSkillShellExecution` (managed and user always, project when trusted) replaces every `!` span with a policy-disabled placeholder; project commands gated on approval | `commands.ts` |
 | `/init` | generates a project context file: detects an existing `AGENTS.md`/`CLAUDE.md` (proposes improvements) or none (creates `AGENTS.md`, pi's preferred name), ingesting `.cursor/rules`, `.cursorrules`, and `.github/copilot-instructions.md` when present; drives the main agent with full tools via a prompt (not a tool-less completion) so it analyzes the codebase and writes the file itself | `init.ts` |
 | Skills | `.claude/skills` → pi skill discovery, project skills gated on approval (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.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, Notification (idle_prompt, the type pi can source), InstructionsLoaded (observational: fires per loaded context file at session start, plus `path_glob_match` on a scoped-rule attach and `include` per resolved `@import`; deduped per session; `nested_traversal`/`compact` reasons never fire since pi does not lazily load nested CLAUDE.md or reload after compaction); `type: http` entries POST the payload (a 2xx JSON body renders the decision, everything else is non-blocking per Claude's contract), `type: prompt` evaluates in-process against the session model, `type: mcp_tool` calls a connected server's tool, and `type: agent` (experimental) spawns a read-only Read/Grep/Glob subagent that returns the JSON decision (a missing model/server/runner is non-blocking, only a PreToolUse timeout fails closed); Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort; `permissionDecision: "ask"` prompts via a confirm dialog (blocks when headless), SubagentStop/PostToolUseFailure are notify-only, and a timed-out PreToolUse/UserPromptSubmit hook fails closed at a 60s default (Claude: 600s, non-blocking) since pi has no permission backstop; a `command` hook may use exec form (`command` as an argv array, run with no shell) and executes with `CLAUDECODE=1` and `CLAUDE_PROJECT_DIR` set; a user-typed `!`/`!!` bash line runs PreToolUse (there is no PostToolUse for it); `type: http` targets are gated by `allowedHttpHookUrls` (union of managed and settings scopes; unset allows all, `[]` blocks every http hook); a Stop hook may block at most 8 times before the turn ends (`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`); `disableAllHooks` in any scope turns the system off; `/hooks` prints the resolved configuration | `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, Notification (idle_prompt, the type pi can source), InstructionsLoaded (observational: fires per loaded context file at session start, plus `path_glob_match` on a scoped-rule attach and `include` per resolved `@import`; deduped per session; `nested_traversal`/`compact` reasons never fire since pi does not lazily load nested CLAUDE.md or reload after compaction); `type: http` entries POST the payload (a 2xx JSON body renders the decision, everything else is non-blocking per Claude's contract), `type: prompt` evaluates in-process against the session model, `type: mcp_tool` calls a connected server's tool, and `type: agent` (experimental) spawns a read-only Read/Grep/Glob subagent that returns the JSON decision (a missing model/server/runner is non-blocking, only a PreToolUse timeout fails closed); Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort; `permissionDecision: "ask"` prompts via a confirm dialog (blocks when headless), SubagentStop/PostToolUseFailure are notify-only, and a timed-out PreToolUse/UserPromptSubmit hook fails closed at a 60s default (Claude: 600s, non-blocking) since pi has no permission backstop; `async`/`asyncRewake` command hooks run in the background on every event (never blocking, no decision, no timeout enforced on `async` while asyncRewake keeps its own; an asyncRewake exit 2 wakes the model with the hook's stderr as a new turn, other completions deliver `systemMessage`/`additionalContext` to the model on the next turn, and hooks still running at session end are killed); a `command` hook may use exec form (`command` as an argv array, run with no shell) and executes with `CLAUDECODE=1` and `CLAUDE_PROJECT_DIR` set; a user-typed `!`/`!!` bash line runs PreToolUse (there is no PostToolUse for it); `type: http` targets are gated by `allowedHttpHookUrls` (union of managed and settings scopes; unset allows all, `[]` blocks every http hook); a Stop hook may block at most 8 times before the turn ends (`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`); `disableAllHooks` in any scope turns the system off; `/hooks` prints the resolved configuration | `hooks.ts` |
 | Output styles | `.claude/output-styles` + active `outputStyle`; plus styles shipped by enabled plugins (manifest `outputStyles`, default `output-styles/`, ranked below the user's and project's own); Claude replace semantics with `keep-coding-instructions`; bundled Explanatory/Learning/Proactive; `/output-style [name]` | `output-styles.ts` |
 | CLAUDE.md `@imports` and rewriting | resolves `@path` imports pi's native loader skips (4-hop depth, budget-capped); loads the user `~/.claude/CLAUDE.md` and the project `.claude/CLAUDE.md` (approval-gated, deduped against the repo-root `CLAUDE.md`/`AGENTS.md` pi loads natively) that pi's own loader does not; loads every `CLAUDE.local.md` from the repo root down to cwd (approval-gated, root first); injects the managed `CLAUDE.md` (a per-OS file beside `managed-settings.json`) and the `claudeMd` string from `managed-settings.json` at the top of context (managed content is never excludable); honors `claudeMdExcludes` (glob/absolute-path skip list from user, approved-project, and managed settings, merged; managed content never excluded); strips block-level HTML comments from CLAUDE.md, rule, and imported bodies (fenced-code comments preserved), so a commented-out `@import` does not expand; with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` set, loads `CLAUDE.md`/`.claude/CLAUDE.md`/`.claude/rules/*.md`/`CLAUDE.local.md` from each `--add-dir` directory (comma-separated for several, since pi's flag is single-value) | `context-imports.ts` |
 | Settings `env` | `env` blocks from `managed-settings.json`, `~/.claude/settings.json`, and the project `.claude/settings.json`/`settings.local.json` exported into the session (per-key `managed > user > project`); the project scope is approval-gated (a repo's env can redirect providers), a shell `export` outranks user and project but a managed key overrides even that, and a key an approved project set is unset once a later session no longer defines it | `env-settings.ts` |

package/extensions/hooks/config.ts

@@ -17,6 +17,14 @@ export interface HookCommand {
    * absent). $ARGUMENTS in each arg is replaced with the event JSON. */
   args?: string[]
   timeout?: number
+  /** Claude's background contract, honored on `type: "command"` hooks only: `async` runs
+   * without blocking its event and with no timeout enforced; `asyncRewake` also runs in
+   * the background but keeps its timeout, and wakes the model when the hook exits 2
+   * (stderr, or stdout when stderr is empty, feeds back as a new turn). Background hooks
+   * render no decision; their JSON `systemMessage`/`additionalContext` reach the model on
+   * the next turn, and any still running are killed at session end. */
+  async?: boolean
+  asyncRewake?: boolean
   /** http entries: the endpoint POSTed to; `command` mirrors it for dedup and display. */
   url?: string
   headers?: Record<string, string>
@@ -35,6 +43,13 @@ export interface HookMatcher {
   matcher?: string
   hooks: HookCommand[]
 }
+
+/** Whether a hook runs in the background. Claude documents `async`/`asyncRewake` on
+ * `type: "command"` hooks only; on any other type the fields are inert and the hook
+ * blocks, exactly as Claude runs it. */
+export function isBackgroundHook(hook: HookCommand): boolean {
+  return (hook.type === undefined || hook.type === 'command') && (hook.async === true || hook.asyncRewake === true)
+}
 export type HooksConfig = Record<string, HookMatcher[]>
 
 export function isRecord(value: unknown): value is Record<string, unknown> {

package/extensions/hooks/index.ts

@@ -38,6 +38,14 @@
  * user-facing warning).
  * `suppressOutput` is accepted and inert: pi never echoes hook stdout to the
  * transcript in the first place.
+ * `async`/`asyncRewake` (command hooks only, as Claude documents) run in the
+ * background on every event: they never block or delay the event that fired them
+ * and render no decision. An asyncRewake hook exiting 2 wakes the model with its
+ * stderr (stdout when stderr is empty) as a new turn; any other background
+ * completion delivers the JSON response's systemMessage/additionalContext to the
+ * model on the next turn, shown to nobody else. No timeout is enforced on `async`
+ * (asyncRewake keeps its own), and hooks still running at session end are killed,
+ * as Claude does at teardown.
  *
  * SubagentStart/SubagentStop ride pi-code's own subagent extension, which publishes
  * child-run lifecycle on the shared bus (notify-style: a child has already exited by
@@ -71,7 +79,7 @@ import { installedPlugins } from '../internal/plugins.js'
 import { isProjectApproved } from '../internal/project-approval.js'
 import { repoRoot } from '../internal/project-root.js'
 import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
-import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, loadHooks, loadPluginHooks, readAllowedHttpHookUrls, readDisableAllHooks } from './config.js'
+import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, isBackgroundHook, loadHooks, loadPluginHooks, readAllowedHttpHookUrls, readDisableAllHooks } from './config.js'
 import { blockedToolCall, postToolFeedback, promptContext, runPreToolUse, runUserPromptSubmit, surfaceSystemMessages, tryParseJson } from './decisions.js'
 import { matchingCommands } from './matcher.js'
 import { type HookRunner, type HookRunResult, runAgentHook, runHookCommand, runHttpHook, runMcpToolHook, runPromptHook, timeoutMs } from './runners.js'
@@ -150,17 +158,62 @@ export default function hooksExtension(pi: ExtensionAPI) {
     if (ctx.thinkingLevel) common.effort = { level: ctx.thinkingLevel }
     return common
   }
+  /** Kills for background hooks still running; Claude kills async hooks at teardown,
+   * so session_shutdown reaps anything left rather than let a hung hook pin the
+   * event loop past a one-shot run's end. */
+  const backgroundKills = new Set<() => void>()
+  /** Claude's background delivery: an asyncRewake exit 2 wakes the model with the
+   * hook's stderr (stdout when stderr is empty) as a new turn; any other completion
+   * feeds the JSON response's systemMessage/additionalContext to the model on the
+   * next turn, shown to nobody else. A timeout kill discards the output, like a
+   * canceled synchronous hook; it resolves with code 124, so it never reads as a wake. */
+  const deliverBackgroundResult = (hook: HookCommand, result: HookRunResult): void => {
+    if (result.timedOut) return
+    if (hook.asyncRewake === true && result.code === 2) {
+      const detail = result.stderr.trim() || result.stdout.trim()
+      const content = detail ? `Async hook requested attention (exit 2):\n${detail}` : 'Async hook requested attention (exit 2)'
+      pi.sendMessage({ customType: 'claude-async-hook', content, display: true }, { triggerTurn: true })
+      return
+    }
+    const parsed = tryParseJson(result.stdout)
+    // The typeof guard doubles as Claude's schema validation: a wrong-typed field is
+    // dropped rather than delivered.
+    const parts = [parsed?.systemMessage, parsed?.hookSpecificOutput?.additionalContext].filter((part): part is string => typeof part === 'string' && part.length > 0)
+    if (parts.length === 0) return
+    pi.sendMessage({ customType: 'claude-async-hook', content: parts.join('\n'), display: false }, { deliverAs: 'nextTurn' })
+  }
   /** A runner bound to the firing context, filling the common fields into each
-   * payload and dispatching on the entry's type. */
+   * payload and dispatching on the entry's type. A background hook (see
+   * isBackgroundHook) is fired and the caller immediately gets a no-verdict result,
+   * so it can neither block nor delay the event that fired it; its completion is
+   * delivered by deliverBackgroundResult whenever it lands. */
   const boundRunner =
     (ctx: ExtensionContext, extra?: Record<string, unknown>): HookRunner =>
     (hook, payload, ms) => {
       const merged = { ...commonPayload(ctx), ...extra, ...(payload as Record<string, unknown>) }
-      if (hook.type === 'http') return runHttpHook(hook, merged, ms, allowedHttpHookUrls)
-      if (hook.type === 'prompt') return runPromptHook(hook, merged, ctx.model, ms)
-      if (hook.type === 'agent') return runAgentHook(hook, merged, ms, (ctx.model as { id?: string } | undefined)?.id)
-      if (hook.type === 'mcp_tool') return runMcpToolHook(hook, merged, ms)
-      return runHookCommand(hook.command, merged, ms, projectDir, hook.args)
+      const dispatch = (onChild?: (kill: () => void) => void): Promise<HookRunResult> => {
+        if (hook.type === 'http') return runHttpHook(hook, merged, ms, allowedHttpHookUrls)
+        if (hook.type === 'prompt') return runPromptHook(hook, merged, ctx.model, ms)
+        if (hook.type === 'agent') return runAgentHook(hook, merged, ms, (ctx.model as { id?: string } | undefined)?.id)
+        if (hook.type === 'mcp_tool') return runMcpToolHook(hook, merged, ms)
+        return runHookCommand(hook.command, merged, ms, projectDir, hook.args, onChild)
+      }
+      if (!isBackgroundHook(hook)) return dispatch()
+      let kill: (() => void) | undefined
+      void dispatch((registered) => {
+        kill = registered
+        backgroundKills.add(registered)
+      })
+        .then((result) => deliverBackgroundResult(hook, result))
+        .catch(() => {
+          // The hook may outlive the session (/new, shutdown): sendMessage asserts
+          // liveness, and nothing awaits this chain, so a throw would otherwise
+          // escape as an unhandled rejection.
+        })
+        .finally(() => {
+          if (kill) backgroundKills.delete(kill)
+        })
+      return Promise.resolve({ code: 0, stdout: '', stderr: '', timedOut: false })
     }
   // 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.
@@ -422,6 +475,10 @@ export default function hooksExtension(pi: ExtensionAPI) {
     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'))
+    // Claude kills async hooks still running at teardown; the session that spawned
+    // these is over, and their delivery would target a disposed context anyway.
+    for (const kill of backgroundKills) kill()
+    backgroundKills.clear()
   })
 
   // Claude's /hooks manages hook configuration; pi-code's is a viewer: hook failures

package/extensions/hooks/runners.ts

@@ -9,7 +9,7 @@ import type { Api, Model } from '@earendil-works/pi-ai'
 import { runAgent } from '../internal/agent-run.js'
 import { callMcpTool } from '../internal/mcp-call.js'
 import { completeText } from '../internal/model-complete.js'
-import { type HookCommand, httpUrlAllowed } from './config.js'
+import { type HookCommand, httpUrlAllowed, isBackgroundHook } from './config.js'
 
 // Claude defaults to 600s and lets a timed-out hook proceed; here a timed-out
 // PreToolUse or UserPromptSubmit hook fails closed (pi has no permission prompt
@@ -30,13 +30,20 @@ export interface HookRunResult {
 /** Runs one configured hook entry, whatever its type; boundRunner dispatches. */
 export type HookRunner = (hook: HookCommand, payload: unknown, timeoutMs: number) => Promise<HookRunResult>
 /** The shell path specifically; the statusline reuses it for its own command. With an
- * `args` array it becomes the exec path: `command` is spawned directly with those args. */
-export type HookCommandRunner = (command: string, payload: unknown, timeoutMs: number, projectDir?: string, args?: string[]) => Promise<HookRunResult>
+ * `args` array it becomes the exec path: `command` is spawned directly with those args.
+ * `onChild` hands the caller a kill for the spawned tree, so a background hook that is
+ * still running at session end can be reaped (Claude kills async hooks at teardown). */
+export type HookCommandRunner = (command: string, payload: unknown, timeoutMs: number, projectDir?: string, args?: string[], onChild?: (kill: () => void) => void) => Promise<HookRunResult>
 
 /** Above 2^31-1 ms Node clamps a timer to 1ms, which would kill the hook instantly. */
 const MAX_TIMEOUT_S = 2_147_483
 
 export function timeoutMs(command: HookCommand): number {
+  // Claude does not enforce `timeout` on an `async` command hook (it does on
+  // `asyncRewake`), so the budget is the Node timer ceiling: the timer exists only
+  // so the delay never clamps, not as a deadline. Still-running background hooks
+  // are killed at session end instead.
+  if (isBackgroundHook(command) && command.asyncRewake !== true) return MAX_TIMEOUT_S * 1000
   // Non-positive values fall back to the default: a 0ms timer would fire before the
   // hook runs, and a timed-out PreToolUse hook fails closed, bricking the tool.
   const declared = command.timeout
@@ -67,7 +74,7 @@ function killTree(child: ChildProcess): void {
   child.kill('SIGKILL')
 }
 
-export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, projectDir, args) =>
+export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, projectDir, args, onChild) =>
   new Promise((resolve) => {
     // Absolute path so the shell can't be resolved through an attacker-controlled PATH.
     // `detached` makes the shell its own process group leader so the timeout can kill
@@ -84,6 +91,7 @@ export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, p
     const file = Array.isArray(args) ? command : '/bin/sh'
     const spawnArgs = Array.isArray(args) ? args.map((arg) => substituteArguments(arg, payload)) : ['-c', command]
     const child = spawn(file, spawnArgs, { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env })
+    onChild?.(() => killTree(child))
     let stdout = ''
     let stderr = ''
     let settled = false

package/package.json

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