@draht/coding-agent 2026.3.5 → 2026.3.11-1

package/dist/prompts/commands/verify-work.md

@@ -4,7 +4,7 @@ description: "Acceptance testing of completed phase work"
 
 # /verify-work
 
-Walk through acceptance testing of completed phase work.
+Walk through acceptance testing of completed phase work, using subagents for parallel verification.
 
 ## Usage
 ```
@@ -14,20 +14,34 @@ Walk through acceptance testing of completed phase work.
 Phase: $1
 
 ## Steps
-1. Run full test suite and capture results:
-   - Execute all tests (`bun test` or project-specific runner)
-   - Record pass/fail counts — verification cannot proceed if tests are failing
-2. Check domain language violations:
-   - Load `.planning/DOMAIN.md` and extract all defined terms
-   - Scan source files for PascalCase identifiers not present in the glossary
-   - Flag any bounded context boundary violations (cross-context direct imports)
-3. Run quality gate: `draht-tools quality-gate --strict`
-4. Run `draht-tools extract-deliverables $1` to get testable items
-5. Walk user through each deliverable one at a time
-6. Record results (pass/fail/partially/skip)
-7. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
+1. Run `draht-tools extract-deliverables $1` to get testable items
+2. **Run parallel verification via subagents:**
+   Use the `subagent` tool in **parallel mode** with these tasks:
+   - `verifier` agent: "Run the full test suite for this project. Check package.json for the test command. Record pass/fail counts. Then run any available lint and typecheck commands (e.g. npm run check, npm run lint, npx tsc --noEmit). Report all results with error details. Do NOT run draht, draht-tools, or pi commands."
+   - `security-auditor` agent: "Audit the recent code changes (use git log and git diff to find them). Check for injection risks, auth bypasses, secrets in code, unsafe patterns. Report findings by severity. Do NOT run draht, draht-tools, or pi commands."
+   - `reviewer` agent: "Review the recent code changes (use git log and git diff). Check domain language compliance against `.planning/DOMAIN.md` if it exists — scan for identifiers not in the glossary and cross-context boundary violations. Report findings. Do NOT run draht, draht-tools, or pi commands."
+
+3. Collect results from all subagents
+4. Walk user through each deliverable one at a time, incorporating findings from the parallel checks
+5. Record results (pass/fail/partially/skip)
+6. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
    - Fix plans MUST include a reproducing test that demonstrates the failure before any implementation
-8. Write UAT report: `draht-tools write-uat $1`
-   - Report must include: test health summary (pass/fail/coverage), domain model status (any glossary violations), deliverable results
-9. If all passed: mark phase complete
-10. If failures: route to `execute-phase $1 --gaps-only`
+7. Write UAT report: `draht-tools write-uat $1`
+   - Report must include: test health summary (pass/fail/coverage), security audit results, domain model status (any glossary violations), deliverable results
+8. If all passed: mark phase complete.
+   - If more phases remain in the milestone: tell the user to start a new session and run `/discuss-phase N+1`.
+   - If ALL phases in the milestone are complete: tell the user to start a new session and run `/next-milestone`.
+9. If failures: route to `execute-phase $1 --gaps-only`
+
+## Workflow
+This is the last step in the per-phase cycle. Each step runs in its own session (`/new` between steps):
+
+```
+/discuss-phase N → /new → /plan-phase N → /new → /execute-phase N → /new → /verify-work N
+```
+
+After verify-work passes:
+- More phases remaining → `/new` → `/discuss-phase N+1`
+- ALL phases in milestone verified → `/new` → `/next-milestone`
+
+`/next-milestone` is ONLY for generating new phases after every phase in the current milestone is complete.

package/docs/compaction.md

@@ -262,6 +262,8 @@ Before summarization, messages are serialized to text via [`serializeConversatio
 
 This prevents the model from treating it as a conversation to continue.
 
+Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated. This keeps summarization requests within reasonable token budgets, since tool results (especially from `read` and `bash`) are typically the largest contributors to context size.
+
 ## Custom Summarization via Extensions
 
 Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.

package/docs/custom-provider.md

@@ -159,6 +159,7 @@ The `api` field determines which streaming implementation is used:
 | `openai-responses` | OpenAI Responses API |
 | `azure-openai-responses` | Azure OpenAI Responses API |
 | `openai-codex-responses` | OpenAI Codex Responses API |
+| `mistral-conversations` | Mistral SDK Conversations/Chat streaming |
 | `google-generative-ai` | Google Generative AI API |
 | `google-gemini-cli` | Google Cloud Code Assist API |
 | `google-vertex` | Google Vertex AI API |
@@ -180,14 +181,17 @@ models: [{
       high: "default",
       xhigh: "default"
     },
-    maxTokensField: "max_tokens",      // instead of "max_completion_tokens"
-    requiresToolResultName: true,      // tool results need name field
-    requiresMistralToolIds: true,
-    thinkingFormat: "qwen"             // uses enable_thinking: true
-  }
-}]
+      maxTokensField: "max_tokens",      // instead of "max_completion_tokens"
+      requiresToolResultName: true,      // tool results need name field
+      thinkingFormat: "qwen"             // uses enable_thinking: true
+    }
+  }]
 ```
 
+> Migration note: Mistral moved from `openai-completions` to `mistral-conversations`.
+> Use `mistral-conversations` for native Mistral models.
+> If you intentionally route Mistral-compatible/custom endpoints through `openai-completions`, set `compat` flags explicitly as needed.
+
 ### Auth Header
 
 If your provider expects `Authorization: Bearer <key>` but doesn't use a standard API, set `authHeader: true`:
@@ -301,6 +305,7 @@ For providers with non-standard APIs, implement `streamSimple`. Study the existi
 
 **Reference implementations:**
 - [anthropic.ts](https://github.com/draht-dev/draht/blob/main/packages/ai/src/providers/anthropic.ts) - Anthropic Messages API
+- [mistral.ts](https://github.com/draht-dev/draht/blob/main/packages/ai/src/providers/mistral.ts) - Mistral Conversations API
 - [openai-completions.ts](https://github.com/draht-dev/draht/blob/main/packages/ai/src/providers/openai-completions.ts) - OpenAI Chat Completions
 - [openai-responses.ts](https://github.com/draht-dev/draht/blob/main/packages/ai/src/providers/openai-responses.ts) - OpenAI Responses API
 - [google.ts](https://github.com/draht-dev/draht/blob/main/packages/ai/src/providers/google.ts) - Google Generative AI
@@ -581,7 +586,6 @@ interface ProviderModelConfig {
     requiresToolResultName?: boolean;
     requiresAssistantAfterToolResult?: boolean;
     requiresThinkingAsText?: boolean;
-    requiresMistralToolIds?: boolean;
     thinkingFormat?: "openai" | "zai" | "qwen";
   };
 }

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)