@mariozechner/pi-coding-agent 0.50.8 → 0.51.0

package/docs/rpc.md

@@ -903,6 +903,191 @@ Emitted when an extension throws an error.
 }
 ```
 
+## Extension UI Protocol
+
+Extensions can request user interaction via `ctx.ui.select()`, `ctx.ui.confirm()`, etc. In RPC mode, these are translated into a request/response sub-protocol on top of the base command/event flow.
+
+There are two categories of extension UI methods:
+
+- **Dialog methods** (`select`, `confirm`, `input`, `editor`): emit an `extension_ui_request` on stdout and block until the client sends back an `extension_ui_response` on stdin with the matching `id`.
+- **Fire-and-forget methods** (`notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`): emit an `extension_ui_request` on stdout but do not expect a response. The client can display the information or ignore it.
+
+If a dialog method includes a `timeout` field, the agent-side will auto-resolve with a default value when the timeout expires. The client does not need to track timeouts.
+
+Some `ExtensionUIContext` methods are not supported in RPC mode because they require direct TUI access:
+- `custom()` returns `undefined`
+- `setWorkingMessage()`, `setFooter()`, `setHeader()`, `setEditorComponent()` are no-ops
+- `getEditorText()` returns `""`
+
+### Extension UI Requests (stdout)
+
+All requests have `type: "extension_ui_request"`, a unique `id`, and a `method` field.
+
+#### select
+
+Prompt the user to choose from a list. Dialog methods with a `timeout` field include the timeout in milliseconds; the agent auto-resolves with `undefined` if the client doesn't respond in time.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-1",
+  "method": "select",
+  "title": "Allow dangerous command?",
+  "options": ["Allow", "Block"],
+  "timeout": 10000
+}
+```
+
+Expected response: `extension_ui_response` with `value` (the selected option string) or `cancelled: true`.
+
+#### confirm
+
+Prompt the user for yes/no confirmation.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-2",
+  "method": "confirm",
+  "title": "Clear session?",
+  "message": "All messages will be lost.",
+  "timeout": 5000
+}
+```
+
+Expected response: `extension_ui_response` with `confirmed: true/false` or `cancelled: true`.
+
+#### input
+
+Prompt the user for free-form text.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-3",
+  "method": "input",
+  "title": "Enter a value",
+  "placeholder": "type something..."
+}
+```
+
+Expected response: `extension_ui_response` with `value` (the entered text) or `cancelled: true`.
+
+#### editor
+
+Open a multi-line text editor with optional prefilled content.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-4",
+  "method": "editor",
+  "title": "Edit some text",
+  "prefill": "Line 1\nLine 2\nLine 3"
+}
+```
+
+Expected response: `extension_ui_response` with `value` (the edited text) or `cancelled: true`.
+
+#### notify
+
+Display a notification. Fire-and-forget, no response expected.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-5",
+  "method": "notify",
+  "message": "Command blocked by user",
+  "notifyType": "warning"
+}
+```
+
+The `notifyType` field is `"info"`, `"warning"`, or `"error"`. Defaults to `"info"` if omitted.
+
+#### setStatus
+
+Set or clear a status entry in the footer/status bar. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-6",
+  "method": "setStatus",
+  "statusKey": "my-ext",
+  "statusText": "Turn 3 running..."
+}
+```
+
+Send `statusText: undefined` (or omit it) to clear the status entry for that key.
+
+#### setWidget
+
+Set or clear a widget (block of text lines) displayed above or below the editor. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-7",
+  "method": "setWidget",
+  "widgetKey": "my-ext",
+  "widgetLines": ["--- My Widget ---", "Line 1", "Line 2"],
+  "widgetPlacement": "aboveEditor"
+}
+```
+
+Send `widgetLines: undefined` (or omit it) to clear the widget. The `widgetPlacement` field is `"aboveEditor"` (default) or `"belowEditor"`. Only string arrays are supported in RPC mode; component factories are ignored.
+
+#### setTitle
+
+Set the terminal window/tab title. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-8",
+  "method": "setTitle",
+  "title": "pi - my project"
+}
+```
+
+#### set_editor_text
+
+Set the text in the input editor. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-9",
+  "method": "set_editor_text",
+  "text": "prefilled text for the user"
+}
+```
+
+### Extension UI Responses (stdin)
+
+Responses are sent for dialog methods only (`select`, `confirm`, `input`, `editor`). The `id` must match the request.
+
+#### Value response (select, input, editor)
+
+```json
+{"type": "extension_ui_response", "id": "uuid-1", "value": "Allow"}
+```
+
+#### Confirmation response (confirm)
+
+```json
+{"type": "extension_ui_response", "id": "uuid-2", "confirmed": true}
+```
+
+#### Cancellation response (any dialog)
+
+Dismiss any dialog method. The extension receives `undefined` (for select/input/editor) or `false` (for confirm).
+
+```json
+{"type": "extension_ui_response", "id": "uuid-3", "cancelled": true}
+```
+
 ## Error Handling
 
 Failed commands return a response with `success: false`:
@@ -933,7 +1118,7 @@ Source files:
 - [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
 - [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AgentMessage`, `AgentEvent`
 - [`src/core/messages.ts`](../src/core/messages.ts) - `BashExecutionMessage`
-- [`src/modes/rpc/rpc-types.ts`](../src/modes/rpc/rpc-types.ts) - RPC command/response types
+- [`src/modes/rpc/rpc-types.ts`](../src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types
 
 ### Model
 
@@ -1082,6 +1267,8 @@ for event in read_events():
 
 See [`test/rpc-example.ts`](../test/rpc-example.ts) for a complete interactive example, or [`src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts) for a typed client implementation.
 
+For a complete example of handling the extension UI protocol, see [`examples/rpc-extension-ui.ts`](../examples/rpc-extension-ui.ts) which pairs with the [`examples/extensions/rpc-demo.ts`](../examples/extensions/rpc-demo.ts) extension.
+
 ```javascript
 const { spawn } = require("child_process");
 const readline = require("readline");

package/docs/termux.md

@@ -0,0 +1,127 @@
+# Termux (Android) Setup
+
+Pi runs on Android via [Termux](https://termux.dev/), a terminal emulator and Linux environment for Android.
+
+## Prerequisites
+
+1. Install [Termux](https://github.com/termux/termux-app#installation) from GitHub or F-Droid (not Google Play, that version is deprecated)
+2. Install [Termux:API](https://github.com/termux/termux-api#installation) from GitHub or F-Droid for clipboard and other device integrations
+
+## Installation
+
+```bash
+# Update packages
+pkg update && pkg upgrade
+
+# Install dependencies
+pkg install nodejs termux-api git
+
+# Install pi
+npm install -g @mariozechner/pi-coding-agent
+
+# Create config directory
+mkdir -p ~/.pi/agent
+
+# Run pi
+pi
+```
+
+## Clipboard Support
+
+Clipboard operations use `termux-clipboard-set` and `termux-clipboard-get` when running in Termux. The Termux:API app must be installed for these to work.
+
+Image clipboard is not supported on Termux (the `ctrl+v` image paste feature will not work).
+
+## Example AGENTS.md for Termux
+
+Create `~/.pi/agent/AGENTS.md` to help the agent understand the Termux environment:
+
+```markdown
+# Agent Environment: Termux on Android
+
+## Location
+- **OS**: Android (Termux terminal emulator)
+- **Home**: `/data/data/com.termux/files/home`
+- **Prefix**: `/data/data/com.termux/files/usr`
+- **Shared storage**: `/storage/emulated/0` (Downloads, Documents, etc.)
+
+## Opening URLs
+```bash
+termux-open-url "https://example.com"
+```
+
+## Opening Files
+```bash
+termux-open file.pdf          # Opens with default app
+termux-open -c image.jpg      # Choose app
+```
+
+## Clipboard
+```bash
+termux-clipboard-set "text"   # Copy
+termux-clipboard-get          # Paste
+```
+
+## Notifications
+```bash
+termux-notification -t "Title" -c "Content"
+```
+
+## Device Info
+```bash
+termux-battery-status         # Battery info
+termux-wifi-connectioninfo    # WiFi info
+termux-telephony-deviceinfo   # Device info
+```
+
+## Sharing
+```bash
+termux-share -a send file.txt # Share file
+```
+
+## Other Useful Commands
+```bash
+termux-toast "message"        # Quick toast popup
+termux-vibrate                # Vibrate device
+termux-tts-speak "hello"      # Text to speech
+termux-camera-photo out.jpg   # Take photo
+```
+
+## Notes
+- Termux:API app must be installed for `termux-*` commands
+- Use `pkg install termux-api` for the command-line tools
+- Storage permission needed for `/storage/emulated/0` access
+```
+
+## Limitations
+
+- **No image clipboard**: Termux clipboard API only supports text
+- **No native binaries**: Some optional native dependencies (like the clipboard module) are unavailable on Android ARM64 and are skipped during installation
+- **Storage access**: To access files in `/storage/emulated/0` (Downloads, etc.), run `termux-setup-storage` once to grant permissions
+
+## Troubleshooting
+
+### Clipboard not working
+
+Ensure both apps are installed:
+1. Termux (from GitHub or F-Droid)
+2. Termux:API (from GitHub or F-Droid)
+
+Then install the CLI tools:
+```bash
+pkg install termux-api
+```
+
+### Permission denied for shared storage
+
+Run once to grant storage permissions:
+```bash
+termux-setup-storage
+```
+
+### Node.js installation issues
+
+If npm fails, try clearing the cache:
+```bash
+npm cache clean --force
+```

package/examples/extensions/README.md

@@ -53,9 +53,11 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
 | `send-user-message.ts` | Demonstrates `pi.sendUserMessage()` for sending user messages from extensions |
 | `timed-confirm.ts` | Demonstrates AbortSignal for auto-dismissing `ctx.ui.confirm()` and `ctx.ui.select()` dialogs |
+| `rpc-demo.ts` | Exercises all RPC-supported extension UI methods; pair with [`examples/rpc-extension-ui.ts`](../rpc-extension-ui.ts) |
 | `modal-editor.ts` | Custom vim-like modal editor via `ctx.ui.setEditorComponent()` |
 | `rainbow-editor.ts` | Animated rainbow text effect via custom editor |
 | `notify.ts` | Desktop notifications via OSC 777 when agent finishes (Ghostty, iTerm2, WezTerm) |
+| `titlebar-spinner.ts` | Braille spinner animation in terminal title while the agent is working |
 | `summarize.ts` | Summarize conversation with GPT-5.2 and show in transient UI |
 | `custom-footer.ts` | Custom footer with git branch and token stats via `ctx.ui.setFooter()` |
 | `custom-header.ts` | Custom header via `ctx.ui.setHeader()` |

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

@@ -352,7 +352,7 @@ export default function antigravityImageGen(pi: ExtensionAPI) {
 		description:
 			"Generate an image via Google Antigravity image models. Returns the image as a tool result attachment. Optional saving via save=project|global|custom|none, or PI_IMAGE_SAVE_MODE/PI_IMAGE_SAVE_DIR.",
 		parameters: TOOL_PARAMS,
-		async execute(_toolCallId, params: ToolParams, onUpdate, ctx, signal) {
+		async execute(_toolCallId, params: ToolParams, signal, onUpdate, ctx) {
 			const { accessToken, projectId } = await getCredentials(ctx);
 			const model = params.model || DEFAULT_MODEL;
 			const aspectRatio = params.aspectRatio || DEFAULT_ASPECT_RATIO;

package/examples/extensions/bash-spawn-hook.ts

@@ -0,0 +1,30 @@
+/**
+ * Bash Spawn Hook Example
+ *
+ * Adjusts command, cwd, and env before execution.
+ *
+ * Usage:
+ *   pi -e ./bash-spawn-hook.ts
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createBashTool } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	const cwd = process.cwd();
+
+	const bashTool = createBashTool(cwd, {
+		spawnHook: ({ command, cwd, env }) => ({
+			command: `source ~/.profile\n${command}`,
+			cwd,
+			env: { ...env, PI_SPAWN_HOOK: "1" },
+		}),
+	});
+
+	pi.registerTool({
+		...bashTool,
+		execute: async (id, params, signal, onUpdate, _ctx) => {
+			return bashTool.execute(id, params, signal, onUpdate);
+		},
+	});
+}

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "1.1.8",
+      "version": "1.2.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "1.1.8",
+  "version": "1.2.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "1.1.8",
+  "version": "1.2.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-qwen-cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-qwen-cli",
   "private": true,
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/hello.ts

@@ -14,7 +14,7 @@ export default function (pi: ExtensionAPI) {
 			name: Type.String({ description: "Name to greet" }),
 		}),
 
-		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
 			const { name } = params as { name: string };
 			return {
 				content: [{ type: "text", text: `Hello, ${name}!` }],

package/examples/extensions/question.ts

@@ -40,7 +40,7 @@ export default function question(pi: ExtensionAPI) {
 		description: "Ask the user a question and let them pick from options. Use when you need user input to proceed.",
 		parameters: QuestionParams,
 
-		async execute(_toolCallId, params, _onUpdate, ctx, _signal) {
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			if (!ctx.hasUI) {
 				return {
 					content: [{ type: "text", text: "Error: UI not available (running in non-interactive mode)" }],

package/examples/extensions/questionnaire.ts

@@ -81,7 +81,7 @@ export default function questionnaire(pi: ExtensionAPI) {
 			"Ask the user one or more questions. Use for clarifying requirements, getting preferences, or confirming decisions. For single questions, shows a simple option list. For multiple questions, shows a tab-based interface.",
 		parameters: QuestionnaireParams,
 
-		async execute(_toolCallId, params, _onUpdate, ctx, _signal) {
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			if (!ctx.hasUI) {
 				return errorResult("Error: UI not available (running in non-interactive mode)");
 			}

package/examples/extensions/rpc-demo.ts

@@ -0,0 +1,124 @@
+/**
+ * RPC Extension UI Demo
+ *
+ * Purpose-built extension that exercises all RPC-supported extension UI methods.
+ * Designed to be loaded alongside the rpc-extension-ui-example.ts script to
+ * demonstrate the full extension UI protocol.
+ *
+ * UI methods exercised:
+ * - select() - on tool_call for dangerous bash commands
+ * - confirm() - on session_before_switch
+ * - input() - via /rpc-input command
+ * - editor() - via /rpc-editor command
+ * - notify() - after each dialog completes
+ * - setStatus() - on turn_start/turn_end
+ * - setWidget() - on session_start
+ * - setTitle() - on session_start and session_switch
+ * - setEditorText() - via /rpc-prefill command
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	let turnCount = 0;
+
+	// -- setTitle, setWidget, setStatus on session lifecycle --
+
+	pi.on("session_start", async (_event, ctx) => {
+		ctx.ui.setTitle("pi RPC Demo");
+		ctx.ui.setWidget("rpc-demo", ["--- RPC Extension UI Demo ---", "Loaded and ready."]);
+		ctx.ui.setStatus("rpc-demo", `Turns: ${turnCount}`);
+	});
+
+	pi.on("session_switch", async (_event, ctx) => {
+		turnCount = 0;
+		ctx.ui.setTitle("pi RPC Demo (new session)");
+		ctx.ui.setStatus("rpc-demo", `Turns: ${turnCount}`);
+	});
+
+	// -- setStatus on turn lifecycle --
+
+	pi.on("turn_start", async (_event, ctx) => {
+		turnCount++;
+		ctx.ui.setStatus("rpc-demo", `Turn ${turnCount} running...`);
+	});
+
+	pi.on("turn_end", async (_event, ctx) => {
+		ctx.ui.setStatus("rpc-demo", `Turn ${turnCount} done`);
+	});
+
+	// -- select on dangerous tool calls --
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "bash") return undefined;
+
+		const command = event.input.command as string;
+		const isDangerous = /\brm\s+(-rf?|--recursive)/i.test(command) || /\bsudo\b/i.test(command);
+
+		if (isDangerous) {
+			if (!ctx.hasUI) {
+				return { block: true, reason: "Dangerous command blocked (no UI)" };
+			}
+
+			const choice = await ctx.ui.select(`Dangerous command: ${command}`, ["Allow", "Block"]);
+			if (choice !== "Allow") {
+				ctx.ui.notify("Command blocked by user", "warning");
+				return { block: true, reason: "Blocked by user" };
+			}
+			ctx.ui.notify("Command allowed", "info");
+		}
+
+		return undefined;
+	});
+
+	// -- confirm on session clear --
+
+	pi.on("session_before_switch", async (event, ctx) => {
+		if (event.reason !== "new") return;
+		if (!ctx.hasUI) return;
+
+		const confirmed = await ctx.ui.confirm("Clear session?", "All messages will be lost.");
+		if (!confirmed) {
+			ctx.ui.notify("Clear cancelled", "info");
+			return { cancel: true };
+		}
+	});
+
+	// -- input via command --
+
+	pi.registerCommand("rpc-input", {
+		description: "Prompt for text input (demonstrates ctx.ui.input in RPC)",
+		handler: async (_args, ctx) => {
+			const value = await ctx.ui.input("Enter a value", "type something...");
+			if (value) {
+				ctx.ui.notify(`You entered: ${value}`, "info");
+			} else {
+				ctx.ui.notify("Input cancelled", "info");
+			}
+		},
+	});
+
+	// -- editor via command --
+
+	pi.registerCommand("rpc-editor", {
+		description: "Open multi-line editor (demonstrates ctx.ui.editor in RPC)",
+		handler: async (_args, ctx) => {
+			const text = await ctx.ui.editor("Edit some text", "Line 1\nLine 2\nLine 3");
+			if (text) {
+				ctx.ui.notify(`Editor submitted (${text.split("\n").length} lines)`, "info");
+			} else {
+				ctx.ui.notify("Editor cancelled", "info");
+			}
+		},
+	});
+
+	// -- setEditorText via command --
+
+	pi.registerCommand("rpc-prefill", {
+		description: "Prefill the input editor (demonstrates ctx.ui.setEditorText in RPC)",
+		handler: async (_args, ctx) => {
+			ctx.ui.setEditorText("This text was set by the rpc-demo extension.");
+			ctx.ui.notify("Editor prefilled", "info");
+		},
+	});
+}

package/examples/extensions/sandbox/index.ts

@@ -211,7 +211,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		...localBash,
 		label: "bash (sandboxed)",
-		async execute(id, params, onUpdate, _ctx, signal) {
+		async execute(id, params, signal, onUpdate, _ctx) {
 			if (!sandboxEnabled || !sandboxInitialized) {
 				return localBash.execute(id, params, signal, onUpdate);
 			}

package/examples/extensions/shutdown-command.ts

@@ -23,7 +23,7 @@ export default function (pi: ExtensionAPI) {
 		label: "Finish and Exit",
 		description: "Complete a task and exit pi",
 		parameters: Type.Object({}),
-		async execute(_toolCallId, _params, _onUpdate, ctx, _signal) {
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
 			// Do any final work here...
 			// Request graceful shutdown (deferred until agent is idle)
 			ctx.shutdown();
@@ -44,7 +44,7 @@ export default function (pi: ExtensionAPI) {
 		parameters: Type.Object({
 			environment: Type.String({ description: "Target environment (e.g., production, staging)" }),
 		}),
-		async execute(_toolCallId, params, onUpdate, ctx, _signal) {
+		async execute(_toolCallId, params, _signal, onUpdate, ctx) {
 			onUpdate?.({ content: [{ type: "text", text: `Deploying to ${params.environment}...` }], details: {} });
 
 			// Example deployment logic

package/examples/extensions/ssh.ts

@@ -127,7 +127,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.registerTool({
 		...localRead,
-		async execute(id, params, onUpdate, _ctx, signal) {
+		async execute(id, params, signal, onUpdate, _ctx) {
 			const ssh = getSsh();
 			if (ssh) {
 				const tool = createReadTool(localCwd, {
@@ -141,7 +141,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.registerTool({
 		...localWrite,
-		async execute(id, params, onUpdate, _ctx, signal) {
+		async execute(id, params, signal, onUpdate, _ctx) {
 			const ssh = getSsh();
 			if (ssh) {
 				const tool = createWriteTool(localCwd, {
@@ -155,7 +155,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.registerTool({
 		...localEdit,
-		async execute(id, params, onUpdate, _ctx, signal) {
+		async execute(id, params, signal, onUpdate, _ctx) {
 			const ssh = getSsh();
 			if (ssh) {
 				const tool = createEditTool(localCwd, {
@@ -169,7 +169,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.registerTool({
 		...localBash,
-		async execute(id, params, onUpdate, _ctx, signal) {
+		async execute(id, params, signal, onUpdate, _ctx) {
 			const ssh = getSsh();
 			if (ssh) {
 				const tool = createBashTool(localCwd, {

package/examples/extensions/subagent/index.ts

@@ -416,7 +416,7 @@ export default function (pi: ExtensionAPI) {
 		].join(" "),
 		parameters: SubagentParams,
 
-		async execute(_toolCallId, params, onUpdate, ctx, signal) {
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const agentScope: AgentScope = params.agentScope ?? "user";
 			const discovery = discoverAgents(ctx.cwd, agentScope);
 			const agents = discovery.agents;