gentle-pi 2.5.0 → 2.6.1

package/assets/support/sdd-status-contract.md

@@ -15,94 +15,43 @@ Any phase that selects, continues, applies, verifies, syncs, or archives an SDD
 
 ## Native Engine
 
-- For file-backed `openspec` or `both` sessions with an `openspec/` directory, use Gentle Pi's local SDD status engine as the artifact-state authority. It resolves the local artifact graph without consulting RDD authority or receipts.
-- For non-authoritative stores (`engram`, `none`, and `both` without an `openspec/` directory), do not treat disk status output as authoritative; follow Engine Authority by Store below.
-- Runtime-attempt authority is different from artifact dispatch: normal runtime-bearing OpenSpec and Engram continuations MUST bracket external execution with `gentle-ai sdd-attempt acquire|settle --cwd <repo> --change <change>`. Their bounded result contains only `proceed`, `blocked`, or `complete` plus an opaque continuation token when required, and MAY carry `settle_obligation` on a `proceed`. The Git-common-dir immutable chain remains the sole authority for ordinals, cumulative attempt/line budgets, runtime evidence, and atomic bound remediation.
-- A phase actor launched BY a parent that already holds a `proceed`-state acquire for that exact work unit is a distinct call/process, not a fresh continuation: it MUST NOT `acquire` again blind. Colliding with its own parent's active attempt is not a genuine `blocked: active_attempt` (#2291). It authenticates as that SAME attempt by passing the parent's returned token on its own `acquire --token <token>` call: a token matching the ledger's live active attempt returns `proceed` with that same token and zero mutation, while a non-matching token gets the ordinary `blocked: active_attempt` naming the real active token.
-- When `blockedReasons` is non-empty, do not proceed to terminal, archive, or apply work. Return or report `blockedReasons` and stop unless `nextRecommended` is `verify`, in which case verification may run only to remediate or refresh evidence for the blockers. When `nextRecommended` is `resolve-blockers`, always report `blockedReasons` and stop. When `nextRecommended` is a planning token (`propose`, `spec`, `design`, or `tasks`), launch the corresponding planning phase — missing planning artifacts are the expected output of those phases, not genuine blockers.
-- `nextRecommended` is a bounded machine token for routing, not human prose. Route only by `nextRecommended` and dependency states. Human-readable explanation belongs in `blockedReasons`, not `nextRecommended`.
-- If the binary is unavailable, fall back to this prompt contract and the manual status schema below. Manual fallback status MUST stay shape-compatible with the native status JSON even when values are reconstructed manually.
+- `gentle-ai sdd-status --contract gentle-ai.sdd-status/v2` is the sole status authority for every store. It is read-only: inspect its native projection unchanged and never launch a phase, prepare consent, or grant roots while reading it.
+- If native status is unavailable, malformed, or does not select the requested change/workspace, stop and report that failure. Do not construct a local status, infer readiness from artifacts, substitute continuation, or bypass it through Engram.
+- `nextRecommended`, `dependencies`, `blockedReasons`, `actionContext`, and optional `phaseInstructions` are producer facts. Route only by their typed values, never by prose or a local lifecycle graph. A genuine blocker's human-readable explanation belongs in `blockedReasons`; a non-blocking diagnostic belongs in `notes`; neither belongs in `nextRecommended`.
+- Runtime-attempt authority is separate from status: runtime-bearing work uses the provider `sdd-attempt acquire|settle` flow and its `proceed`, `blocked`, or `complete` result.
+- Only an explicitly authorized `gentle-ai sdd-continue` may prepare a missing change-instance marker. `ensureChangeInstanceMarker` has no status caller; its sole production path is `PrepareChangeInstanceConsent` through `sdd-continue`.
+
+## Bounded Planning Routing
+
+For authoritative native status, route only by the bounded `nextRecommended` token and dependency states; never infer a route from prose. Keep genuine blockers in `blockedReasons` and non-blocking diagnostics in `notes`, never in `nextRecommended`, and report them without discarding them to enable a route.
+
+| `nextRecommended` | Planning route |
+| --- | --- |
+| `propose` | `sdd-proposal` |
+| `spec` | `sdd-spec` |
+| `design` | `sdd-design` |
+| `tasks` | `sdd-tasks` |
+
+Native unprefixed tokens are the only automatic planning routes. Prefixed or locally derived status tokens never authorize a phase.
+
+These planning routes remain runnable when missing planning artifacts leave `dependencies.apply: blocked`; do not require apply readiness to produce those artifacts. This is a planning-only exception, not permission to run apply or another blocked non-planning phase.
+
+Before any planning launch, stop for ambiguous change selection, unresolved session preflight, or unsafe action context. Carry `actionContext` and prove planned writes are within the authoritative workspace or allowed edit roots; workspace-planning without allowed edit roots remains read-only. Planning does not bypass the init guard, pre-proposal gate, or phase approval requirements.
+
+## Bounded Execution Routing
+
+| Native `nextRecommended` | Pi executor |
+| --- | --- |
+| `apply` | `sdd-apply` |
+| `verify` | `sdd-verify` |
+| `remediate` | `sdd-remediate` |
+| `archive` | `sdd-archive` |
+
+Execute only a native selected action whose dependency and `actionContext` permit it. Unknown, malformed, blocked, or unsupported actions stop before work; no local route, prefixed token, or prose can replace them. `notes` is separate from `blockedReasons` and never gates: report a non-empty `notes` value as informational and proceed when the dependency and `blockedReasons` gates allow. Manual `sdd-sync` remains its intentional local resolver and is never an automatic native-status dispatch.
 
 ## Status Schema
 
-Return status as markdown with these fields, or equivalent JSON when the host supports it:
-
-```yaml
-schemaName: spec-driven
-changeName: <change-name>
-artifactStore: openspec | engram | both | none
-planningHome:
-  root: <project-or-openspec-root>
-  changesDir: <openspec/changes or memory topic prefix>
-changeRoot: <openspec/changes/<change> or memory topic prefix>
-artifactPaths:
-  proposal: [<path-or-topic>]
-  specs: [<path-or-topic>]
-  design: [<path-or-topic>]
-  tasks: [<path-or-topic>]
-  applyProgress: [<path-or-topic>]
-  verifyReport: [<path-or-topic>]
-  syncReport: [<path-or-topic>]
-contextFiles:
-  proposal: [<concrete readable files/topics>]
-  specs: [<concrete readable files/topics>]
-  design: [<concrete readable files/topics>]
-  tasks: [<concrete readable files/topics>]
-  applyProgress: [<concrete readable files/topics>]
-  verifyReport: [<concrete readable files/topics>]
-  syncReport: [<concrete readable files/topics>]
-artifacts:
-  proposal: missing | done | partial
-  specs: missing | done | partial
-  design: missing | done | partial
-  tasks: missing | done | partial
-  applyProgress: missing | done | partial
-  verifyReport: missing | done | partial
-  syncReport: missing | done | partial
-taskProgress: # implementation-owned plus malformed unresolved rows
-  total: 0
-  complete: 0
-  remaining: 0
-  unchecked: []
-deferredParentActions:
-  total: 0
-  complete: 0
-  remaining: 0
-  unchecked: []
-taskArtifactErrors: []
-applyState: blocked | all_done | ready | not_applicable
-dependencies:
-  apply: blocked | ready | all_done | not_applicable
-  verify: blocked | ready | all_done | not_applicable
-  sync: blocked | ready | all_done | not_applicable
-  archive: blocked | ready | all_done | not_applicable
-actionContext:
-  mode: repo-local | workspace-planning
-  workspaceRoot: <absolute path>
-  allowedEditRoots: [<absolute paths>]
-  warnings: []
-nextRecommended: <bounded-machine-token>
-isNonAuthoritative: false  # boolean; true when the native engine is not authoritative for the store
-```
-
-## Task Ownership
-
-New task checkboxes end with the terminal marker `<!-- sdd-owner: implementation -->`. An unmarked legacy checkbox is implementation-owned. Supported legacy non-implementation rows are informational only. Any line containing `sdd-owner` that is unsupported, duplicated, or non-terminal is malformed: add its exact line to `taskArtifactErrors` and `blockedReasons`, and count it as unresolved implementation work even when checked. `taskProgress` reports implementation work.
-
-## Apply State
-
-- `blocked`: required apply artifacts are missing, task selection is ambiguous, malformed ownership markers exist, or action context makes edits unsafe.
-- `all_done`: tasks artifact exists and every implementation task is checked `[x]`.
-- `ready`: tasks artifact exists, at least one implementation task remains unchecked, and edit scope is safe.
-- `not_applicable`: emitted for non-authoritative stores (see Engine Authority by Store). This is NOT a blocker.
-
-## Dependency States
-
-- `apply` is `ready` only when specs, design, and tasks are available and task progress is not all done.
-- `verify` is ready after implementation completion when tasks are complete or apply-progress exists. RDD authority and receipts never gate the apply -> verify -> sync -> archive route. Unchecked implementation tasks remain CRITICAL blockers for full archive readiness.
-- `sync` is `ready` only when verify-report exists and has no unresolved `FAIL`, `BLOCKED`, `CRITICAL`, or verification blockers. `engram`/`none` modes may mark sync `not_applicable`.
-- `archive` is `ready` only when verify-report exists, sync is complete or not applicable, and implementation tasks are complete. CRITICAL verification issues have no override. Explicit recorded exceptions are limited to non-critical partial archives or stale-checkbox reconciliation when apply-progress/verify-report prove completion.
-- `not_applicable`: emitted for non-authoritative stores (engram, none, and both when no `openspec/` directory exists) when `nextRecommended: "resolve-via-engram"` is active. `not_applicable` is NOT a gate failure — readiness must be resolved from Engram instead of from these fields.
+Consume the native v2 projection (`schemaName: gentle-ai.sdd-status`, `schemaVersion: 2`) losslessly. Its producer-defined selection, artifact locators, task progress, seven dependencies, `actionContext`, `blockedReasons`, optional execution instructions, remediation state, and `nextRecommended` are status facts, not a Pi schema to recreate.
 
 ## Action Context Guard
 
@@ -112,11 +61,6 @@ The orchestrator MUST carry `actionContext` into any phase launch.
 - If `allowedEditRoots` is present, only edit or move files within those roots.
 - If a phase cannot prove a file is inside the authoritative workspace or allowed edit roots, stop and ask for clarification.
 
-## Engine Authority by Store
-
-- `openspec` and `both` (when `openspec/` directory exists): the local SDD status engine resolves artifact state from disk and is authoritative. Phase executors must obey it.
-- `engram`, `none`, and `both` (when `openspec/` directory does NOT exist): the local engine cannot read Engram artifacts. It returns `nextRecommended: "resolve-via-engram"` and empty `blockedReasons`. This output is **non-authoritative**. The orchestrator must resolve readiness directly from Engram using the Engram memory tools injected by the memory provider on the change topic keys (`sdd/{change-name}/proposal`, `sdd/{change-name}/spec`, etc.) instead of relying on the engine's dependency states. The `artifactStore` field still reflects the real chosen store value (e.g. `"both"`) and must not be rewritten.
-
 ## Native Runtime Attempt Authority
 
 The compact SDD runtime attempt authority is separate from artifact dispatch and status. It is artifact-store agnostic: the same acquire/settle discipline applies to `openspec`, `engram`, `both`, and `none` stores. Its payload MUST NOT be embedded in the SDD v1 status schema above; status reports artifact state only, never attempt tokens or attempt counters. No OpenSpec or Engram attempt ledger may be created or mirrored by Pi.

package/contracts/telemetry/runtime-aggregate-v1.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "gentle-ai.telemetry-runtime-aggregate/v1",
+  "description": "Sanitized stdin for gentle-ai telemetry runtime send --json. Maximum UTF-8 input 16384 bytes. One best-effort send attempt, no client persistence or retry. Rows are independent observations, not a session composition. No caller identity is accepted.",
+  "type": "object", "additionalProperties": false,
+  "required": ["schema", "registry", "host", "rows"],
+  "properties": {
+    "schema": {"const": "gentle-ai.telemetry-runtime-aggregate/v1"},
+    "registry": {"const": 1},
+    "host": {"enum": ["claude-code", "opencode", "codex", "pi"]},
+    "rows": {"type": "array", "minItems": 1, "maxItems": 32, "items": {"$ref": "#/$defs/row"}}
+  },
+  "$defs": {
+    "metric": {"oneOf": [{"type": "integer", "minimum": 0, "maximum": 999999999999}, {"type": "null"}, {"const": "unsupported"}]},
+    "count": {"type": "integer", "minimum": 0, "maximum": 999999999999},
+    "token": {
+      "type": "object", "additionalProperties": false,
+      "required": ["reported", "unavailable", "unsupported", "sum"],
+      "properties": {
+        "reported": {"$ref": "#/$defs/count"}, "unavailable": {"$ref": "#/$defs/count"},
+        "unsupported": {"$ref": "#/$defs/count"}, "sum": {"$ref": "#/$defs/count"}
+      },
+      "if": {"properties": {"reported": {"const": 0}}},
+      "then": {"properties": {"sum": {"const": 0}}}
+    },
+    "duration": {
+      "type": "object", "additionalProperties": false, "required": ["kind", "measured_count", "sum_ms"],
+      "properties": {"kind": {}, "measured_count": {}, "sum_ms": {}},
+      "oneOf": [
+        {"properties": {"kind": {"const": "unavailable"}, "measured_count": {"const": 0}, "sum_ms": {"type": "null"}}},
+        {"properties": {"kind": {"enum": ["request", "message"]}, "measured_count": {"type": "integer", "minimum": 1, "maximum": 999999999999}, "sum_ms": {"type": "number", "minimum": 0, "maximum": 999999999999}}}
+      ]
+    },
+    "effort": {"enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max", "not_selected", "unknown", "custom", "unavailable", "unsupported"]},
+    "model": {
+      "type": "object", "additionalProperties": false, "required": ["provider", "id"],
+      "properties": {
+        "provider": {"type": "string", "maxLength": 32},
+        "id": {"type": "string", "maxLength": 64}
+      },
+      "anyOf": [
+        {"properties": {"provider": {"pattern": "^[a-z0-9][a-z0-9-]{0,31}$"}, "id": {"pattern": "^(claude|gpt|o[1-9]|codex|gemini|gemma|deepseek|glm|qwen|qwq|kimi|moonshot|llama|codellama|mistral|mixtral|codestral|devstral|magistral|ministral|minimax|grok|phi|nemotron|jamba|hunyuan|doubao|ernie|mimo|granite|olmo|smollm|starcoder|titan)[a-z0-9]*([-_.:][a-z0-9]+){0,8}$"}}},
+        {"properties": {"provider": {"const": "unknown"}, "id": {"const": "unknown"}}},
+        {"properties": {"provider": {"const": "custom"}, "id": {"const": "custom"}}},
+        {"properties": {"provider": {"const": "opencode"}, "id": {"const": "custom"}}}
+      ]
+    },
+    "row": {
+      "type": "object", "additionalProperties": false,
+      "required": ["model", "model_evidence", "agent_kind", "agent_class", "selected_effort", "effective_effort", "launches", "responses", "input_tokens", "output_tokens", "cache_read_tokens", "cache_creation_tokens", "reasoning_tokens", "total_tokens", "error_category", "duration"],
+      "properties": {
+        "reasoning_tokens": {"$ref": "#/$defs/token"},
+        "total_tokens": {"$ref": "#/$defs/token"},
+        "agent_class": {"enum": ["orchestrator", "worker", "explore", "verify", "unknown", "sdd-init", "sdd-explore", "sdd-research", "sdd-propose", "sdd-spec", "sdd-design", "sdd-tasks", "sdd-apply", "sdd-verify", "sdd-archive", "sdd-onboard", "sdd-status", "sdd-sync", "jd-judge-a", "jd-judge-b", "jd-fix-agent", "review-risk", "review-readability", "review-reliability", "review-resilience", "review-refuter", "review-validator"]},
+        "error_category": {"enum": ["none", "unknown", "auth", "output_length", "aborted", "api", "rate_limit", "server"]},
+        "duration": {"$ref": "#/$defs/duration"},
+        "model": {"$ref": "#/$defs/model"},
+        "model_evidence": {"enum": ["selected", "response", "unknown"]},
+        "agent_kind": {"enum": ["orchestrator", "built_in", "custom", "unknown"]},
+        "selected_effort": {"$ref": "#/$defs/effort"}, "effective_effort": {"$ref": "#/$defs/effort"},
+        "launches": {"$ref": "#/$defs/metric", "description": "Source-observed event count only; null when not observed. Never reconstructed from sessions."}, "responses": {"$ref": "#/$defs/metric", "description": "Source-observed response occurrence count, independent of token coverage and success."},
+        "input_tokens": {"$ref": "#/$defs/token"}, "output_tokens": {"$ref": "#/$defs/token"},
+        "cache_read_tokens": {"$ref": "#/$defs/token"}, "cache_creation_tokens": {"$ref": "#/$defs/token"}
+      }
+    }
+  }
+}

package/docs/telemetry.md

@@ -1,6 +1,62 @@
 # Telemetry
 
-`gentle-pi` does not collect anything itself. [`gentle-ai`](https://github.com/Gentleman-Programming/gentle-ai) (issue [#4309](https://github.com/Gentleman-Programming/gentle-ai/issues/4309)) owns anonymous usage telemetry end to end: install and heartbeat events, the exact fields sent, rate limiting, and every opt-out. See gentle-ai's own README/docs for that contract. Gentle Pi's only involvement is a best-effort nudge that asks the local binary to act.
+Runtime usage telemetry is best effort: an available usage event gets at most one
+asynchronous attempt through `gentle-ai telemetry runtime send --json`. Busy,
+failed, disabled, or cancelled attempts are discarded silently. There is no
+metrics disk storage, outbox, retry, backoff, cooldown, daemon, or session reconstruction.
+
+The production encoder uses the byte-identical [native schema mirror](../contracts/telemetry/runtime-aggregate-v1.schema.json).
+[The synthetic fixture](../tests/fixtures/runtime-metrics-native-batches.json) pins its
+SHA-256 and exact one-shot stdin bytes. No old intake fallback is used. These are
+fake-subprocess tests, not a live collector or deployment verification.
+
+## Runtime usage flow
+
+1. A finalized primary assistant message or child completion supplies available usage.
+   Child-host extensions do not independently consume primary usage.
+2. Pi builds event-local sanitized rows, not cumulative session totals. An occupied
+   attempt slot discards the event; it never queues it for later.
+3. One cancellable immediate defers binary verification and subprocess launch beyond
+   the provider callback. The native command owns fresh policy and exactly one POST.
+4. Only `stored`, `duplicate`, `discarded`, or `disabled` results are recognized.
+   All are terminal. `stored` and `duplicate` reflect collector acknowledgement,
+   not client persistence; Pi retains nothing and never retries.
+
+There is no policy or capability subprocess before send, and no ingest or flush call.
+The packaged binary is verified; development overrides are refused for runtime usage.
+Missing binaries and unsupported commands discard without installation or fallback.
+
+Replacement and shutdown cancel an unstarted attempt or request termination of its
+child immediately, without a wait loop or final send. The process slot remains busy
+until actual close, preventing overlap even if a cancelled process is slow to exit.
+A one-second process timeout requests termination; it is not a retry timer or a hard
+bound on synchronous binary verification or event-loop stalls.
+
+## Data and source limits
+
+Wire fields are the schema/registry, host, public model with evidence, available
+selected/effective effort, orchestrator or known built-in subagent class, source
+launch/response occurrence coverage, six token coverages, explicitly reported typed
+duration, and a sanitized error category. Occurrences never represent sessions.
+Prompts, responses, code, paths, private names, source IDs, and raw errors never enter
+the payload. There is no `batch_id`; native creates the remote `delivery_id`.
+
+One event produces 1–32 rows within 16 KiB. Oversized or invalid events discard
+whole rather than splitting into multiple sends. Child launch selection is a separate
+row with zero response-token coverage, never substituted for per-response evidence.
+
+- Token coverage distinguishes reported, unavailable, and unsupported values. Pi's
+  SDK-positive counters are usable; zero defaults and absence do not prove reported zero.
+- Selected model/effort is captured at the request hook, separately from response
+  model and effective-effort evidence. Ambiguous request sequences discard selection.
+- Pi hooks do not correlate requests/retries reliably, so this adapter does not infer duration.
+- Child configuration classification uses packaged built-in definitions, not agent names.
+  Launch configuration is not proof of the model or selected effort of each child response.
+- Bounded live child observations remain in RAM until completion. No completed child
+  event is retained for forwarding. A completion without usage creates no usage send.
+- Primary object deduplication uses weak tombstones; copied objects are distinct.
+  Child completion tombstones are capped at 256 per extension session. Source IDs
+  stay local and are never exported. No session history is read or reconstructed.
 
 ## What Gentle Pi does
 

package/docs/windows-startup-console-visibility.md

@@ -0,0 +1,18 @@
+# Windows Startup Console Capture
+
+Use this protocol to validate the startup Git child processes on a real Windows desktop. Linux CI can verify spawn configuration but cannot observe Windows console windows.
+
+## Capture
+
+1. Start a Windows window-event trace before launching Pi. Capture `EVENT_OBJECT_SHOW`, its timestamp, HWND, owner PID, and owner session.
+2. Deliberately launch a known visible, short-lived console as a positive control. If its show event is absent, the capture is **INCONCLUSIVE**.
+3. Build or install the candidate Gentle Pi package and start `pi` from a repository whose path contains spaces. Leave it idle for at least 10 seconds so the startup identity lookups (`git rev-parse --show-toplevel` and `git rev-parse --git-common-dir`), branch lookup, initial shell scan, and repeated poll run.
+4. Correlate each show event with `GetWindowThreadProcessId`, then use its timestamp, host PID/session, and Procmon process-creation ancestry and command line to associate it with a Pi-launched Git invocation. The HWND can be owned by `conhost.exe`, OpenConsole, or Windows Terminal rather than `git.exe`.
+
+## Expected Result
+
+No `WS_VISIBLE` show event is associated with the Git invocation for the startup identity lookups, banner branch lookup, initial shell scan, or repeated shell polling. A visible show event proves window visibility, not that it was unobscured on screen. Process start alone is not visible-window evidence. If event-to-invocation association cannot be established, report **INCONCLUSIVE**, not pass.
+
+## Scope
+
+This protocol does not cover user-configured external editors. Their inherited-stdio launch is intentional and may open a visible window.

package/extensions/ask-user-choice.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { Container, Input, isKeyRelease, matchesKey, Text, type KeybindingsManager, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
 import { NativeChoiceList } from "../lib/native-choice-list.ts";
 import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
@@ -25,6 +25,9 @@ const ChoiceParamsSchema = Type.Object(
 			maxItems: 4,
 			description: "Two to four ordered closed options",
 		}),
+		allowCustomResponse: Type.Optional(Type.Boolean({
+			description: "Opt in to an Other… free-text response. Never enable for provider-owned consent prompts, maintenance authorizations, or any exact opaque-token decision.",
+		})),
 	},
 	{ additionalProperties: false },
 );
@@ -42,9 +45,108 @@ interface ChoiceDetails {
 	question: string;
 	options: ChoiceOption[];
 	selection?: ChoiceSelection;
+	customResponse?: string;
 	cancelled?: true;
 }
 
+type ChoiceResult = ChoiceSelection | { customResponse: string };
+
+class CustomResponseEditor extends Container {
+	private readonly input = new Input({ prompt: "> ", placeholder: "Type your response" });
+	private readonly validationText = new Text("", 1, 0);
+	private readonly keybindings: KeybindingsManager | undefined;
+	private readonly onSubmit: (value: string) => void;
+	private readonly onCancel: () => void;
+
+	constructor(
+		keybindings: KeybindingsManager | undefined,
+		onSubmit: (value: string) => void,
+		onCancel: () => void,
+	) {
+		super();
+		this.keybindings = keybindings;
+		this.onSubmit = onSubmit;
+		this.onCancel = onCancel;
+		this.input.focused = true;
+		this.addChild(new Text("Custom response", 1, 0));
+		this.addChild(this.input);
+		this.addChild(this.validationText);
+		this.addChild(new Text("Submit to continue • Cancel to return to choices", 1, 0));
+	}
+
+	handleInput(data: string): void {
+		if (isKeyRelease(data)) return;
+		if (this.matches(data, "tui.select.cancel")) {
+			this.onCancel();
+			return;
+		}
+		if (this.matches(data, "tui.input.submit")) {
+			const value = this.input.getValue();
+			if (value.trim().length > 0) this.onSubmit(value);
+			else this.validationText.setText("Response cannot be empty.");
+			this.invalidate();
+			return;
+		}
+		if (this.matches(data, "tui.editor.deleteCharBackward")) {
+			this.input.handleInput(data);
+			this.validationText.setText("");
+			this.invalidate();
+			return;
+		}
+		this.input.handleInput(data);
+		this.validationText.setText("");
+		this.invalidate();
+	}
+
+	private matches(
+		data: string,
+		binding: "tui.select.cancel" | "tui.input.submit" | "tui.editor.deleteCharBackward",
+	): boolean {
+		if (this.keybindings?.matches) return this.keybindings.matches(data, binding);
+		const key = binding === "tui.select.cancel" ? "escape"
+			: binding === "tui.input.submit" ? "enter" : "backspace";
+		return matchesKey(data, key);
+	}
+}
+
+class ChoiceModeView extends Container {
+	private editing = false;
+	private readonly list: NativeChoiceList<{ id: string; label: string; description: string }>;
+	private readonly editor: CustomResponseEditor;
+
+	constructor(
+		list: NativeChoiceList<{ id: string; label: string; description: string }>,
+		editor: CustomResponseEditor,
+	) {
+		super();
+		this.list = list;
+		this.editor = editor;
+	}
+
+	showEditor(): void {
+		this.editing = true;
+		this.invalidate();
+	}
+
+	showList(): void {
+		this.editing = false;
+		this.invalidate();
+	}
+
+	handleInput(data: string): void {
+		if (this.editing) this.editor.handleInput(data);
+		else this.list.handleInput(data);
+	}
+
+	override handleMouse(event: TuiMouseEvent) {
+		return this.editing ? undefined : this.list.handleMouse(event);
+	}
+
+	override render(width: number): string[] {
+		return (this.editing ? this.editor : this.list).render(width);
+	}
+}
+
 function reconcileToolAvailability(pi: ExtensionAPI, interactiveTui: boolean): void {
 	const active = pi.getActiveTools();
 	const isActive = active.includes(CHOICE_TOOL_NAME);
@@ -62,10 +164,12 @@ function resultDetails(params: ChoiceParams): ChoiceDetails {
 export default function askUserChoice(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: CHOICE_TOOL_NAME,
+		renderShell: "self",
 		label: "Ask User Choice",
-		description: "Ask one strictly closed single-select question with two to four ordered options. It never accepts free-text or multiple selections.",
+		description: "Ask one single-select question with two to four ordered options. A custom response is available only when allowCustomResponse is explicitly enabled.",
 		promptGuidelines: [
-			"Use ask_user_choice only for one exactly representable closed single-select question with 2-4 ordered options; never use it for free-text or multi-select input.",
+			"Use ask_user_choice only for one exactly representable single-select question with 2-4 ordered options. Enable allowCustomResponse only when free text is safe and intended.",
+			"Never enable allowCustomResponse for provider-owned consent prompts, maintenance authorizations, or any decision that requires an exact opaque token.",
 		],
 		parameters: ChoiceParamsSchema,
 		executionMode: "sequential",
@@ -79,37 +183,54 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 				label: option.label,
 				description: option.description,
 			}));
-			let selection: ChoiceSelection | undefined;
+			const customItemId = "choice-custom-response";
+			if (params.allowCustomResponse === true) {
+				items.push({ id: customItemId, label: "Other…", description: "Provide a custom response" });
+			}
+			let selection: ChoiceResult | undefined;
 			try {
 				pi.events.emit(ASK_USER_CHOICE_BLOCKED_EVENT, { active: true });
-				selection = await ctx.ui.custom<ChoiceSelection | undefined>((tui, theme, keybindings, done) => {
+				selection = await ctx.ui.custom<ChoiceResult | undefined>((tui, theme, keybindings, done) => {
 					const list = new NativeChoiceList(items, {
 						selectedPrefix: (text) => theme.fg("accent", text),
 						selectedText: (text) => theme.fg("accent", text),
 						description: (text) => theme.fg("muted", text),
 						hoverBackground: (text) => theme.bg("toolPendingBg", text),
 					}, keybindings);
-					const container = createNativeFullscreenInteraction({
-						keyboardTarget: list,
-						requestRender: () => tui.requestRender(),
-						mouseObserver: list.createMouseObserver(() => tui.requestRender()),
-					});
 					let completed = false;
-					const finish = (result: ChoiceSelection | undefined) => {
+					const finish = (result: ChoiceResult | undefined) => {
 						if (completed) return;
 						completed = true;
 						list.setDisabled(true);
 						done(result);
 					};
+					let view: ChoiceModeView;
+					const editor = new CustomResponseEditor(
+						keybindings,
+						(value) => finish({ customResponse: value }),
+						() => view.showList(),
+					);
+					view = new ChoiceModeView(list, editor);
+					const container = createNativeFullscreenInteraction({
+						keyboardTarget: view,
+						requestRender: () => tui.requestRender(),
+						mouseObserver: list.createMouseObserver(() => tui.requestRender()),
+					});
 					list.onSelect = (item) => {
-						const index = items.indexOf(item);
-						const option = params.options[index];
-						if (option) finish({ value: option.value, label: option.label, index: index + 1 });
+						if (item.id === customItemId) {
+							view.showEditor();
+							tui.requestRender();
+						}
+						else {
+							const index = items.indexOf(item);
+							const option = params.options[index];
+							if (option) finish({ value: option.value, label: option.label, index: index + 1 });
+						}
 					};
 					list.onCancel = () => finish(undefined);
 					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
 					container.addChild(new Text(theme.fg("accent", theme.bold(params.question)), 1, 0));
-					container.addChild(list);
+					container.addChild(view);
 					container.addChild(new Text(theme.fg("dim", "↑↓ navigate • Enter select • Esc cancel"), 1, 0));
 					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
 					return container;
@@ -124,6 +245,12 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 					details: { ...resultDetails(params), cancelled: true },
 				};
 			}
+			if ("customResponse" in selection) {
+				return {
+					content: [{ type: "text", text: `User responded: ${selection.customResponse}` }],
+					details: { ...resultDetails(params), customResponse: selection.customResponse },
+				};
+			}
 			return {
 				content: [{ type: "text", text: `User selected: ${selection.index}. ${selection.label} (value: ${selection.value})` }],
 				details: { ...resultDetails(params), selection },
@@ -147,6 +274,7 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 			if (details?.selection) {
 				return new Text(theme.fg("success", `✓ ${details.selection.index}. ${details.selection.label}`), 0, 0);
 			}
+			if (details?.customResponse !== undefined) return new Text(theme.fg("success", "✓ Custom response"), 0, 0);
 			return new Text(theme.fg("warning", "Cancelled"), 0, 0);
 		},
 	});

package/extensions/codegraph-tools.ts

@@ -278,6 +278,7 @@ const runCodeGraphCommand: CodeGraphRunner = async (args, options) => {
 export function createCodeGraphTool(runner: CodeGraphRunner = runCodeGraphCommand) {
 	return {
 		name: "codegraph",
+		renderShell: "self" as const,
 		label: "CodeGraph",
 		description:
 			"Initialize, search, or explore the CodeGraph index for the current Pi workspace only. This tool never accepts a project path or shell command.",