From 02175d908b4a4b2be271f275ace332752450dfdb Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Fri, 2 Jan 2026 01:26:21 +0100
Subject: [PATCH] Update docs for ctx.ui.editor() and handoff example

- Added ctx.ui.editor() to hooks.md and custom-tools.md
- Added ctx.ui.editor() to CHANGELOG.md
- Added handoff.ts to examples/hooks/README.md
---
 packages/coding-agent/CHANGELOG.md             |  1 +
 packages/coding-agent/docs/custom-tools.md     | 17 +++++++++++++++++
 packages/coding-agent/examples/README.md       | 10 +---------
 packages/coding-agent/examples/hooks/README.md |  1 +
 4 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 01d2711d..667afc25 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -36,6 +36,7 @@ The hooks API has been restructured with more granular events and better session
 - New `pi.registerCommand(name, options)` for custom slash commands (handler receives `HookCommandContext`)
 - New `pi.registerMessageRenderer(customType, renderer)` for custom TUI rendering
 - New `ctx.isIdle()`, `ctx.abort()`, `ctx.hasQueuedMessages()` for agent state (available in all events)
+- New `ctx.ui.editor(title, prefill?)` for multi-line text editing with Ctrl+G external editor support
 - New `ctx.ui.custom(component)` for full TUI component rendering with keyboard focus
 - New `ctx.ui.setStatus(key, text)` for persistent status text in footer (multiple hooks can set their own)
 - New `ctx.ui.theme` getter for styling text with theme colors
diff --git a/packages/coding-agent/docs/custom-tools.md b/packages/coding-agent/docs/custom-tools.md
index 2e546618..61061ef6 100644
--- a/packages/coding-agent/docs/custom-tools.md
+++ b/packages/coding-agent/docs/custom-tools.md
@@ -257,6 +257,23 @@ async execute(toolCallId, params, onUpdate, ctx, signal) {
 }
 ```
 
+### Multi-line Editor
+
+For longer text editing, use `pi.ui.editor()` which supports Ctrl+G for external editor:
+
+```typescript
+async execute(toolCallId, params, onUpdate, ctx, signal) {
+  const text = await pi.ui.editor("Edit your response:", "prefilled text");
+  // Returns edited text or undefined if cancelled (Escape)
+  // Ctrl+Enter to submit, Ctrl+G to open $VISUAL or $EDITOR
+  
+  if (!text) {
+    return { content: [{ type: "text", text: "Cancelled" }] };
+  }
+  // ...
+}
+```
+
 ## Session Lifecycle
 
 Tools can implement `onSession` to react to session changes:
diff --git a/packages/coding-agent/examples/README.md b/packages/coding-agent/examples/README.md
index 9b9ba0c6..c1748c27 100644
--- a/packages/coding-agent/examples/README.md
+++ b/packages/coding-agent/examples/README.md
@@ -1,6 +1,6 @@
 # Examples
 
-Example code for pi-coding-agent.
+Example code for pi-coding-agent SDK, hooks, and custom tools.
 
 ## Directories
 
@@ -13,14 +13,6 @@ Example hooks for intercepting tool calls, adding safety gates, and integrating
 ### [custom-tools/](custom-tools/)
 Example custom tools that extend the agent's capabilities.
 
-## Running Examples
-
-```bash
-cd packages/coding-agent
-npx tsx examples/sdk/01-minimal.ts
-npx tsx examples/hooks/permission-gate.ts
-```
-
 ## Documentation
 
 - [SDK Reference](sdk/README.md)
diff --git a/packages/coding-agent/examples/hooks/README.md b/packages/coding-agent/examples/hooks/README.md
index 8661f6a4..70f84fe8 100644
--- a/packages/coding-agent/examples/hooks/README.md
+++ b/packages/coding-agent/examples/hooks/README.md
@@ -27,6 +27,7 @@ cp permission-gate.ts ~/.pi/agent/hooks/
 | `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
 | `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
 | `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
+| `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
 
 ## Writing Hooks