@code-yeongyu/senpi 2026.6.21 → 2026.6.30-2

package/docs/extensions.md

@@ -38,6 +38,11 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
 - [Events](#events)
   - [Lifecycle Overview](#lifecycle-overview)
   - [Resource Events](#resource-events)
+  - [Builtin Hooks](#builtin-hooks)
+    - [Hook setup workflow](#hook-setup-workflow)
+    - [Hook input and output](#hook-input-and-output)
+    - [Common hook recipes](#common-hook-recipes)
+    - [Hook troubleshooting](#hook-troubleshooting)
   - [Session Events](#session-events)
   - [Agent Events](#agent-events)
   - [Model Events](#model-events)
@@ -322,6 +327,9 @@ user sends another prompt ◄─────────────────
   ├─► session_start { reason: "fork", previousSessionFile }
   └─► resources_discover { reason: "startup" }
 
+/name or pi.setSessionName()
+  └─► session_info_changed
+
 /compact or auto-compaction
   ├─► session_before_compact (can cancel or customize)
   └─► session_compact
@@ -379,6 +387,451 @@ pi.on("resources_discover", async (event, _ctx) => {
 });
 ```
 
+### Builtin Hooks
+
+The builtin `hooks` extension runs trusted command hooks from JSON config files. It is intended for local guardrails and migration from Claude-style command hooks, while keeping the extension API as the primary senpi customization surface.
+
+Default senpi hook files are discovered from:
+
+| Source | Timing | Notes |
+|--------|--------|-------|
+| `~/.senpi/agent/hooks.json` | pre-session | Global hook config. |
+| Global package `pi.hooks` or `hooks/*.json` | pre-session | Package hook config loaded after the global hook file. |
+| `.senpi/hooks.json` | pre-session | Project hook config, loaded after project trust. |
+| Project package `pi.hooks` or `hooks/*.json` | pre-session | Package hook config loaded after the project hook file. |
+| Temporary package sources and SDK/host-provided `new DefaultResourceLoader({ additionalHookPaths })` | pre-session | Package/plugin hook JSON files resolved before `session_start`. |
+| `resources_discover` `hookPaths` | runtime | Late sources. They can affect later hook events in the current runtime and `SessionStart` on `/reload` or the next session. |
+
+#### Hook setup workflow
+
+Use builtin hooks when you already have Claude/Codex-style JSON hook configs or when you want a small shell-script guardrail. Use a TypeScript extension instead when the behavior needs rich senpi APIs, UI prompts, custom tools, long-lived state, or non-command handlers.
+
+For a project-local hook:
+
+1. Create `.senpi/hooks.json`.
+2. Put command scripts under `.senpi/hooks/` or another project path.
+3. Start `senpi` in that project.
+4. Run `/hooks list` and copy the real hook id.
+5. Run `/hooks trust <id>` once for each command hook you want to execute.
+6. Trigger the event, then use `/hooks diagnostics` if it did not run.
+
+For a global hook, use `~/.senpi/agent/hooks.json` and a stable global script path. For team-shared hooks, prefer a senpi package or plugin manifest so the scripts and hook JSON move together.
+
+Trust is tied to the command hook's canonical hash. Changing the command text, `commandWindows`, timeout, matcher, or status message makes the hook untrusted again until you review and trust the new hash. Disabling a hook with `/hooks disable <id>` keeps the trust entry but skips execution; `/hooks enable <id>` re-enables it.
+
+Recommended first check after adding a hook:
+
+```text
+/hooks list
+/hooks diagnostics
+```
+
+`/hooks list` should show the source, matcher, trust state, disabled state, and redacted command preview. `/hooks diagnostics` should be empty or contain only diagnostics you intentionally accept.
+
+#### Minimal project hook
+
+Create `.senpi/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .senpi/hooks/log-pretool.mjs",
+            "timeout": 10,
+            "statusMessage": "Checking bash command"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Create `.senpi/hooks/log-pretool.mjs`:
+
+```javascript
+let stdin = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  stdin += chunk;
+});
+process.stdin.on("end", () => {
+  const input = JSON.parse(stdin);
+  const toolInput = input.toolInput ?? input.tool_input ?? {};
+  const command = String(toolInput.command ?? "");
+  if (command.includes("rm -rf")) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: "Refusing destructive shell command"
+      }
+    }));
+    return;
+  }
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow"
+    }
+  }));
+});
+```
+
+Start senpi in the project and inspect hooks:
+
+```bash
+senpi
+/hooks list
+/hooks trust hk_example_PreToolUse_0_0
+```
+
+The real hook id is shown by `/hooks list`. A command hook must be trusted before it runs. Project hook trust is writable only when the project is trusted.
+
+Exact command grammar:
+
+```text
+Usage: /hooks [list|diagnostics|trust <id>|disable <id>|enable <id>|reload]
+```
+
+`/hooks list` shows executable hooks, ids, trust state, disabled state, matcher, status message, and a redacted command preview. `/hooks diagnostics` shows malformed, unsupported, untrusted, and skipped hook details. `/hooks reload` runs the normal extension/resource reload flow.
+
+#### Command handler JSON
+
+Only command handlers are executable in builtin hooks v1:
+
+```json
+{
+  "type": "command",
+  "command": "node ./hooks/check.mjs",
+  "commandWindows": "node .\\hooks\\check.mjs",
+  "timeout": 30,
+  "statusMessage": "Running hook"
+}
+```
+
+`command` is required and runs through the host shell with the hook input JSON on stdin. `commandWindows` or `command_windows` can override the command on Windows. `timeout` is seconds and defaults to 600. `statusMessage` is display text only.
+
+Hook commands inherit a minimal environment (`PATH`, home/user/shell/temp variables, and Windows shell basics). Hooks loaded through the plugin manifest helper also receive `PLUGIN_ROOT`, `PLUGIN_DATA`, `CLAUDE_PLUGIN_ROOT`, and `CLAUDE_PLUGIN_DATA`. Every command receives `SENPI_HOOK_SOURCE` and `SENPI_HOOK_EVENT`. Do not put API keys or tokens in hook config, command text, status messages, stdout, stderr, or diagnostics. Read secrets inside the command from your own secret store and avoid echoing them.
+
+#### Event map
+
+| Event | senpi source | Supported behavior |
+|-------|--------------|--------------------|
+| `SessionStart` | `session_start` | Runs on startup/reload/new/resume/fork. `additionalContext` is recorded as hidden hook context. Decisions are diagnostics only. |
+| `UserPromptSubmit` | `input` plus `before_agent_start` | Can block the prompt. `additionalContext` is injected as hidden context for the turn. `systemMessage` appends to the turn system prompt. |
+| `PreToolUse` | `tool_call` | Can deny/block, ask (represented as block), allow/approve, mutate `updatedInput` only with `permissionDecision: "allow"`, and add context for the matching tool result. |
+| `PostToolUse` | `tool_result` | Can block by replacing the tool result with an error, replace tool output with `updatedToolOutput`, and append `additionalContext`. |
+| `PreCompact` | `session_before_compact` | Can block/cancel compaction with `decision: "block"` or exit code 2. `additionalContext` and `customInstructions` are diagnostic-only. |
+| `PostCompact` | `session_compact` | Runs after accepted compactions. Output fields are currently diagnostic-only. |
+| `Stop` | `agent_end` | Can block by sending a follow-up prompt from `additionalContext` or `reason`. Reentry is capped at eight blocks per turn. |
+
+Matchers are strings. For tool events, matchers match tool names. For lifecycle events, `*`, event names, reasons such as `startup`, `reload`, `manual`, or `overflow`, comma/pipe-separated literals, and JavaScript regular expressions are supported.
+
+Command stdout may be empty or JSON. Universal JSON fields include `decision`, `reason`, `additionalContext`, `continue`, `stopReason`, `suppressOutput`, `systemMessage`, and `hookSpecificOutput`. `hookSpecificOutput.hookEventName` must match the current event when present. Exit code `2` is treated as a block decision with stderr as the reason.
+
+#### Hook input and output
+
+Every command receives one JSON object on stdin. The object always includes `event` and `cwd`, and includes session/transcript fields when senpi has them:
+
+| Field | Meaning |
+|-------|---------|
+| `event` | Hook event name, such as `PreToolUse` or `UserPromptSubmit`. |
+| `cwd` | Current project working directory. |
+| `session_id` | Session id when available. |
+| `transcript_path` | Session transcript path when available. |
+
+Tool events include both senpi-style camelCase and Claude-compatible snake_case fields:
+
+```json
+{
+  "event": "PreToolUse",
+  "toolName": "bash",
+  "toolInput": { "command": "npm test" },
+  "tool_name": "bash",
+  "tool_input": { "command": "npm test" },
+  "cwd": "/repo"
+}
+```
+
+Prompt hooks receive the raw prompt:
+
+```json
+{
+  "event": "UserPromptSubmit",
+  "prompt": "summarize this repo",
+  "cwd": "/repo"
+}
+```
+
+Output must be valid JSON if you want senpi to apply a decision. Empty stdout means no decision. Prefer event-specific output inside `hookSpecificOutput`:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Do not run destructive commands"
+  }
+}
+```
+
+`PreToolUse` supports `permissionDecision: "allow" | "deny" | "ask"`. `updatedInput` is applied only when `permissionDecision` is `"allow"`. `additionalContext` is saved as hidden context for the active tool result.
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "updatedInput": { "command": "npm test -- --runInBand" },
+    "additionalContext": "The hook serialized this test command."
+  }
+}
+```
+
+`UserPromptSubmit` can block or add context, but it cannot replace the prompt through Claude/Codex-compatible fields:
+
+```json
+{
+  "decision": "block",
+  "reason": "Please include an issue number before starting release work."
+}
+```
+
+`PostToolUse` can replace visible tool output with `updatedToolOutput` and can add `additionalContext`:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "updatedToolOutput": "Output redacted by local hook.",
+    "additionalContext": "The raw tool output was replaced because it matched the secret scanner."
+  }
+}
+```
+
+`Stop` can ask senpi to continue with a follow-up prompt by returning `decision: "block"` plus `additionalContext` or `reason`. senpi caps repeated Stop follow-ups at eight per turn to prevent loops.
+
+#### Common hook recipes
+
+Block dangerous shell commands:
+
+```javascript
+let stdin = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  stdin += chunk;
+});
+process.stdin.on("end", () => {
+  const input = JSON.parse(stdin);
+  const toolInput = input.toolInput ?? input.tool_input ?? {};
+  const command = String(toolInput.command ?? "");
+
+  if (/\brm\s+-rf\b/.test(command)) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: "Blocked rm -rf"
+      }
+    }));
+  }
+});
+```
+
+Add per-prompt project context:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .senpi/hooks/prompt-context.mjs",
+            "statusMessage": "Loading prompt context"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+```javascript
+process.stdin.resume();
+process.stdin.on("end", () => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: "Prefer the repository's AGENTS.md rules over generic defaults."
+    }
+  }));
+});
+```
+
+Stop when a final answer needs a required follow-up:
+
+```javascript
+process.stdin.resume();
+process.stdin.on("end", () => {
+  process.stdout.write(JSON.stringify({
+    decision: "block",
+    hookSpecificOutput: {
+      hookEventName: "Stop",
+      additionalContext: "Before finishing, run the focused regression test and summarize the result."
+    }
+  }));
+});
+```
+
+Distribute hooks from a package:
+
+```json
+{
+  "name": "team-senpi-hooks",
+  "pi": {
+    "hooks": ["./hooks/pretool.json"]
+  }
+}
+```
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "bash|edit|write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./hooks/check.mjs",
+            "statusMessage": "Running team hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Package hook paths are resolved relative to the package root. If you need plugin-root environment variables, use a `.codex-plugin/plugin.json` manifest and `${PLUGIN_ROOT}` in the command.
+
+#### Plugin hooks
+
+Plugin hook manifests are package integration inputs. Installed senpi packages can expose hook JSON files through `package.json` under `pi.hooks` or by placing JSON files under `hooks/`; those sources are discovered before `session_start` in global, project, or temporary package scope.
+
+Plugin hook manifests live at `.codex-plugin/plugin.json` under the plugin root. A manifest can point to hook JSON files:
+
+```json
+{
+  "name": "example-hooks-plugin",
+  "hooks": "./hooks/pretool.json"
+}
+```
+
+It can also inline hook config directly:
+
+```json
+{
+  "name": "inline-hooks-plugin",
+  "hooks": {
+    "hooks": {
+      "SessionStart": [
+        {
+          "matcher": "startup|reload",
+          "hooks": [
+            {
+              "type": "command",
+              "command": "node ${PLUGIN_ROOT}/hooks/session-start.mjs"
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+`hooks` may also be an array mixing paths, nested arrays, and inline hook objects. Hook paths must stay inside the plugin root. The manifest helper also understands a plugin default hook file at `hooks/hooks.json` unless the host disables default plugin hooks. Plugin commands that reference `${PLUGIN_ROOT}`, `$PLUGIN_ROOT`, or `%PLUGIN_ROOT%` must resolve to existing files inside the plugin root.
+
+SDK hosts can still provide explicit pre-session hook sources:
+
+```typescript
+const loader = new DefaultResourceLoader({
+  cwd,
+  agentDir,
+  additionalHookPaths: ["/absolute/path/to/package-hooks.json"],
+});
+```
+
+Pre-session sources are visible to `SessionStart` on initial startup.
+
+#### Runtime hook sources
+
+Extensions can return late hook paths from `resources_discover`:
+
+```typescript
+import { join } from "node:path";
+import type { ExtensionAPI } from "@code-yeongyu/senpi";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("resources_discover", (event, ctx) => {
+    if (event.reason !== "reload") return {};
+    return {
+      hookPaths: [join(ctx.cwd, ".senpi", "generated-hooks.json")],
+    };
+  });
+}
+```
+
+These paths are runtime sources. They can affect later hook events in the current runtime, but their `SessionStart` hooks do not run for the already-started initial session. On `/hooks reload` or `/reload`, runtime `SessionStart` hooks are visible to the reloaded session. If a runtime source contains `SessionStart`, senpi records a diagnostic: `Runtime SessionStart hooks are loaded for reload or the next session only.`
+
+#### Not yet supported
+
+The builtin hooks implementation intentionally does not claim full Claude hook coverage. Unsupported shapes produce warnings or diagnostics and are not executed.
+
+| Area | Not yet supported |
+|------|-------------------|
+| Events | `PermissionRequest`, `PermissionDenied`, `SubagentStart`, `SubagentStop`, `Notification`, `Setup`, `UserPromptExpansion`, `PostToolUseFailure`, `PostToolBatch`, `TaskCreated`, `TaskCompleted`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay`, `SessionEnd`, `Elicitation`, `ElicitationResult`. |
+| Handler types | `prompt`, `agent`, `http`, and `mcp_tool`. |
+| Command forms | Exec-form commands, object-valued `command`, separate `args`, `shell`, and command handlers with `async: true`. |
+| Command fields | `if`, `asyncRewake`, `terminalSequence`, and `continueOnBlock`. |
+| Prompt mutation | UserPromptSubmit prompt replacement fields such as `prompt`, `updatedPrompt`, and `replacementPrompt`. |
+| Async behavior | Claude-style async hooks and `asyncRewake`. |
+| PreCompact mutation | `customInstructions` does not change compaction in builtin hooks v1. |
+
+#### omo-codex migration notes
+
+For omo-codex or Claude-style hook configs, migrate the lowest-risk checks first:
+
+- Keep existing `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `PreCompact`, `PostCompact`, and `Stop` command hooks if they use shell command strings.
+- Move `http`, `mcp_tool`, `prompt`, and `agent` hooks to senpi extensions or tools.
+- Replace `if` conditions with logic inside the command script or with matcher strings for tool/lifecycle selection.
+- Treat `Notification`, subagent/task/teammate/worktree events, and prompt replacement as deferred; document them in plugin README files instead of assuming execution.
+- When the host uses the plugin manifest helper, use `PLUGIN_ROOT` and `PLUGIN_DATA` for plugin-relative scripts and state. Keep secrets out of manifests and hook JSON.
+
+#### Hook troubleshooting
+
+If a hook does not run:
+
+1. Run `/hooks list` and confirm the hook is present, enabled, and trusted.
+2. Run `/hooks diagnostics` and check for malformed JSON, unsupported fields, untrusted hashes, skipped runtime `SessionStart`, or plugin containment errors.
+3. Confirm the matcher matches the event. Tool events match tool names such as `bash`, `edit`, `write`, `Bash`, `Edit`, and `Write`; lifecycle events match reasons such as `startup`, `reload`, `manual`, and `overflow`.
+4. Confirm the command path works from the project cwd. For plugin commands using `${PLUGIN_ROOT}`, the resolved file must exist inside the plugin root.
+5. Keep stdout as valid JSON or empty. Human-readable logs should go to stderr, and secret-bearing logs should be avoided entirely.
+6. After editing hook JSON or scripts, run `/hooks reload`, then `/hooks list` again. If the trusted hash changed, trust the hook again.
+
+If a hook runs but has no effect, check the event support table. Some fields are diagnostic-only by design, such as `PreCompact` `additionalContext` and `customInstructions`, `PostCompact` output fields, and unsupported prompt replacement fields for `UserPromptSubmit`.
+
+If a hook times out, increase `timeout` in seconds or make the script observe stdin and exit quickly. The default timeout is 600 seconds. Invalid timeout values such as `0`, negative numbers, `NaN`, or infinity are rejected and the command is not started.
+
 ### Session Events
 
 See [Session Format](session-format.md) for session storage internals and the SessionManager API.
@@ -395,6 +848,17 @@ pi.on("session_start", async (event, ctx) => {
 });
 ```
 
+#### session_info_changed
+
+Fired when the current session display name is set via `/name`, RPC, or `pi.setSessionName()`.
+
+```typescript
+pi.on("session_info_changed", async (event, ctx) => {
+  // event.name - current normalized name, or undefined if cleared
+  ctx.ui.notify(`Session renamed: ${event.name ?? "(none)"}`, "info");
+});
+```
+
 #### session_before_switch
 
 Fired before starting a new session (`/new`) or switching sessions (`/resume`).
@@ -437,7 +901,10 @@ Fired on compaction. See [compaction.md](compaction.md) for details.
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, signal } = event;
+  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
+
+  // reason - "manual" (/compact), "threshold", or "overflow"
+  // willRetry - whether the aborted turn is retried after compaction (overflow recovery)
 
   // Cancel:
   return { cancel: true };
@@ -455,6 +922,8 @@ pi.on("session_before_compact", async (event, ctx) => {
 pi.on("session_compact", async (event, ctx) => {
   // event.compactionEntry - the saved compaction
   // event.fromExtension - whether extension provided it
+  // event.reason - "manual" (/compact), "threshold", or "overflow"
+  // event.willRetry - whether the aborted turn is retried after compaction (overflow recovery)
 });
 ```
 

package/docs/index.md

@@ -43,7 +43,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 
 ## Customization
 
-- [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
+- [Extensions](extensions.md) - TypeScript modules for tools, commands, events, custom UI, and builtin command hooks.
 - [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
 - [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
 - [Themes](themes.md) - built-in and custom terminal themes.

package/docs/keybindings.md

@@ -54,7 +54,7 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
 
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
-| `tui.input.newLine` | `shift+enter` | Insert new line |
+| `tui.input.newLine` | `shift+enter`, `ctrl+j` | Insert new line |
 | `tui.input.submit` | `enter` | Submit input |
 | `tui.input.tab` | `tab` | Tab / autocomplete |
 
@@ -86,7 +86,7 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
 | `app.clear` | `ctrl+c` | Clear editor |
 | `app.exit` | `ctrl+d` | Exit (when editor empty) |
 | `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
-| `app.editor.external` | `ctrl+g` | Open in external editor (`$VISUAL` or `$EDITOR`) |
+| `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
 | `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image from clipboard |
 | `app.history.search` | `ctrl+r` | Search prompt history across sessions |
 | `app.sessions.observe` | `ctrl+s` | Observe session transcripts |

package/docs/models.md

@@ -34,7 +34,7 @@ For local models (Ollama, LM Studio, vLLM), only `id` is required per model:
 }
 ```
 
-The `apiKey` is required but Ollama ignores it, so any value works.
+The `apiKey` value is a placeholder because Ollama ignores it. pi still treats models as requiring auth before they appear in `/model`, so keyless local servers should keep a dummy value, save a key for that provider with `/login`, or pass `--api-key` when selecting the model.
 
 Some OpenAI-compatible servers do not understand the `developer` role used for reasoning-capable models. For those providers, set `compat.supportsDeveloperRole` to `false` so senpi sends the system prompt as a `system` message instead. If the server also does not support `reasoning_effort`, set `compat.supportsReasoningEffort` to `false` too.
 
@@ -135,12 +135,14 @@ Set `api` at provider level (default for all models) or model level (override pe
 |-------|-------------|
 | `baseUrl` | API endpoint URL |
 | `api` | API type (see above) |
-| `apiKey` | API key (see value resolution below) |
+| `apiKey` | Optional API key config (see value resolution below). Omit it when auth is provided by `/login`/`auth.json` or CLI `--api-key`. |
 | `headers` | Custom headers (see value resolution below) |
 | `authHeader` | Set `true` to add `Authorization: Bearer <apiKey>` automatically |
 | `models` | Array of model configurations |
 | `modelOverrides` | Per-model overrides for built-in models on this provider |
 
+For providers with `models`, non-built-in provider configs need `baseUrl` and an `api` value at either provider or model level. `apiKey` is not required to load the file: models become available when auth is configured through `/login`/`auth.json`, CLI `--api-key`, or provider `apiKey`. If no auth is configured, the models load but stay unavailable in `/model` and `--list-models`.
+
 ### Value Resolution
 
 The `apiKey` and `headers` fields support command execution, environment interpolation, and literals:

package/docs/packages.md

@@ -1,8 +1,8 @@
-> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
+> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, themes, or hook configs.
 
 # Pi Packages
 
-Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories.
+Pi packages bundle extensions, skills, prompt templates, themes, and hook configs so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories.
 
 ## Table of Contents
 
@@ -124,7 +124,8 @@ Add a `pi` manifest to `package.json` or use conventional directories. Include t
     "extensions": ["./extensions"],
     "skills": ["./skills"],
     "prompts": ["./prompts"],
-    "themes": ["./themes"]
+    "themes": ["./themes"],
+    "hooks": ["./hooks"]
   }
 }
 ```
@@ -162,10 +163,11 @@ If no `pi` manifest is present, pi auto-discovers resources from these directori
 - `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
 - `prompts/` loads `.md` files
 - `themes/` loads `.json` files
+- `hooks/` loads `.json` files
 
 ## Dependencies
 
-Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When pi installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, themes, or hook configs also belong in `dependencies`. When pi installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
 
 Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`.
 
@@ -199,7 +201,8 @@ Filter what a package loads using the object form in settings:
       "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
       "skills": [],
       "prompts": ["prompts/review.md"],
-      "themes": ["+themes/legacy.json"]
+      "themes": ["+themes/legacy.json"],
+      "hooks": ["hooks/pretool.json"]
     }
   ]
 }
@@ -216,7 +219,7 @@ Filter what a package loads using the object form in settings:
 
 ## Enable and Disable Resources
 
-Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.
+Use `pi config` to enable or disable extensions, skills, prompt templates, themes, and hook configs from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.
 
 ## Scope and Deduplication
 

package/docs/providers.md

@@ -63,7 +63,7 @@ senpi
 | xAI | `XAI_API_KEY` | `xai` |
 | OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
 | Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
-| ZAI | `ZAI_API_KEY` | `zai` |
+| ZAI Coding Plan (Global) | `ZAI_API_KEY` | `zai` |
 | ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` | `zai-coding-cn` |
 | OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
 | OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
@@ -156,8 +156,9 @@ OAuth credentials are also stored here after `/login` and managed automatically.
 
 ```bash
 export AZURE_OPENAI_API_KEY=...
-export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
+export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
 # also supported: https://your-resource.cognitiveservices.azure.com
+# also supported: https://your-resource.openai.azure.com
 # root endpoints are auto-normalized to /openai/v1
 # or use resource name instead of base URL
 export AZURE_OPENAI_RESOURCE_NAME=your-resource