@aliou/pi-dev-kit 0.6.5 → 0.7.1

package/src/skills/pi-extension/references/hooks.md

@@ -1,169 +1,264 @@
-# Hooks (Events)
+# Hooks and Events
 
-Hooks let extensions react to lifecycle events. They are registered with `pi.on(eventName, handler)`.
+Hooks let extensions observe, modify, or block Pi lifecycle events. Register them with `pi.on(eventName, handler)`.
 
-## Event Reference
-
-### Session Events
-
-| Event | When | Can Cancel | Payload |
-|---|---|---|---|
-| `session_start` | Session starts, reloads, or is replaced | No | `{ reason: "startup" \| "reload" \| "new" \| "resume" \| "fork", previousSessionFile? }` |
-| `session_before_switch` | Before `/new` or `/resume` replaces the current session | Yes (`{ cancel: true }`) | `{ reason: "new" \| "resume", targetSessionFile? }` |
-| `session_before_fork` | Before forking a session | Yes (`{ cancel: true }`) | `{ entryId }` |
-| `session_shutdown` | Current session runtime is shutting down or being replaced | No | `{ reason: "quit" | "reload" | "new-session" | "resume" | "fork", targetSessionFile? }` |
-| `session_before_compact` | Before compaction | Yes (cancel or provide custom compaction) | event-specific compaction data |
-
-### Agent Events
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  // event is event-specific.
+  // ctx is ExtensionContext.
+});
+```
 
-| Event | When | Payload |
-|---|---|---|
-| `before_agent_start` | Before agent turn starts | `{ systemPrompt, systemPromptOptions }` |
-| `agent_start` | Agent turn started | `{}` |
-| `turn_start` | Turn begins processing | `{}` |
-| `turn_end` | Turn finishes processing | `{}` |
-| `model_select` | User changed the model | `{ model: string }` |
+Handlers run in extension load order. For blocking/cancelling events, the first blocking result wins.
 
-### Tool Events
+## Event Lifecycle Summary
 
-| Event | When | Can Block | Payload |
-|---|---|---|---|
-| `tool_call` | Before a tool executes | Yes (`{ block: true, reason }`) | `{ toolName, toolCallId, input }` |
+Common startup and prompt flow:
 
-### Input Events
+1. `session_start`
+2. `resources_discover`
+3. user input arrives
+4. extension command check
+5. `input`
+6. skill/prompt expansion
+7. `before_agent_start`
+8. `agent_start`
+9. repeated turns:
+   - `turn_start`
+   - `context`
+   - `before_provider_request`
+   - `after_provider_response`
+   - message/tool lifecycle events
+   - `turn_end`
+10. `agent_end`
+11. `session_shutdown` on exit, reload, or session replacement
 
-| Event | When | Can Transform | Payload |
-|---|---|---|---|
-| `input` | User submitted a message | Yes (return transformed text) | `{ text: string }` |
+Read Pi `docs/extensions.md` for the exhaustive event diagram before changing lifecycle-heavy code.
 
-### Bash Events
+## Resource Events
 
-| Event | When | Can Modify | Payload |
-|---|---|---|---|
-| `user_bash` | Before bash command runs | Yes (return modified command/cwd/env) | `{ command, cwd }` |
+### `resources_discover`
 
-## Handler Signature
+Contribute skill, prompt, and theme paths after startup or reload.
 
 ```typescript
-pi.on("event_name", async (event, ctx) => {
-  // event: event-specific payload
-  // ctx: ExtensionContext (hasUI, ui methods, cwd, model, etc.)
+pi.on("resources_discover", async (event) => {
+  return {
+    skillPaths: ["/path/to/skills"],
+    promptPaths: ["/path/to/prompts"],
+    themePaths: ["/path/to/themes"],
+  };
 });
 ```
 
-The handler receives the event payload and an `ExtensionContext`. The context provides access to UI methods, the current working directory, model info, and more.
+`event.reason` is `"startup"` or `"reload"`.
 
-## Blocking and Cancelling
+## Session Events
 
-Some events let you prevent the default behavior by returning an object.
+| Event | Can cancel | Notes |
+|---|---:|---|
+| `session_start` | No | Session started, reloaded, resumed, or forked. |
+| `session_before_switch` | Yes | Before `/new` or `/resume`. |
+| `session_before_fork` | Yes | Before `/fork` or `/clone`; includes `position: "before" | "at"`. |
+| `session_before_compact` | Yes/custom | Cancel or provide a custom compaction result. |
+| `session_compact` | No | After compaction. |
+| `session_before_tree` | Yes/custom | Before `/tree` navigation. |
+| `session_tree` | No | After `/tree` navigation. |
+| `session_shutdown` | No | Runtime teardown for quit, reload, new, resume, or fork. |
 
-### Blocking Tool Calls
+After a session replacement, the old runtime is torn down and extensions are rebound. Use `session_shutdown` for cleanup and `session_start` to rebuild in-memory state.
 
 ```typescript
-pi.on("tool_call", async (event, ctx) => {
-  if (event.toolName === "bash" && event.input.command.includes("rm -rf /")) {
-    // Check ctx.hasUI before prompting -- see references/modes.md
-    if (!ctx.hasUI) {
-      return { block: true, reason: "Blocked: dangerous command (no UI to confirm)" };
-    }
-
-    const confirmed = await ctx.ui.confirm(
-      "Dangerous Command",
-      `Allow: ${event.input.command}?`
-    );
-    if (!confirmed) {
-      return { block: true, reason: "Blocked by user" };
-    }
-  }
-  return undefined; // Allow the tool call
+pi.on("session_before_switch", async (event, ctx) => {
+  if (event.reason !== "new") return;
+  if (!ctx.hasUI) return { cancel: true };
+
+  const confirmed = await ctx.ui.confirm("Clear session?", "All messages will be lost.");
+  if (!confirmed) return { cancel: true };
 });
 ```
 
-### Cancelling Session Operations
+## Agent and Message Events
+
+| Event | Purpose |
+|---|---|
+| `before_agent_start` | Inject a message or replace the system prompt for this turn. |
+| `agent_start` / `agent_end` | Whole prompt lifecycle. |
+| `turn_start` / `turn_end` | One provider response plus tool batch. |
+| `context` | Modify copied messages before a provider call. |
+| `message_start` / `message_update` / `message_end` | Observe or replace messages. |
+| `before_provider_request` | Inspect/replace provider-specific payload. |
+| `after_provider_response` | Inspect response status/headers before stream consumption. |
+| `model_select` | Model changed. |
+| `thinking_level_select` | Thinking level changed. |
+
+### `before_agent_start`
+
+Use this for system prompt changes that depend on dynamic context. Per-tool `promptSnippet` and `promptGuidelines` are preferred for simple tool-local guidance.
 
 ```typescript
-pi.on("session_before_switch", async (event, ctx) => {
-  if (event.reason === "new" && ctx.hasUI) {
-    const confirmed = await ctx.ui.confirm("Clear session?", "All messages will be lost.");
-    if (!confirmed) {
-      return { cancel: true };
-    }
-  }
+pi.on("before_agent_start", async (event) => {
+  return {
+    systemPrompt: `${event.systemPrompt}\n\nExtra instructions for this turn.`,
+  };
 });
 ```
 
-### Custom Compaction
+`event.systemPromptOptions` exposes structured prompt inputs such as selected tools, tool snippets, prompt guidelines, context files, and loaded skills. `ctx.getSystemPrompt()` reflects changes made by earlier `before_agent_start` handlers in the chain.
+
+### `message_end`
+
+`message_end` handlers can replace a finalized message. Keep the same role.
 
 ```typescript
-pi.on("session_before_compact", async (event, ctx) => {
+pi.on("message_end", async (event) => {
+  if (event.message.role !== "assistant") return;
   return {
-    compaction: {
-      summary: "Custom summary",
-      firstKeptEntryId: event.preparation.firstKeptEntryId,
-      tokensBefore: event.preparation.tokensBefore,
+    message: {
+      ...event.message,
+      usage: {
+        ...event.message.usage,
+        cost: { ...event.message.usage.cost, total: 0 },
+      },
     },
   };
 });
 ```
 
-## Transforming Input
+## Tool Events
+
+| Event | Can block/modify | Notes |
+|---|---:|---|
+| `tool_execution_start` | No | Tool started. |
+| `tool_call` | Block/mutate input | Runs before tool execution. |
+| `tool_execution_update` | No | Partial result update. |
+| `tool_result` | Modify result | Runs after tool execution, before final events. |
+| `tool_execution_end` | No | Tool completed. |
+
+Tool calls from one assistant message are preflighted sequentially, then run concurrently by default. Do not assume sibling tool results are visible inside `tool_call`.
+
+### Blocking tool calls
+
+Use `isToolCallEventType` for typed built-in inputs.
 
 ```typescript
-pi.on("input", async (event, ctx) => {
-  if (event.text.startsWith("!")) {
-    return event.text.slice(1).toUpperCase();
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+
+pi.on("tool_call", async (event, ctx) => {
+  if (!isToolCallEventType("bash", event)) return;
+
+  if (!event.input.command.includes("rm -rf")) return;
+
+  if (!ctx.hasUI) {
+    return { block: true, reason: "Dangerous command blocked because no UI is available." };
   }
-  return undefined; // No transformation
+
+  const confirmed = await ctx.ui.confirm("Dangerous command", `Allow ${event.input.command}?`);
+  if (!confirmed) return { block: true, reason: "Blocked by user" };
 });
 ```
 
-## Modifying Bash Commands
+`event.input` is mutable. Mutating it changes the arguments passed to the tool. Pi does not revalidate after your mutation.
+
+### Typing custom tool input
+
+Export your custom tool input type and use explicit type params with `isToolCallEventType`.
+
+```typescript
+if (isToolCallEventType<"my_tool", MyToolParams>("my_tool", event)) {
+  event.input.action;
+}
+```
+
+### Modifying tool results
 
 ```typescript
-pi.on("user_bash", async (event, ctx) => {
+pi.on("tool_result", async (event, ctx) => {
+  if (event.toolName !== "bash") return;
+
+  const response = await fetch("https://example.com/summarize", {
+    method: "POST",
+    body: JSON.stringify({ content: event.content }),
+    signal: ctx.signal,
+  });
+
+  const summary = await response.text();
   return {
-    command: event.command,
-    cwd: "/sandboxed/directory",
-    env: { ...process.env, SANDBOX: "true" },
+    content: [...event.content, { type: "text", text: `\nSummary: ${summary}` }],
   };
 });
 ```
 
-## before_agent_start
+`tool_result` handlers chain like middleware. Return partial patches (`content`, `details`, `isError`) and omit fields that should stay unchanged.
 
-This event fires before each agent turn. It is commonly used to modify the system prompt.
+## Input Events
 
-The handler receives a `BeforeAgentStartEvent` with `systemPrompt` and `systemPromptOptions` fields. `systemPromptOptions` exposes the structured inputs used to build the prompt. Return a `{ systemPrompt }` object to replace it. If multiple extensions return a modified prompt, they are chained. `ctx.getSystemPrompt()` reflects changes made by earlier `before_agent_start` handlers.
+`input` fires after extension command checks and before skill/template expansion. Return an action object.
 
 ```typescript
-pi.on("before_agent_start", async (event) => {
-  return {
-    systemPrompt: event.systemPrompt + "\n\nAlways respond as a pirate.",
-  };
+pi.on("input", async (event) => {
+  if (event.source === "extension") return { action: "continue" };
+
+  if (event.text.startsWith("?quick ")) {
+    return {
+      action: "transform",
+      text: `Respond briefly: ${event.text.slice(7)}`,
+      images: event.images,
+    };
+  }
+
+  if (event.text === "ping") {
+    return { action: "handled" };
+  }
+
+  return { action: "continue" };
 });
 ```
 
-Return `undefined` to leave the prompt unchanged.
+Actions:
 
-The system prompt is reset each turn, so modifications in `before_agent_start` are not cumulative.
+- `continue`: keep processing.
+- `transform`: replace text/images, then continue.
+- `handled`: stop; the extension handled the input.
 
-To access flags inside hooks, use `pi.getFlag()` (see `references/additional-apis.md`).
+Transforms chain across handlers. The first `handled` wins.
+
+## User Bash Events
+
+`user_bash` fires for user `!` and `!!` commands. It is separate from LLM bash tool calls.
+
+Use it to provide custom bash operations or a direct result.
+
+```typescript
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+
+pi.on("user_bash", (event) => {
+  const local = createLocalBashOperations();
+  return {
+    operations: {
+      exec(command, cwd, options) {
+        return local.exec(`source ~/.profile\n${command}`, cwd, options);
+      },
+    },
+  };
+});
+```
 
-## Bash Spawn Hook (Command Rewriting)
+For transparent LLM bash tool rewriting, use a bash spawn hook instead.
 
-The `createBashTool(cwd, options)` function lets you replace the built-in bash tool with one that transparently rewrites commands before shell execution. Always pass an explicit cwd. This is different from `tool_call` blocking -- the agent never sees that the command was rewritten.
+## Bash Spawn Hook
 
-Use spawn hooks when you have a clear rewrite target (e.g. `npm` -> `pnpm`). Use `tool_call` blocking when you need to stop a command entirely or show a confirmation dialog.
+`createBashTool(cwd, { spawnHook })` creates a bash tool that rewrites command/cwd/env before execution. Registering a tool named `bash` overrides the built-in bash tool.
 
 ```typescript
-import { createBashTool, type BashSpawnHook, type BashSpawnContext } from "@mariozechner/pi-coding-agent";
+import { createBashTool, type BashSpawnContext } from "@earendil-works/pi-coding-agent";
 
-export default function (pi: ExtensionAPI) {
+export default function hooksExtension(pi: ExtensionAPI) {
   const bashTool = createBashTool(process.cwd(), {
     spawnHook: ({ command, cwd, env }: BashSpawnContext): BashSpawnContext => ({
       command: command.replace(/^npm /, "pnpm "),
       cwd,
-      env: { ...env, CUSTOM_VAR: "1" },
+      env: { ...env, CI: "1" },
     }),
   });
 
@@ -171,77 +266,55 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-### BashSpawnContext
-
-The spawn hook receives and returns a `BashSpawnContext`:
+Use spawn hooks for clear rewrites or env injection. Use `tool_call` blocking for safety gates and confirmation dialogs.
 
-```typescript
-interface BashSpawnContext {
-  command: string;        // The shell command to execute
-  cwd: string;            // Working directory
-  env: NodeJS.ProcessEnv; // Environment variables
-}
-```
+Key points:
 
-You can modify any of these fields. The hook runs after pi's own processing but before the shell spawns.
+- Prompt metadata is not inherited when overriding built-ins. Re-declare `promptSnippet`/`promptGuidelines` if needed.
+- Tool-call blockers run before the spawn hook.
+- Prefer parsed shell rewrites over broad regex replacements.
 
-### Key Points
+## Provider Request Hooks
 
-- **Replaces the built-in bash tool.** When you call `pi.registerTool()` with a tool named `"bash"`, it replaces the default. Only one extension should do this.
-- **Transparent to the agent.** The agent sees the original command in the tool call UI but gets the output of the rewritten command.
-- **Execution order with tool_call hooks.** `tool_call` event hooks (blockers) run first. If a blocker returns `{ block: true }`, the spawn hook never fires. This means you can combine blocking hooks for commands that should be stopped entirely with spawn hooks for commands that should be rewritten.
-- **Prefer AST-based rewrites over regex.** A false positive rewrite corrupts a command silently. Use `@aliou/sh` or similar shell parsers to identify command names in the AST, then do surgical string replacement at the identified positions. If the parse fails, return the command unchanged.
-- **Compose multiple rewriters.** Chain rewriter functions that each transform the context:
+Use these for debugging serialization, proxies, or cache behavior.
 
 ```typescript
-const rewriters: ((ctx: BashSpawnContext) => BashSpawnContext)[] = [
-  createPackageManagerRewriter(config),
-  createGitRebaseRewriter(),
-];
-
-const spawnHook = (ctx: BashSpawnContext) => {
-  let result = ctx;
-  for (const rewrite of rewriters) {
-    result = rewrite(result);
-  }
-  return result;
-};
+pi.on("before_provider_request", (event) => {
+  console.log(JSON.stringify(event.payload, null, 2));
+  // return { ...event.payload, temperature: 0 };
+});
 
-const bashTool = createBashTool(process.cwd(), { spawnHook });
-pi.registerTool({ ...bashTool });
+pi.on("after_provider_response", (event) => {
+  if (event.status === 429) {
+    console.log("rate limited", event.headers["retry-after"]);
+  }
+});
 ```
 
-### When to Use What
+Payload-level rewrites are provider-specific and are not reflected by `ctx.getSystemPrompt()`.
 
-| Pattern | Use When | Agent Sees |
-|---|---|---|
-| `tool_call` hook + `{ block: true }` | Command must be stopped entirely | Block reason (retries with correct command) |
-| `tool_call` hook + `ctx.ui.confirm()` | User confirmation needed | Block reason if denied |
-| Spawn hook (command rewrite) | Clear 1:1 rewrite target exists | Output of rewritten command (transparent) |
-| Spawn hook (env injection) | Need to set env vars for specific commands | Output with injected env (transparent) |
+## Mode Awareness
 
-## Multiple Handlers
-
-Multiple extensions can register handlers for the same event. They execute in registration order. For blocking events (`tool_call`, `session_before_switch`, etc.), the first handler to return a blocking/cancelling result wins.
-
-## Mode Awareness in Hooks
-
-Always consider what happens in Print mode when your hook uses dialog methods. See `references/modes.md` for the full behavior matrix.
-
-Common pattern for `tool_call` handlers:
+Dialog methods that gate behavior need a safe no-UI default. Fire-and-forget methods are safe without guards.
 
 ```typescript
 pi.on("tool_call", async (event, ctx) => {
-  if (shouldBlock(event)) {
-    if (!ctx.hasUI) {
-      return { block: true, reason: "No UI to confirm" };
-    }
-    // Safe to use dialogs here
-    const choice = await ctx.ui.select("Allow?", ["Yes", "No"]);
-    if (choice !== "Yes") {
-      return { block: true, reason: "Blocked by user" };
-    }
-  }
-  return undefined;
+  if (!shouldConfirm(event)) return;
+  if (!ctx.hasUI) return { block: true, reason: "No UI to confirm" };
+
+  const choice = await ctx.ui.select("Allow?", ["Allow", "Block"]);
+  if (choice !== "Allow") return { block: true, reason: "Blocked" };
 });
 ```
+
+Read `references/modes.md` before adding UI to hooks.
+
+## Checklist
+
+- [ ] Event return shape matches current Pi docs.
+- [ ] Blocking hooks have safe defaults when `ctx.hasUI` is false.
+- [ ] `input` hooks return `{ action: ... }`, not raw strings.
+- [ ] `before_agent_start` returns `{ systemPrompt }`; it does not call `ctx.setSystemPrompt()`.
+- [ ] Nested async work uses `ctx.signal` when available.
+- [ ] Session replacement cleanup/rebuild is split between `session_shutdown` and `session_start`.
+- [ ] Built-in tool overrides re-declare prompt metadata if needed.