pi-rnd 0.2.1

package/docs/PI-API.md

@@ -0,0 +1,574 @@
+# PI Extension API Reference
+
+> Citation format: `(file:line-range)` — paths abbreviated as `pi-agent/` for
+> `@earendil-works/pi-coding-agent/dist/core/` and `pi-sub/` for
+> `@tintinweb/pi-subagents/src/`.
+
+---
+
+## 1. PI Runtime API (ExtensionAPI)
+
+Extensions export a default factory function `(pi: ExtensionAPI) => void | Promise<void>`
+(`pi-agent/extensions/types.d.ts:983`). PI awaits the factory before firing `session_start`.
+Extensions load via **jiti** — TypeScript works without a compile step.
+
+**Auto-discovery locations** (`pi-agent/` docs/extensions.md:7):
+
+- `~/.pi/agent/extensions/*.ts` or `/*/index.ts` (global)
+- `.pi/extensions/*.ts` or `/*/index.ts` (project-local)
+- Packages listed in `settings.json#packages` or `settings.json#extensions`
+- npm packages: `"pi": { "extensions": [...] }` in `package.json`
+
+### ExtensionAPI method surface
+
+(`pi-agent/extensions/types.d.ts:770-923`)
+
+| Method | Signature | Notes |
+|--------|-----------|-------|
+| `pi.on(event, handler)` | overloaded per event type | subscribe lifecycle events |
+| `pi.registerTool(tool)` | `(ToolDefinition) => void` | LLM-callable tools |
+| `pi.registerCommand(name, opts)` | `(string, Omit<RegisteredCommand, "name"\|"sourceInfo">) => void` | slash commands |
+| `pi.registerShortcut(shortcut, opts)` | `(KeyId, {handler}) => void` | keyboard shortcuts |
+| `pi.registerFlag(name, opts)` | `(string, {type, default?}) => void` | CLI flags |
+| `pi.getFlag(name)` | `() => boolean\|string\|undefined` | read flag value |
+| `pi.registerMessageRenderer(type, fn)` | custom chat message renderer | |
+| `pi.registerProvider(name, config)` | add/override model provider | can be called after init |
+| `pi.unregisterProvider(name)` | remove provider | |
+| `pi.sendMessage(msg, opts?)` | send custom message (not user turn) | |
+| `pi.sendUserMessage(content, opts?)` | always triggers LLM turn | |
+| `pi.appendEntry(type, data?)` | persist state in session (not sent to LLM) | |
+| `pi.setSessionName(name)` / `getSessionName()` | session display name | |
+| `pi.setLabel(entryId, label)` | bookmark/navigation labels | |
+| `pi.exec(cmd, args, opts?)` | shell execution | |
+| `pi.getActiveTools()` / `setActiveTools(names)` / `getAllTools()` | tool list management | |
+| `pi.getCommands()` | list registered slash commands | |
+| `pi.setModel(model)` / `getThinkingLevel()` / `setThinkingLevel(level)` | model control | |
+| `pi.events` | shared `EventBus` for cross-extension comms | |
+
+### EventBus shape
+
+(`pi-agent/event-bus.d.ts:1-4`)
+
+```typescript
+interface EventBus {
+  emit(channel: string, data: unknown): void;
+  on(channel: string, handler: (data: unknown) => void): () => void;  // returns unsub fn
+}
+```
+
+### pi.on() — all supported events
+
+(`pi-agent/extensions/types.d.ts:771-798`)
+
+| Event name | Handler return | When fired |
+|------------|---------------|------------|
+| `resources_discover` | `ResourcesDiscoverResult?` | after `session_start`, for extra skill/prompt/theme paths |
+| `session_start` | void | startup / reload / new / resume / fork |
+| `session_before_switch` | `{cancel?}` | before switching session |
+| `session_before_fork` | `{cancel?, skipConversationRestore?}` | before forking |
+| `session_before_compact` | `{cancel?, compaction?}` | before context compaction |
+| `session_compact` | void | after compaction |
+| `session_shutdown` | void | before teardown (quit/reload/replace) |
+| `session_before_tree` | `{cancel?, summary?, ...}` | before tree navigation |
+| `session_tree` | void | after tree navigation |
+| `context` | `{messages?}` | before each LLM call; can mutate messages |
+| `before_provider_request` | `unknown` | before HTTP request to provider |
+| `after_provider_response` | void | after HTTP response received |
+| `before_agent_start` | `{message?, systemPrompt?}` | after user submit, before agent loop |
+| `agent_start` | void | agent loop begins |
+| `agent_end` | void | agent loop ends |
+| `turn_start` | void | each turn starts |
+| `turn_end` | void | each turn ends |
+| `message_start` / `message_update` / `message_end` | void | message streaming |
+| `tool_execution_start` / `tool_execution_update` / `tool_execution_end` | void | tool running |
+| `model_select` | void | model changed |
+| `tool_call` | `{block?, reason?}` | before tool executes; mutate `event.input` to patch args |
+| `tool_result` | `{content?, details?, isError?}` | after tool executes; can rewrite result |
+| `user_bash` | `{operations?, result?}` | user's `!cmd` or `!!cmd` |
+| `input` | `{action: "continue"\|"transform"\|"handled"}` | user input received |
+
+### ToolDefinition fields
+
+(`pi-agent/extensions/types.d.ts:325-356`)
+
+Required: `name`, `label`, `description`, `parameters` (TypeBox schema), `execute`.
+Optional: `promptSnippet`, `promptGuidelines`, `executionMode` (`"sequential"`|`"parallel"`),
+`renderCall`, `renderResult`, `renderShell`, `prepareArguments`.
+
+### ProviderConfig (pi.registerProvider)
+
+(`pi-agent/extensions/types.d.ts:924-953`)
+
+Fields: `baseUrl?`, `apiKey?`, `api?`, `models?`, `headers?`, `authHeader?`,
+`streamSimple?`, `oauth?`. If `models` provided, replaces all models for that provider.
+Provider registration is queued during extension init, applied once runner binds context;
+safe to call at any time after that.
+
+---
+
+## 2. pi-subagents RPC Contract
+
+RPC is implemented over `pi.events` using scoped channels.
+(`pi-sub/cross-extension-rpc.ts:1-95`)
+
+### Protocol
+
+- `PROTOCOL_VERSION = 2` (`pi-sub/cross-extension-rpc.ts:24`)
+- Request: emit on `subagents:rpc:<method>` with `{ requestId: string, ...params }`
+- Reply: listen on `subagents:rpc:<method>:reply:<requestId>`
+- Reply envelope (`pi-sub/cross-extension-rpc.ts:19-21`):
+
+```typescript
+type RpcReply<T = void> =
+  | { success: true; data?: T }
+  | { success: false; error: string };
+```
+
+### Methods
+
+**ping** (`pi-sub/cross-extension-rpc.ts:76-78`):
+
+```
+Request:  { requestId: string }
+Reply:    { success: true, data: { version: 2 } }
+```
+
+**spawn** (`pi-sub/cross-extension-rpc.ts:80-85`):
+
+```
+Request:  { requestId: string, type: string, prompt: string, options?: any }
+Reply:    { success: true, data: { id: string } }
+Error:    { success: false, error: "No active session" }
+```
+
+Agent ID is `randomUUID().slice(0, 17)` (`pi-sub/agent-manager.ts:92`).
+The `type` field is a SubagentType string (matches an agent definition name).
+Spawn returns immediately; agent may still be queued (see section 3).
+
+**stop** (`pi-sub/cross-extension-rpc.ts:88-91`):
+
+```
+Request:  { requestId: string, agentId: string }
+Reply:    { success: true }
+Error:    { success: false, error: "Agent not found" }
+```
+
+### Handler wiring
+
+`registerRpcHandlers(deps)` is called once during extension init.
+Returns `{ unsubPing, unsubSpawn, unsubStop }` for cleanup.
+(`pi-sub/cross-extension-rpc.ts:73-95`)
+
+---
+
+## 3. pi-subagents Lifecycle Events
+
+All events emitted on `pi.events`. Sources: `pi-sub/index.ts:364-411`.
+
+| Event | Payload | When fired |
+|-------|---------|------------|
+| `subagents:ready` | `{}` | once on extension init |
+| `subagents:settings_loaded` | `{ settings: SubagentsSettings }` | settings loaded at init |
+| `subagents:settings_changed` | `{ settings: SubagentsSettings, persisted: boolean }` | settings mutated via /agents |
+| `subagents:created` | `{ id, type, description, isBackground: true }` | background spawn accepted |
+| `subagents:started` | `{ id, type, description }` | agent transitions queued→running |
+| `subagents:completed` | see below | terminal success |
+| `subagents:failed` | same shape as completed | terminal failure (error/stopped/aborted) |
+| `subagents:steered` | `{ id, message }` | `steer_subagent` tool called |
+
+**completed / failed payload** (`pi-sub/index.ts:338-362`):
+
+```typescript
+{
+  id: string;
+  type: string;
+  description: string;
+  result: string | undefined;
+  error: string | undefined;
+  status: "completed" | "error" | "stopped" | "aborted" | "steered";
+  toolUses: number;
+  durationMs: number;
+  tokens: { input: number; output: number; total: number } | undefined;
+}
+```
+
+### Timing: subagents:completed vs spawn-RPC reply
+
+Background `subagents:rpc:spawn` reply arrives immediately, carrying only `{ id }`.
+The agent may be queued (`status: "queued"`) at that point.
+`subagents:started` fires when it leaves the queue.
+`subagents:completed` fires inside the AgentManager `onComplete` callback, after the agent
+finishes. There is no ordering guarantee relative to the spawn reply — that reply arrived
+before the agent even started. (`pi-sub/agent-manager.ts:62-100`, `pi-sub/index.ts:364-411`)
+
+### Transcript readability mid-flight
+
+The output file is flushed to disk on every `turn_end` event during the agent's run.
+(`pi-sub/output-file.ts:69-71`: `session.subscribe(event => { if (event.type === "turn_end") flush(); })`)
+Transcripts are readable mid-flight; no need to wait for completion.
+
+---
+
+## 4. Custom Agent Frontmatter Schema
+
+Custom agents defined as `.md` files in `.pi/agents/<name>.md` (project) or
+`~/.pi/agent/agents/<name>.md` (global). Project overrides global on name collision.
+(`pi-sub/custom-agents.ts:20-28`)
+
+Parsed via `parseFrontmatter()` from `@earendil-works/pi-coding-agent`.
+Body (after frontmatter block) becomes `systemPrompt`. (`pi-sub/custom-agents.ts:51-52`)
+
+### All supported frontmatter fields
+
+(`pi-sub/custom-agents.ts:53-73`)
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `display_name` | string | — | human-readable name |
+| `description` | string | filename stem | shown in UI / system prompt |
+| `tools` | CSV string | BUILTIN_TOOL_NAMES | `"none"` → empty list; omit → all builtins |
+| `disallowed_tools` | CSV string | — | tools blocked for this agent |
+| `extensions` / `inherit_extensions` | bool or CSV | `true` (inherit all) | `false`/`"none"` → none; CSV → named list |
+| `skills` / `inherit_skills` | bool or CSV | `true` (inherit all) | same semantics |
+| `model` | string | — | model ID override |
+| `thinking` | ThinkingLevel string | — | thinking level override |
+| `max_turns` | integer ≥ 0 | — | 0 = unlimited |
+| `prompt_mode` | `"replace"` \| `"append"` | `"replace"` | system prompt source |
+| `inherit_context` | boolean | — | prepend parent conversation to prompt text |
+| `run_in_background` | boolean | — | default run mode |
+| `isolated` | boolean | — | deprecated alias for `isolation: worktree` |
+| `memory` | `"user"` \| `"project"` \| `"local"` | — | memory scope |
+| `isolation` | `"worktree"` | — | creates a temp git worktree |
+| `enabled` | boolean | `true` | `false` disables the agent |
+
+**`prompt_mode` × `inherit_context` interaction:**
+`prompt_mode: "replace"` means the agent's body replaces the parent's system prompt
+entirely. `inherit_context: true` is orthogonal: it prepends the parent's conversation
+history to the prompt text. They affect different things — system prompt source vs
+conversation context — and can be combined freely. (`pi-sub/custom-agents.ts:65-66`,
+exploration cache `pi-subagents.md:54-57`)
+
+---
+
+## 5. Slash Command Registration
+
+Extensions register slash commands at load time via:
+
+```typescript
+pi.registerCommand(name, {
+  description?: string,
+  getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null | Promise<...>,
+  handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>,
+});
+```
+
+(`pi-agent/extensions/types.d.ts:802`, `RegisteredCommand` interface at line 755-761`)
+
+`name` is the command name **without** the leading `/`. The runtime prepends `/` when
+displaying and routing. (`pi-agent/docs/extensions.md` — example: `pi.registerCommand("mycommand", ...)`)
+
+The handler receives `args: string` (everything after the command name) and a full
+`ExtensionCommandContext` with `ctx.ui`, session navigation (`newSession`, `fork`,
+`switchSession`), `ctx.waitForIdle()`, and `ctx.reload()`.
+(`pi-agent/extensions/types.d.ts:238-273`)
+
+Commands registered by `@tintinweb/pi-subagents`: `/agents` (`pi-sub/index.ts` — command
+registered in the extension factory body).
+
+---
+
+## 6. Settings File Locations and Schema
+
+### pi (host) settings
+
+File locations (`pi-agent/settings-manager.d.ts:103-108`):
+
+- Global: `~/.pi/agent/settings.json` (default; `$PI_CODING_AGENT_DIR` overrides the
+  entire agent dir path)
+- Project: `.pi/settings.json` (cwd)
+- Precedence: project overrides global on a per-field basis
+
+**Settings schema** (`pi-agent/settings-manager.d.ts:57-94`):
+
+| Key | Type | Notes |
+|-----|------|-------|
+| `defaultProvider` | string | |
+| `defaultModel` | string | |
+| `defaultThinkingLevel` | `"off"\|"minimal"\|"low"\|"medium"\|"high"\|"xhigh"` | |
+| `transport` | Transport | |
+| `steeringMode` | `"all"\|"one-at-a-time"` | |
+| `followUpMode` | `"all"\|"one-at-a-time"` | |
+| `theme` | string | |
+| `compaction` | `{enabled?, reserveTokens?, keepRecentTokens?}` | |
+| `branchSummary` | `{reserveTokens?, skipPrompt?}` | |
+| `retry` | `{enabled?, maxRetries?, baseDelayMs?, provider?}` | |
+| `hideThinkingBlock` | boolean | |
+| `shellPath` | string | |
+| `lastChangelogVersion` | string | last seen changelog version |
+| `quietStartup` | boolean | suppress startup output |
+| `shellCommandPrefix` | string | prefix prepended to shell commands |
+| `npmCommand` | `string[]` | override npm executable and args |
+| `collapseChangelog` | boolean | collapse changelog UI on startup |
+| `enableInstallTelemetry` | boolean | opt-in install telemetry |
+| `doubleEscapeAction` | `"fork"\|"tree"\|"none"` | action triggered by double-Escape |
+| `treeFilterMode` | `"default"\|"no-tools"\|"user-only"\|"labeled-only"\|"all"` | session tree display filter |
+| `editorPaddingX` | number | horizontal editor padding in cells |
+| `autocompleteMaxVisible` | number | max autocomplete suggestions shown |
+| `showHardwareCursor` | boolean | show hardware cursor in TUI |
+| `packages` | `PackageSource[]` | npm/git packages to load extensions/skills from |
+| `extensions` | `string[]` | extra extension paths |
+| `skills` | `string[]` | extra skill paths |
+| `prompts` | `string[]` | extra prompt template paths |
+| `themes` | `string[]` | extra theme paths |
+| `enableSkillCommands` | boolean | |
+| `sessionDir` | string | override for sessions directory |
+| `enabledModels` | `string[]` | |
+| `terminal` | `{showImages?, imageWidthCells?, clearOnShrink?, showTerminalProgress?}` | |
+| `images` | `{autoResize?, blockImages?}` | |
+| `thinkingBudgets` | `{minimal?, low?, medium?, high?}` | |
+| `markdown` | `{codeBlockIndent?}` | |
+| `warnings` | `{anthropicExtraUsage?}` | |
+
+### pi-subagents settings
+
+(`pi-sub/settings.ts:1-20`, `pi-sub/settings.ts:74-80`)
+
+- Global: `~/.pi/agent/subagents.json` — manual defaults, never written by the extension
+- Project: `.pi/subagents.json` — written by `/agents → Settings`
+- Precedence: project overrides global (`pi-sub/settings.ts:99-100`)
+
+**SubagentsSettings schema:**
+
+```typescript
+interface SubagentsSettings {
+  maxConcurrent?: number;      // default 4; 1–1024
+  defaultMaxTurns?: number;    // 0 = unlimited; 0–10000
+  graceTurns?: number;         // 1–1000
+  defaultJoinMode?: "async" | "group" | "smart";
+}
+```
+
+---
+
+## 7. Skill Discovery
+
+Skills are `.md` files injected into the system prompt as XML-formatted context blocks.
+
+### Discovery order
+
+(`pi-agent/skills.d.ts:46-58`, exploration cache `settings-and-skills.md:28-43`)
+
+1. `~/.pi/agent/skills/` — root `.md` files discovered individually; SKILL.md dirs recursed
+2. `~/.agents/skills/` — SKILL.md dirs only (root `.md` files NOT auto-discovered here)
+3. `.pi/skills/` — root `.md` files + SKILL.md dirs
+4. `.agents/skills/` in cwd and ancestor dirs up to git root — SKILL.md dirs only
+5. npm packages: `"pi": { "skills": [...] }` in `package.json`, or `skills/` dir in package
+6. `settings.json#skills` array — explicit paths
+
+### Package manifest
+
+For npm-published extensions, place in `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./dist/index.js"],
+    "skills": ["./skills"]
+  }
+}
+```
+
+(`pi-agent/docs/extensions.md` — extension auto-discovery via `pi.extensions` in package.json)
+
+### Skill file rules
+
+(`pi-agent/skills.d.ts:26-33`)
+
+- Directory containing `SKILL.md` → treated as one skill root; recursion stops there
+- Otherwise: direct `.md` children of a skills dir are each a skill
+- Sub-directories without `SKILL.md` are recursed to find `SKILL.md` files
+
+### Skill frontmatter
+
+(`pi-agent/skills.d.ts:3-7`)
+
+```typescript
+interface SkillFrontmatter {
+  name?: string;
+  description?: string;
+  "disable-model-invocation"?: boolean;
+  [key: string]: unknown;  // open record — arbitrary additional keys permitted (skills.d.ts:7)
+}
+```
+
+`disable-model-invocation: true` excludes the skill from the system prompt; it can still
+be invoked explicitly via `/skill:<name>`.
+
+---
+
+## 8. Session / Output File Locations
+
+### PI session files
+
+Sessions stored in `~/.pi/agent/sessions/` by default.
+Override via `settings.json#sessionDir`. (`pi-agent/settings-manager.d.ts:93`)
+
+### pi-subagents output files
+
+Path template (`pi-sub/output-file.ts:15-23`):
+
+```
+/tmp/pi-subagents-<uid>/<cwd-encoded>/<sessionId>/tasks/<agentId>.output
+```
+
+Where `<cwd-encoded>` = `cwd.replace(/\//g, "-").replace(/^-/, "")`.
+Directory permissions: `0700`. (`pi-sub/output-file.ts:17-19`)
+
+**Format:** JSONL, one entry per message. Each entry:
+
+```typescript
+{
+  isSidechain: true,
+  agentId: string,
+  type: "user" | "assistant" | "toolResult",
+  message: AgentMessage,
+  timestamp: string,  // ISO 8601
+  cwd: string,
+}
+```
+
+(`pi-sub/output-file.ts:26-36`, `pi-sub/output-file.ts:52-64`)
+
+Initial user prompt written by `writeInitialEntry()` at spawn time.
+Subsequent messages appended by `streamToOutputFile()` on each `turn_end`.
+Final flush performed on agent cleanup. (`pi-sub/output-file.ts:42-77`)
+
+File path available in `AgentRecord.outputFile` for cross-extension access.
+
+---
+
+## 9. Resolved Open Questions
+
+### Q1: Slash command registration mechanism
+
+Slash commands are registered via `pi.registerCommand(name, opts)` where `name` has no
+leading `/`. (`pi-agent/extensions/types.d.ts:802`) The runtime routes `/name` user
+input to the handler. This is confirmed by `@tintinweb/pi-subagents` registering `/agents`
+this way in its extension factory (`pi-sub/index.ts` — `pi.registerCommand("agents", ...)` 
+pattern visible from imports and factory body). Commands are TypeScript — there are no
+`.md`-based slash command definitions. The `/` prefix is entirely runtime-managed; the
+extension only ever sees and registers the bare name.
+
+### Q2: subagents:completed timing relative to spawn-RPC reply
+
+The spawn RPC reply (`{ success: true, data: { id } }`) arrives immediately after
+`manager.spawn()` returns, before the agent executes any work. (`pi-sub/cross-extension-rpc.ts:81-85`)
+The `spawn()` method assigns an ID, sets status to `"queued"` for background agents, and
+returns synchronously. (`pi-sub/agent-manager.ts:92-98`) `subagents:completed` fires inside
+the `onComplete` callback passed to `AgentManager`, which is called only after the agent
+finishes all turns and cleans up. (`pi-sub/index.ts:364-373`) These two events are separated
+by the full agent execution time. Importantly, the `onComplete` callback fires after the
+agent promise resolves, not before — so a post-hoc audit listener on `subagents:completed`
+can inspect the output file, but cannot veto or block the result from reaching the parent;
+by the time `completed` fires, the agent has already returned its result string.
+
+### Q3: Transcript mid-flight readability
+
+Transcripts are readable mid-flight. The output file is opened at spawn time
+(`writeInitialEntry` at `pi-sub/output-file.ts:26-36`) and flushed to disk on every
+`turn_end` during the agent's run (`pi-sub/output-file.ts:69-71`). Because flush is
+synchronous (`appendFileSync`), each turn's messages are durably written before the next
+turn begins. A reader monitoring the file path (`AgentRecord.outputFile`) sees new entries
+accumulate turn-by-turn during execution, not just at completion.
+
+### Q4: prompt_mode: replace × inherit_context: true interaction
+
+`prompt_mode` and `inherit_context` are orthogonal fields affecting different aspects of
+agent context. (`pi-sub/custom-agents.ts:65-66`)
+
+`prompt_mode: "replace"` (the default) means the agent's `.md` body is used as the full
+system prompt, replacing whatever the parent agent's system prompt was. `prompt_mode: "append"`
+appends the body to the parent system prompt instead.
+
+`inherit_context: true` means the parent's conversation history (the messages array, not
+the system prompt) is prepended to the agent's context when it starts. It is independent of
+which system prompt source is used.
+
+Combined effect of `prompt_mode: "replace"` + `inherit_context: true`: the agent gets the
+parent's conversation history as context but runs under its own system prompt (the `.md`
+body), not the parent's. This is the planner pattern: planner reads what's been discussed
+but operates under its own instructions.
+
+### Q5: Full pi extension runtime API surface
+
+The surface is `ExtensionAPI` defined in `pi-agent/extensions/types.d.ts:770-923`. Complete
+method list documented in Section 1. Key observations that differ from prior assumptions:
+
+- Tool interception is via `tool_call` / `tool_result` events with mutable `event.input`
+  and result override — not named PreToolUse/PostToolUse hooks.
+- No file-specific event hooks (no Read-event, Write-event, etc.) — only a generic
+  `tool_call` event that carries `toolName` and `input`, requiring the handler to check
+  `toolName` itself.
+- `pi.events` is the shared `EventBus` instance for cross-extension communication, exposed
+  directly on the `ExtensionAPI` object (`pi-agent/extensions/types.d.ts:922`).
+- Provider registration (`registerProvider`/`unregisterProvider`) supports OAuth, custom
+  stream handlers, and model-level API overrides — more complete than expected.
+- Session navigation (fork, branch tree, compaction control) is available in
+  `ExtensionCommandContext` passed to command handlers.
+- Extensions can set custom TUI components: editor, footer, header, widgets, working
+  indicator. (`pi-agent/extensions/types.d.ts:94-188`)
+
+---
+
+## 10. API Gaps
+
+### What the brainstorm assumed PI has — that it does not
+
+**PreToolUse hooks (absent).**
+PI has no `PreToolUse` / `PostToolUse` hook system as found in Claude Code's
+`~/.claude/settings.json#hooks`. The equivalent is registering a `tool_call` or
+`tool_result` handler via `pi.on("tool_call", handler)`, which receives a mutable
+`event.input` and can return `{ block: true, reason: "..." }` to halt execution.
+(`pi-agent/extensions/types.d.ts:795, 705-709`) The mechanism exists but under different
+names and a different programming model (in-process TypeScript callbacks, not external
+shell processes).
+
+**File-event hooks (absent).**
+There are no per-file-operation hooks for Read, Write, Glob, or Grep. The `tool_call`
+event is generic — it fires for all tools including `read`, `write`, `grep`, `find`, `ls`.
+Type-narrowing via `isToolCallEventType("read", event)` is provided
+(`pi-agent/extensions/types.d.ts:688-698`), but this is a `tool_call` handler with a type
+check, not a dedicated file-event hook. No separate hook channels exist for these operations.
+
+**`.pi-lens/` is a debug log directory, not a manifest directory.**
+The path `~/.pi-lens/` (in user home) is written by `pi-lens/index.ts` as a debug log:
+`const DEBUG_LOG_DIR = path.join(os.homedir(), ".pi-lens")` and
+`const DEBUG_LOG = path.join(DEBUG_LOG_DIR, "sessionstart.log")`.
+(`pi-lens/index.ts:47-48`) It contains `sessionstart.log` only. It is not a manifest
+directory, not scanned for extensions or skills, and has no role in PI's extension
+discovery system. The pi-lens package manifest is in its `package.json` under `"pi"`.
+
+### What PI has that the brainstorm missed or underspecified
+
+- **TUI customization API** — `ctx.ui.setEditorComponent()`, `setFooter()`, `setHeader()`,
+  `setWidget()`, `setWorkingIndicator()`, `custom()` for arbitrary keyboard-focused
+  components. (`pi-agent/extensions/types.d.ts:96-188`) This is richer than expected.
+- **OAuth provider support** — `pi.registerProvider()` supports a full OAuth login/refresh
+  flow for enterprise SSO providers. (`pi-agent/extensions/types.d.ts:940-952`)
+- **Session tree navigation from commands** — `ctx.fork()`, `ctx.navigateTree()`,
+  `ctx.newSession()`, `ctx.switchSession()` in `ExtensionCommandContext`.
+  (`pi-agent/extensions/types.d.ts:242-272`)
+- **Context compaction control** — `session_before_compact` event with cancel/custom result;
+  `ctx.compact()` callable from any event handler. (`pi-agent/extensions/types.d.ts:775, 229-231`)
+- **`resources_discover` event** — extensions can dynamically add skill/prompt/theme paths
+  per session. (`pi-agent/extensions/types.d.ts:771, 366-377`)
+- **`before_agent_start` system prompt injection** — returning `{ systemPrompt }` from this
+  handler replaces the system prompt for that turn; multiple extensions chain.
+  (`pi-agent/extensions/types.d.ts:783, 720-726`)
+- **Agent manager global registry** — `pi-subagents` exposes the manager via
+  `Symbol.for("pi-subagents:manager")` on `globalThis` for cross-package access without
+  going through RPC. (`pi-sub/index.ts:413-422`)
+- **Batch notification / group join** — background agent completions are debounced and
+  grouped by `GroupJoinManager` before emitting UI notifications, with a 200 ms hold window.
+  (`pi-sub/index.ts:262-335`) This affects timing of `subagent-notification` custom messages
+  but not `subagents:completed` event timing.

package/docs/PORTING.md

@@ -0,0 +1,105 @@
+# Porting Claude Code Skills and Agents to PI
+
+This document maps Claude Code rnd-framework conventions to PI equivalents. Use it when porting skill `.md` files or agent `.md` files from a Claude Code plugin to PI, and when reviewing ported output to confirm no Claude-specific terms remain.
+
+---
+
+## Frontmatter Translation
+
+The table below covers every frontmatter key that appears in Claude Code skill and agent files. Keys marked **drop** have no PI equivalent and must be removed entirely.
+
+| Claude Code | PI | Notes |
+|---|---|---|
+| `name: rnd-planner` | drop | PI uses the filename stem as the agent/skill name |
+| `description: ...` | `description: ...` | Identical; preserve verbatim |
+| `tools: Read, Grep` | `tools: Read, Grep` | CSV string; unchanged |
+| `disallowedTools: X,Y` | `disallowed_tools: X,Y` | Snake_case rename; same CSV value |
+| `effort: low\|medium\|high` | `thinking: low\|medium\|high\|xhigh\|minimal` | Rename; `effort: low` → `thinking: minimal` is the closest match; see §4 for level semantics |
+| `maxTurns: N` | `max_turns: N` | Snake_case rename; same integer value |
+| `subagent_type: foo` | `type` | PI uses the filename stem as the implicit agent type. The spawn-time argument `type: 'rnd-builder'` (passed to `pi.events.emit('subagents:rpc:spawn', ...)`) matches the agent file's basename. |
+| `color: "#3B82F6"` | drop | Not in PI custom-agent schema (PI-API.md §4) |
+| `model: opus` | `model: claude-opus-4-7` | Use full PI-supported model ID |
+| `prompt_mode: replace\|append` | `prompt_mode: replace\|append` | Identical; PI default is `replace` |
+| `inherit_context: bool` | `inherit_context: bool` | Identical |
+| `isolation: worktree` | `isolation: worktree` | Identical; PI-API.md §4 |
+| `memory: user\|project\|local` | `memory: user\|project\|local` | Identical |
+| `skills: [a,b,c]` | drop; use `inherit_skills: true` | PI has no named-skill list in agent frontmatter; rely on auto-injection via skill discovery (PI-API.md §7) |
+| any unlisted key | drop | PI's agent parser ignores unknown keys, but remove to keep frontmatter canonical |
+
+---
+
+## Vocabulary Substitution
+
+These are Claude Code constructs that appear in skill and agent body text. Replace each with the PI equivalent when porting.
+
+| Claude Code | PI equivalent | Notes |
+|---|---|---|
+| `Agent tool` | `subagents:rpc:spawn` event | The Claude Code `Agent` built-in tool has no PI counterpart; spawning is event-driven via `pi.events.emit('subagents:rpc:spawn', ...)` |
+| `Agent({subagent_type, prompt})` | `pi.events.emit("subagents:rpc:spawn", {requestId, type, prompt, options})` | PI-API.md §2; reply on `subagents:rpc:spawn:reply:<requestId>` |
+| `Skill tool` | auto-injected via skill discovery | Skills matching discovery paths are injected into the system prompt; explicit invocation via `/skill:<name>` when `disable-model-invocation: true` (PI-API.md §7) |
+| `SendMessage` | not directly supported | Agent final result string is the primary inter-agent output; `subagents:completed` event payload `{id, result, ...}` carries it |
+| `TaskCreate` / `TaskUpdate` / `TaskList` | `pi.appendEntry("rnd:phase"\|"rnd:wave"\|"rnd:verdict", data)` | PI-API.md §1; persists runtime state outside the LLM context window |
+| `AskUserQuestion` | `ctx.ui.notify(text, level)` | No multi-option UI equivalent; the user's next turn carries their reply |
+| `${CLAUDE_PLUGIN_ROOT}` | strip; use paths relative to extension root or resolve via `process.cwd()` | PI-API.md §1 |
+| `CLAUDE_SESSION_ID` | strip | PI session ID is internal and not exposed to extension code |
+| `~/.claude/agents/` | `.pi/agents/` (project) or `~/.pi/agent/agents/` (global) | See Install Locations below |
+| `~/.claude/skills/` | `.pi/skills/` (project) or `~/.pi/agent/skills/` (global) | PI-API.md §7 |
+| `${CLAUDE_PROJECT_DIR}` | `process.cwd()` | PI sets cwd to the project root before loading extensions |
+
+---
+
+## Install Locations
+
+### Agents
+
+Place ported `.md` files at `.pi/agents/<name>.md` (project-local, **primary**). This path is loaded on every agent invocation — no PI restart required.
+
+Global fallback: `~/.pi/agent/agents/<name>.md`. Project-local overrides global on name collision.
+
+The npm package `agents/` directory is **not** auto-discovered. PI's `loadCustomAgents` function hard-codes only the two paths above (`pi-sub/custom-agents.ts:20-28`). Users must manually copy files into one of the two paths; a `package.json` key analogous to `"pi": { "agents": [...] }` does not exist.
+
+### Skills
+
+PI auto-discovers skills from, in priority order (PI-API.md §7):
+
+1. `~/.pi/agent/skills/` — global
+2. `.pi/skills/` — project-local
+3. npm packages declaring `"pi": { "skills": ["./skills"] }` in `package.json`
+
+For npm-install distribution, add the following to `package.json`:
+
+```json
+{
+  "pi": {
+    "skills": ["./skills"]
+  }
+}
+```
+
+---
+
+## Gate / Hook Translation
+
+**Claude Code** uses external shell scripts listed in `hooks/hooks.json`. Each hook matches a lifecycle event (e.g., `PreToolUse`) with optional tool matchers (`Bash`, `Read`, etc.) and runs as a separate process.
+
+**PI** uses a single in-process subscription:
+
+```typescript
+pi.on("tool_call", (event) => {
+  // return { block: true, reason: "..." } to veto; return void/null to allow
+})
+```
+
+The handler receives the tool name and full input object. Returning `{ block: true, reason }` halts execution before the tool runs (PI-API.md §10; confirmed by static analysis of `ToolCallEventResult` at `dist/core/extensions/types.d.ts:705-709`). Multiple gates compose by funneling all logic through a single `tool_call` subscriber — not via separate hook registrations.
+
+---
+
+## What Does Not Port
+
+These Claude Code constructs have no PI equivalent and must be removed entirely when porting:
+
+- `${CLAUDE_PLUGIN_ROOT}` — no equivalent path variable in PI
+- Multi-option `AskUserQuestion` UI — PI exposes only `ctx.ui.notify`; no structured choice dialogs
+- `SendMessage` — there is no explicit agent-to-orchestrator messaging channel; communication flows through the `subagents:completed` result payload
+- Dedicated `Agent` tool — PI spawning is event-driven via `subagents:rpc:spawn`, not a built-in LLM tool
+- Separate hook event types (`PreToolUse`, `PostToolUse`, etc.) — PI has one `tool_call` event covering pre-execution only