@draht/coding-agent 2026.3.6 → 2026.3.14

package/docs/extensions.md

@@ -225,8 +225,9 @@ Run `npm install` in the extension directory, then imports from `node_modules/`
 ### Lifecycle Overview
 
 ```
-pi starts
+pi starts (CLI only)
   │
+  ├─► session_directory (CLI startup only, no ctx)
   └─► session_start
       │
       ▼
@@ -243,6 +244,7 @@ user sends prompt ────────────────────
   │   │                                            │       │
   │   ├─► turn_start                               │       │
   │   ├─► context (can modify messages)            │       │
+  │   ├─► before_provider_request (can inspect or replace payload)
   │   │                                            │       │
   │   │   LLM responds, may call tools:            │       │
   │   │     ├─► tool_call (can block)              │       │
@@ -284,6 +286,26 @@ exit (Ctrl+C, Ctrl+D)
 
 See [session.md](session.md) for session storage internals and the SessionManager API.
 
+#### session_directory
+
+Fired by the `pi` CLI during startup session resolution, before the initial session manager is created.
+
+This event is:
+- CLI-only. It is not emitted in SDK mode.
+- Startup-only. It is not emitted for later interactive `/new` or `/resume` actions.
+- Bypassed when `--session-dir` is provided.
+- Special-cased to receive no `ctx` argument.
+
+If multiple extensions return `sessionDir`, the last one wins.
+
+```typescript
+pi.on("session_directory", async (event) => {
+  return {
+    sessionDir: `/tmp/pi-sessions/${encodeURIComponent(event.cwd)}`,
+  };
+});
+```
+
 #### session_start
 
 Fired on initial session load.
@@ -489,6 +511,21 @@ pi.on("context", async (event, ctx) => {
 });
 ```
 
+#### before_provider_request
+
+Fired after the provider-specific payload is built, right before the request is sent. Handlers run in extension load order. Returning `undefined` keeps the payload unchanged. Returning any other value replaces the payload for later handlers and for the actual request.
+
+```typescript
+pi.on("before_provider_request", (event, ctx) => {
+  console.log(JSON.stringify(event.payload, null, 2));
+
+  // Optional: replace payload
+  // return { ...event.payload, temperature: 0 };
+});
+```
+
+This is mainly useful for debugging provider serialization and cache behavior.
+
 ### Model Events
 
 #### model_select
@@ -658,7 +695,9 @@ Transforms chain across handlers. See [input-transform.ts](../examples/extension
 
 ## ExtensionContext
 
-Every handler receives `ctx: ExtensionContext`:
+All handlers except `session_directory` receive `ctx: ExtensionContext`.
+
+`session_directory` is a CLI startup hook and receives only the event.
 
 ### ctx.ui
 
@@ -1340,6 +1379,18 @@ pi.registerTool({
 });
 ```
 
+**Signaling errors:** To mark a tool execution as failed (sets `isError: true` on the result and reports it to the LLM), throw an error from `execute`. Returning a value never sets the error flag regardless of what properties you include in the return object.
+
+```typescript
+// Correct: throw to signal an error
+async execute(toolCallId, params) {
+  if (!isValid(params.input)) {
+    throw new Error(`Invalid input: ${params.input}`);
+  }
+  return { content: [{ type: "text", text: "OK" }], details: {} };
+}
+```
+
 **Important:** Use `StringEnum` from `@draht/ai` for string enums. `Type.Union`/`Type.Literal` doesn't work with Google's API.
 
 ### Overriding Built-in Tools
@@ -1880,7 +1931,7 @@ const highlighted = highlightCode(code, lang, theme);
 
 - Extension errors are logged, agent continues
 - `tool_call` errors block the tool (fail-safe)
-- Tool `execute` errors are reported to the LLM with `isError: true`
+- Tool `execute` errors must be signaled by throwing; the thrown error is caught, reported to the LLM with `isError: true`, and execution continues
 
 ## Mode Behavior
 
@@ -1922,6 +1973,7 @@ All examples in [examples/extensions/](../examples/extensions/).
 | `dirty-repo-guard.ts` | Warn on dirty git repo | `on("session_before_*")`, `exec` |
 | `input-transform.ts` | Transform user input | `on("input")` |
 | `model-status.ts` | React to model changes | `on("model_select")`, `setStatus` |
+| `provider-payload.ts` | Inspect or patch provider payloads | `on("before_provider_request")` |
 | `system-prompt-header.ts` | Display system prompt info | `on("agent_start")`, `getSystemPrompt` |
 | `claude-rules.ts` | Load rules from files | `on("session_start")`, `on("before_agent_start")` |
 | `file-trigger.ts` | File watcher triggers messages | `sendMessage` |

package/docs/keybindings.md

@@ -7,11 +7,12 @@ All keyboard shortcuts can be customized via `~/.pi/agent/keybindings.json`. Eac
 `modifier+key` where modifiers are `ctrl`, `shift`, `alt` (combinable) and keys are:
 
 - **Letters:** `a-z`
+- **Digits:** `0-9`
 - **Special:** `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageUp`, `pageDown`, `up`, `down`, `left`, `right`
 - **Function:** `f1`-`f12`
 - **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
 
-Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, etc.
+Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1`, etc.
 
 ## All Actions
 
@@ -119,6 +120,13 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, etc.
 | `selectConfirm` | `enter` | Confirm selection |
 | `selectCancel` | `escape`, `ctrl+c` | Cancel selection |
 
+### Tree Navigation
+
+| Action | Default | Description |
+|--------|---------|-------------|
+| `treeFoldOrUp` | `ctrl+left`, `alt+left` | Fold current branch segment, or jump to the previous segment start |
+| `treeUnfoldOrDown` | `ctrl+right`, `alt+right` | Unfold current branch segment, or jump to the next segment start or branch end |
+
 ### Session Picker
 
 | Action | Default | Description |

package/docs/models.md

@@ -129,7 +129,7 @@ The `apiKey` and `headers` fields support three formats:
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
 | `id` | Yes | — | Model identifier (passed to the API) |
-| `name` | No | `id` | Display name in model selector |
+| `name` | No | `id` | Human-readable model label. Used for matching (`--model` patterns) and shown in model details/status text. |
 | `api` | No | provider's `api` | Override provider's API for this model |
 | `reasoning` | No | `false` | Supports extended thinking |
 | `input` | No | `["text"]` | Input types: `["text"]` or `["text", "image"]` |
@@ -137,6 +137,10 @@ The `apiKey` and `headers` fields support three formats:
 | `maxTokens` | No | `16384` | Maximum output tokens |
 | `cost` | No | all zeros | `{"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0}` (per million tokens) |
 
+Current behavior:
+- `/model` and `--list-models` list entries by model `id`.
+- The configured `name` is used for model matching and detail/status text.
+
 ## Overriding Built-in Providers
 
 Route a built-in provider through a proxy without redefining models:

package/docs/rpc.md

@@ -24,6 +24,17 @@ Common options:
 
 All commands support an optional `id` field for request/response correlation. If provided, the corresponding response will include the same `id`.
 
+### Framing
+
+RPC mode uses strict JSONL semantics with LF (`\n`) as the only record delimiter.
+
+This matters for clients:
+- Split records on `\n` only
+- Accept optional `\r\n` input by stripping a trailing `\r`
+- Do not use generic line readers that treat Unicode separators as newlines
+
+In particular, Node `readline` is not protocol-compliant for RPC mode because it also splits on `U+2028` and `U+2029`, which are valid inside JSON strings.
+
 ## Commands
 
 ### Prompting
@@ -1292,13 +1303,39 @@ For a complete example of handling the extension UI protocol, see [`examples/rpc
 
 ```javascript
 const { spawn } = require("child_process");
-const readline = require("readline");
+const { StringDecoder } = require("string_decoder");
 
 const agent = spawn("pi", ["--mode", "rpc", "--no-session"]);
 
-readline.createInterface({ input: agent.stdout }).on("line", (line) => {
+function attachJsonlReader(stream, onLine) {
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+
+    stream.on("data", (chunk) => {
+        buffer += typeof chunk === "string" ? chunk : decoder.write(chunk);
+
+        while (true) {
+            const newlineIndex = buffer.indexOf("\n");
+            if (newlineIndex === -1) break;
+
+            let line = buffer.slice(0, newlineIndex);
+            buffer = buffer.slice(newlineIndex + 1);
+            if (line.endsWith("\r")) line = line.slice(0, -1);
+            onLine(line);
+        }
+    });
+
+    stream.on("end", () => {
+        buffer += decoder.end();
+        if (buffer.length > 0) {
+            onLine(buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer);
+        }
+    });
+}
+
+attachJsonlReader(agent.stdout, (line) => {
     const event = JSON.parse(line);
-    
+
     if (event.type === "message_update") {
         const { assistantMessageEvent } = event;
         if (assistantMessageEvent.type === "text_delta") {

package/docs/session.md

@@ -5,14 +5,14 @@ Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with
 ## File Location
 
 ```
-~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
+~/.draht/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
 ```
 
 Where `<path>` is the working directory with `/` replaced by `-`.
 
 ## Deleting Sessions
 
-Sessions can be removed by deleting their `.jsonl` files under `~/.pi/agent/sessions/`.
+Sessions can be removed by deleting their `.jsonl` files under `~/.draht/agent/sessions/`.
 
 Pi also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, pi uses the `trash` CLI to avoid permanent deletion.
 

package/docs/settings.md

@@ -42,6 +42,7 @@ Edit directly or use `/settings` for common options.
 | `quietStartup` | boolean | `false` | Hide startup header |
 | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
 | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
+| `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
 | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
 | `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
 | `showHardwareCursor` | boolean | `false` | Show terminal cursor |

package/docs/terminal-setup.md

@@ -8,13 +8,30 @@ Work out of the box.
 
 ## Ghostty
 
-Add to your Ghostty config (`~/.config/ghostty/config`):
+Add to your Ghostty config (`~/Library/Application Support/com.mitchellh.ghostty/config` on macOS, `~/.config/ghostty/config` on Linux):
 
 ```
 keybind = alt+backspace=text:\x1b\x7f
+```
+
+Older Claude Code versions may have added this Ghostty mapping:
+
+```
 keybind = shift+enter=text:\n
 ```
 
+That mapping sends a raw linefeed byte. Inside pi, that is indistinguishable from `Ctrl+J`, so tmux and pi no longer see a real `shift+enter` key event.
+
+If Claude Code 2.x or newer is the only reason you added that mapping, you can remove it, unless you want to use Claude Code in tmux, where it still requires that Ghostty mapping.
+
+If you want `Shift+Enter` to keep working in tmux via that remap, add `ctrl+j` to your pi `newLine` keybinding in `~/.pi/agent/keybindings.json`:
+
+```json
+{
+  "newLine": ["shift+enter", "ctrl+j"]
+}
+```
+
 ## WezTerm
 
 Create `~/.wezterm.lua`:
@@ -46,7 +63,7 @@ Add to `keybindings.json` to enable `Shift+Enter` for multi-line input:
 
 ## Windows Terminal
 
-Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file):
+Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward the modified Enter keys pi uses:
 
 ```json
 {
@@ -54,12 +71,20 @@ Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file):
     {
       "command": { "action": "sendInput", "input": "\u001b[13;2u" },
       "keys": "shift+enter"
+    },
+    {
+      "command": { "action": "sendInput", "input": "\u001b[13;3u" },
+      "keys": "alt+enter"
     }
   ]
 }
 ```
 
-If you already have an `actions` array, add the object to it.
+- `Shift+Enter` inserts a new line.
+- Windows Terminal binds `Alt+Enter` to fullscreen by default. That prevents pi from receiving `Alt+Enter` for follow-up queueing.
+- Remapping `Alt+Enter` to `sendInput` forwards the real key chord to pi instead.
+
+If you already have an `actions` array, add the objects to it. If the old fullscreen behavior persists, fully close and reopen Windows Terminal.
 
 ## IntelliJ IDEA (Integrated Terminal)
 

package/docs/tmux.md

@@ -0,0 +1,61 @@
+# tmux Setup
+
+Pi works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `Shift+Enter` and `Ctrl+Enter` are usually indistinguishable from plain `Enter`.
+
+## Recommended Configuration
+
+Add to `~/.tmux.conf`:
+
+```tmux
+set -g extended-keys on
+set -g extended-keys-format csi-u
+```
+
+Then restart tmux fully:
+
+```bash
+tmux kill-server
+tmux
+```
+
+Pi requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration.
+
+## Why `csi-u` Is Recommended
+
+With only:
+
+```tmux
+set -g extended-keys on
+```
+
+tmux defaults to `extended-keys-format xterm`. When an application requests extended key reporting, modified keys are forwarded in xterm `modifyOtherKeys` format such as:
+
+- `Ctrl+C` → `\x1b[27;5;99~`
+- `Ctrl+D` → `\x1b[27;5;100~`
+- `Ctrl+Enter` → `\x1b[27;5;13~`
+
+With `extended-keys-format csi-u`, the same keys are forwarded as:
+
+- `Ctrl+C` → `\x1b[99;5u`
+- `Ctrl+D` → `\x1b[100;5u`
+- `Ctrl+Enter` → `\x1b[13;5u`
+
+Pi supports both formats, but `csi-u` is the recommended tmux setup.
+
+## What This Fixes
+
+Without tmux extended keys, modified Enter keys collapse to legacy sequences:
+
+| Key | Without extkeys | With `csi-u` |
+|-----|-----------------|--------------|
+| Enter | `\r` | `\r` |
+| Shift+Enter | `\r` | `\x1b[13;2u` |
+| Ctrl+Enter | `\r` | `\x1b[13;5u` |
+| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` |
+
+This affects the default keybindings (`Enter` to submit, `Shift+Enter` for newline) and any custom keybindings using modified Enter.
+
+## Requirements
+
+- tmux 3.2 or later (run `tmux -V` to check)
+- A terminal emulator that supports extended keys (Ghostty, Kitty, iTerm2, WezTerm, Windows Terminal)

package/docs/tree.md

@@ -33,16 +33,25 @@ Sessions are stored as trees where each entry has an `id` and `parentId`. The "l
 | Key | Action |
 |-----|--------|
 | ↑/↓ | Navigate (depth-first order) |
+| ←/→ | Page up/down |
+| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold and jump between branch segments |
 | Enter | Select node |
 | Escape/Ctrl+C | Cancel |
 | Ctrl+U | Toggle: user messages only |
 | Ctrl+O | Toggle: show all (including custom/label entries) |
 
+`Ctrl+←` or `Alt+←` folds the current node if it is foldable. Foldable nodes are roots and branch segment starts that have visible children. If the current node is not foldable, or is already folded, the selection jumps up to the previous visible branch segment start.
+
+`Ctrl+→` or `Alt+→` unfolds the current node if it is folded. Otherwise, the selection jumps down to the next visible branch segment start, or to the branch end when there is no further branch point.
+
 ### Display
 
 - Height: half terminal height
 - Current leaf marked with `← active`
 - Labels shown inline: `[label-name]`
+- Foldable branch starts show `⊟` in the connector. Folded branches show `⊞`
+- Active path marker `•` appears after the fold indicator when applicable
+- Search and filter changes reset all folds
 - Default filter hides `label` and `custom` entries (shown in Ctrl+O mode)
 - Children sorted by timestamp (oldest first)
 

package/examples/extensions/antigravity-image-gen.ts

@@ -28,10 +28,9 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { StringEnum } from "@draht/ai";
-import type { ExtensionAPI } from "@draht/coding-agent";
+import { type ExtensionAPI, getAgentDir } from "@draht/coding-agent";
 import { type Static, Type } from "@sinclair/typebox";
 
 const PROVIDER = "google-antigravity";
@@ -184,7 +183,8 @@ function readConfigFile(path: string): ExtensionConfig {
 }
 
 function loadConfig(cwd: string): ExtensionConfig {
-	const globalConfig = readConfigFile(join(homedir(), ".pi", "agent", "extensions", "antigravity-image-gen.json"));
+	const globalPath = join(getAgentDir(), "extensions", "antigravity-image-gen.json");
+	const globalConfig = readConfigFile(globalPath);
 	const projectConfig = readConfigFile(join(cwd, ".pi", "extensions", "antigravity-image-gen.json"));
 	return { ...globalConfig, ...projectConfig };
 }
@@ -204,7 +204,8 @@ function resolveSaveConfig(params: ToolParams, cwd: string): SaveConfig {
 	}
 
 	if (mode === "global") {
-		return { mode, outputDir: join(homedir(), ".pi", "agent", "generated-images") };
+		const outputDir = join(getAgentDir(), "generated-images");
+		return { mode, outputDir };
 	}
 
 	if (mode === "custom") {

package/examples/extensions/custom-provider-gitlab-duo/test.ts

@@ -10,7 +10,7 @@
 
 import { type Api, type Context, type Model, registerApiProvider, streamSimple } from "@draht/ai";
 import { readFileSync } from "fs";
-import { homedir } from "os";
+import { getAgentDir } from "packages/coding-agent/src/config.js";
 import { join } from "path";
 import { MODELS, streamGitLabDuo } from "./index.js";
 
@@ -28,7 +28,7 @@ async function main() {
 	}
 
 	// Read auth
-	const authPath = join(homedir(), ".pi", "agent", "auth.json");
+	const authPath = join(getAgentDir(), "extensions", "auth.json");
 	const authData = JSON.parse(readFileSync(authPath, "utf-8"));
 	const gitlabCred = authData["gitlab-duo"];
 	if (!gitlabCred?.access) {

package/examples/extensions/notify.ts

@@ -3,12 +3,14 @@
  *
  * Sends a native terminal notification when Pi agent is done and waiting for input.
  * Supports multiple terminal protocols:
+ * - cmux: uses `cmux notify` CLI
  * - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
  * - OSC 99: Kitty
  * - Windows toast: Windows Terminal (WSL)
  */
 
 import type { ExtensionAPI } from "@draht/coding-agent";
+import { execFile } from "child_process";
 
 function windowsToastScript(title: string, body: string): string {
 	const type = "Windows.UI.Notifications";
@@ -33,13 +35,18 @@ function notifyOSC99(title: string, body: string): void {
 	process.stdout.write(`\x1b]99;i=1:p=body;${body}\x1b\\`);
 }
 
+function notifyCmux(title: string, body: string): void {
+	execFile("cmux", ["notify", "--title", title, "--body", body]);
+}
+
 function notifyWindows(title: string, body: string): void {
-	const { execFile } = require("child_process");
 	execFile("powershell.exe", ["-NoProfile", "-Command", windowsToastScript(title, body)]);
 }
 
 function notify(title: string, body: string): void {
-	if (process.env.WT_SESSION) {
+	if (process.env.CMUX_BUNDLE_ID) {
+		notifyCmux(title, body);
+	} else if (process.env.WT_SESSION) {
 		notifyWindows(title, body);
 	} else if (process.env.KITTY_WINDOW_ID) {
 		notifyOSC99(title, body);