pi-grok-agent 0.1.0

package/src/model/hooks.ts

@@ -0,0 +1,154 @@
+// Grok client hooks (x.ai/hooks) for the model provider. Grok keeps executing on its own harness;
+// these run on Pi's side around each native call:
+//   pre_tool_use  -> gate: mirror Pi's tool capabilities onto Grok's tools, plus configured deny/allow
+//   post_tool_use -> enrich: run a check after an edit and hand Grok the findings as additionalContext
+//   stop          -> hold: run an acceptance command; non-zero output blocks the stop with a reason
+import { execFile } from 'node:child_process';
+import type { HookSettings } from '../config.ts';
+
+export type HookRun = {
+  hookCallbackId: string;
+  hookEventName: 'pre_tool_use' | 'post_tool_use' | 'stop' | string;
+  sessionId: string;
+  cwd: string;
+  toolName?: string;
+  toolUseId?: string;
+  toolInput?: unknown;
+  toolResult?: unknown;
+  durationMs?: number;
+  reason?: string;
+  stopHookActive?: boolean;
+  lastAssistantMessage?: string;
+};
+export type HookReply = { decision?: 'continue' | 'deny' | 'block'; reason?: string; additionalContext?: string; continue?: boolean; stopReason?: string };
+
+/**
+ * Grok stamps every `tool_call` with `_meta["x.ai/tool"]`: its canonical kind (snake_case `ToolKind`) and a
+ * `read_only` flag, both exhaustive on Grok's side. That is the primary classification. The name table below is
+ * the fallback for calls that arrive without a stamp.
+ */
+export type GrokToolStamp = { name?: string; kind?: string; read_only?: boolean; namespace?: string };
+export type Capability = 'read' | 'write' | 'shell' | 'mcp' | 'other';
+const KIND_CAPABILITY: Record<string, Capability> = {
+  read: 'read', search: 'read', list_dir: 'read', list: 'read', lsp: 'read', memory_search: 'read', memory_get: 'read',
+  edit: 'write', write: 'write', delete: 'write', move: 'write',
+  execute: 'shell',
+  // MCP and plugin tools dispatch through `use_tool`; the hook's toolName is the qualified `server__tool`.
+  // Grok stamps the dispatcher as mutating and does not forward the server's readOnlyHint, so Pi cannot tell.
+  use_tool: 'mcp', search_tool: 'read',
+};
+/** `server__tool` -> server name, for MCP-dispatched calls. */
+export function mcpServerOf(tool: string): string | undefined {
+  const i = tool.indexOf('__');
+  return i > 0 ? tool.slice(0, i) : undefined;
+}
+/** Grok native tool names by the Pi capability they need (fallback when no stamp is available). */
+export const GROK_TOOL_CLASSES = {
+  read: /^(hashline_read|read_file|read|list_dir|ls|hashline_grep|grep|glob|search_tool|codebase_search)$/,
+  write: /^(hashline_edit|search_replace|edit|apply_patch|write|write_file|delete_file|move_file)$/,
+  shell: /^(run_terminal_command|run_terminal_cmd|bash)$/,
+};
+/** Capability a Grok call needs: stamp kind first, then the name table, then `other`. */
+export function classify(tool: string, stamp?: GrokToolStamp): Capability {
+  if (stamp?.kind && KIND_CAPABILITY[stamp.kind]) return KIND_CAPABILITY[stamp.kind];
+  if (GROK_TOOL_CLASSES.write.test(tool)) return 'write';
+  if (GROK_TOOL_CLASSES.shell.test(tool)) return 'shell';
+  if (GROK_TOOL_CLASSES.read.test(tool)) return 'read';
+  if (mcpServerOf(tool)) return 'mcp';
+  return 'other';
+}
+
+export type PiCapabilities = { read: boolean; write: boolean; shell: boolean };
+
+/** What Pi's own loop may do, from the tool list Pi handed the model. */
+export function capabilitiesFrom(piToolNames: string[]): PiCapabilities {
+  const has = (n: string) => piToolNames.includes(n);
+  return { read: has('read') || has('grep') || has('find') || has('ls'), write: has('edit') || has('write'), shell: has('bash') };
+}
+
+function matchesAny(patterns: string[] | undefined, name: string): boolean {
+  return (patterns ?? []).some((p) => { try { return new RegExp(`^(?:${p})$`).test(name); } catch { return p === name; } });
+}
+
+export type Verdict = { allow: true } | { allow: false; reason: string };
+
+/**
+ * pre_tool_use: deny when Pi itself may not do this, or when configured.
+ * An explicit deny wins over an allow entry; an allow entry wins over the capability mirror.
+ */
+/** Read-only marker a server can place in a tool's `_meta` (Grok forwards `_meta`, not `annotations`). */
+export function metaSaysReadOnly(meta: unknown): boolean {
+  const m = (meta ?? {}) as Record<string, unknown>;
+  const hint = m.readOnlyHint ?? m['pi/readOnly'] ?? (m.annotations as Record<string, unknown> | undefined)?.readOnlyHint;
+  return hint === true;
+}
+
+export function capabilityGate(piToolNames: string[], settings: HookSettings, toolMeta?: (tool: string) => unknown): (tool: string, stamp?: GrokToolStamp) => Verdict {
+  const caps = capabilitiesFrom(piToolNames);
+  return (tool, stamp) => {
+    if (matchesAny(settings.denyGrokTools, tool)) return { allow: false, reason: `Pi policy denies ${tool} in this session.` };
+    if (matchesAny(settings.allowGrokTools, tool)) return { allow: true };
+    const need = classify(tool, stamp);
+    if (need === 'write' && !caps.write) return { allow: false, reason: 'This Pi session is read-only: no file edits or writes. Report findings instead.' };
+    if (need === 'shell' && !caps.shell) return { allow: false, reason: 'This Pi session has no shell access. Use file and search tools instead.' };
+    if (need === 'read' && !caps.read) return { allow: false, reason: 'This Pi session cannot read files.' };
+    if (need === 'mcp' && !caps.write && !caps.shell) {
+      if (metaSaysReadOnly(toolMeta?.(tool))) return { allow: true };
+      const server = mcpServerOf(tool) ?? '';
+      if (matchesAny(settings.mcpReadOnlyServers, server)) return { allow: true };
+      return { allow: false, reason: `This Pi session is read-only and cannot verify that MCP tool ${tool} only reads. Report what you would call instead.` };
+    }
+    // A stamped kind we do not classify (task, workflow, deploy_app, ...) that Grok itself marks as mutating:
+    // in a read-only Pi session that is still a workspace or external mutation, so deny it.
+    if (need === 'other' && stamp && stamp.read_only === false && !caps.write && !caps.shell) return { allow: false, reason: `This Pi session is read-only; ${tool} (${stamp.kind ?? 'unknown kind'}) can mutate state.` };
+    return { allow: true };
+  };
+}
+
+/** The file a Grok edit call targets, from its input. */
+export function editedFile(input: unknown): string | undefined {
+  const i = (input ?? {}) as Record<string, unknown>;
+  return [i.file_path, i.target_file, i.path, i.absolute_path].find((v): v is string => typeof v === 'string');
+}
+
+// Syntax-only TypeScript check: strip types with Node's own stripper, then parse as an ES module without running it.
+const TS_SYNTAX_CHECK = 'const {stripTypeScriptTypes}=require("node:module");const vm=require("node:vm");new vm.SourceTextModule(stripTypeScriptTypes(require("fs").readFileSync(process.argv[1],"utf8")))';
+const BUILTIN_CHECKS: { test: RegExp; command: string[] }[] = [
+  { test: /\.(ts|mts|cts)$/, command: ['node', '--no-warnings', '--experimental-vm-modules', '-e', TS_SYNTAX_CHECK, '{file}'] },
+  { test: /\.(js|mjs|cjs)$/, command: ['node', '--check', '{file}'] },
+  { test: /\.py$/, command: ['python3', '-m', 'py_compile', '{file}'] },
+  { test: /\.json$/, command: ['node', '-e', 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))', '{file}'] },
+  { test: /\.rs$/, command: ['rustfmt', '--check', '--edition', '2021', '{file}'] },
+];
+
+export type RunResult = { ok: boolean; output: string; command: string };
+
+export function run(argv: string[], cwd: string, timeoutMs = 120_000): Promise<RunResult> {
+  return new Promise((resolve) => {
+    execFile(argv[0], argv.slice(1), { cwd, timeout: timeoutMs, maxBuffer: 1 << 20 }, (error, stdout, stderr) => {
+      const output = `${stdout}${stderr}`.trim();
+      resolve({ ok: !error, output: error && !output ? String(error.message) : output, command: argv.join(' ') });
+    });
+  });
+}
+
+/** post_tool_use after an edit: built-in syntax check or the configured command. Findings are returned as text for additionalContext. */
+export async function postEditContext(input: unknown, cwd: string, settings: HookSettings): Promise<string | undefined> {
+  const file = editedFile(input);
+  if (!file) return undefined;
+  let argv: string[] | undefined;
+  if (settings.postEditCheck) argv = ['bash', '-lc', settings.postEditCheck.replaceAll('{file}', file)];
+  else { const builtin = BUILTIN_CHECKS.find((c) => c.test.test(file)); if (builtin) argv = builtin.command.map((a) => a.replaceAll('{file}', file)); }
+  if (!argv) return undefined;
+  const result = await run(argv, cwd);
+  if (result.ok) return undefined;
+  return `Check failed after editing ${file} (${result.command}):\n${result.output.slice(0, 4000)}`;
+}
+
+/** stop: run the acceptance command; non-zero blocks the stop with the output as the reason. */
+export async function stopGate(event: HookRun, settings: HookSettings): Promise<HookReply> {
+  if (!settings.stopCheck || event.reason !== 'end_turn') return { decision: 'continue' };
+  const result = await run(['bash', '-lc', settings.stopCheck], event.cwd, 600_000);
+  if (result.ok) return { decision: 'continue' };
+  return { decision: 'block', reason: `Acceptance check failed (${settings.stopCheck}):\n${result.output.slice(0, 8000)}\nFix the cause, rerun the check, then finish.` };
+}

package/src/model/permissions.ts

@@ -0,0 +1,43 @@
+// Answers Grok's native permission prompts for the model provider.
+// Interactive Pi: the existing dialog. Headless Pi: a configured policy, never a silent allow by default.
+import type { RequestPermissionRequest, RequestPermissionResponse } from '@agentclientprotocol/sdk';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { HeadlessPermissionPolicy } from '../config.ts';
+
+type Answer = (request: RequestPermissionRequest) => Promise<RequestPermissionResponse>;
+
+/** Interactive: Grok's permission prompt as a Pi selection dialog. Dismissal cancels; Grok treats that as a rejection. */
+export function permissionDialog(ctx: Pick<ExtensionContext, 'hasUI' | 'ui'>): Answer {
+  return async (request) => {
+    if (!ctx.hasUI) return { outcome: { outcome: 'cancelled' } };
+    const labels = request.options.map((option, i) => `${i + 1}. ${option.name} (${option.kind})`);
+    const details = JSON.stringify(request.toolCall.rawInput ?? {}, null, 2).slice(0, 4000);
+    const selected = await ctx.ui.select(`Grok: ${request.toolCall.title}\n${details}`, labels);
+    const index = selected === undefined ? -1 : labels.indexOf(selected);
+    if (index < 0) return { outcome: { outcome: 'cancelled' } };
+    return { outcome: { outcome: 'selected', optionId: request.options[index].optionId } };
+  };
+}
+
+const READ_KINDS = new Set(['read', 'search', 'fetch', 'think']);
+
+function pick(request: RequestPermissionRequest, kind: 'allow_once' | 'reject_once'): RequestPermissionResponse {
+  const option = request.options.find((o) => o.kind === kind) ?? request.options.find((o) => o.kind.startsWith(kind.split('_')[0]));
+  return option ? { outcome: { outcome: 'selected', optionId: option.optionId } } : { outcome: { outcome: 'cancelled' } };
+}
+
+export function headlessPermission(policy: HeadlessPermissionPolicy): Answer {
+  return async (request) => {
+    switch (policy) {
+      case 'allow': return pick(request, 'allow_once');
+      case 'reads': return READ_KINDS.has(request.toolCall.kind ?? 'other') ? pick(request, 'allow_once') : pick(request, 'reject_once');
+      case 'deny': return pick(request, 'reject_once');
+      default: return { outcome: { outcome: 'cancelled' } };
+    }
+  };
+}
+
+/** Use the dialog when Pi has a UI; otherwise the headless policy. */
+export function permissionAnswer(hasUI: boolean, dialog: Answer, policy: HeadlessPermissionPolicy): Answer {
+  return hasUI ? dialog : headlessPermission(policy);
+}

package/src/model/provider.ts

@@ -0,0 +1,243 @@
+// Grok Build as a Pi model. Grok runs its own harness: native tools, permissions, subagents.
+// Pi drives turns, shows the stream, and can lend extra tools through Grok's client-hosted
+// MCP channel; those are the only tool calls that reach Pi's executor.
+import { createAssistantMessageEventStream, getCurrentSystemPrompt, getCurrentTools, type AssistantMessage, type AssistantMessageEventStream, type Message, type Model, type Api, type SimpleStreamOptions, type ToolCall, type ToolResultMessage, type TranscriptContext, type Usage } from '@earendil-works/pi-ai';
+import type { GrokModelConnection } from './connection.ts';
+import { GrokModelSession, type TurnEvent, type GrokTurnUsage } from './session.ts';
+import { selectPiTools, type PiToolPolicy } from '../config.ts';
+
+/** Same marker as model.ts; kept here to avoid importing the extension entry from the provider. */
+const GROK_DISPLAY_ONLY = '\u200b[grok-display]';
+/** pi-agent-core presents custom messages (ours and other extensions') to the model as user messages. Ours carry a marker. */
+function isDisplayOnly(m: Message): boolean {
+  if (m.role !== 'user') return false;
+  const first = typeof m.content === 'string' ? m.content : m.content.find((c) => c.type === 'text')?.text ?? '';
+  return first.startsWith(GROK_DISPLAY_ONLY);
+}
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Grok's ACP accepts image blocks but does not see them (promptCapabilities.image: false, verified: a red 1x1 PNG
+// answered "Unknown"). Given a file path it reads the image with its own tools and answers correctly, so inbound
+// images become temp files referenced from the prompt text.
+const IMAGE_DIR = join(tmpdir(), 'pi-grok-images');
+/**
+ * Write an attached image block to a temp file (0600) and return its path, so Grok (which cannot see ACP
+ * image blocks) can read it with its own file tools. Content-addressed: the same bytes reuse the same file.
+ */
+export function spillImageFile(data: string, mimeType: string): string {
+  mkdirSync(IMAGE_DIR, { recursive: true, mode: 0o700 });
+  const ext = mimeType.split('/')[1]?.replace('jpeg', 'jpg') || 'bin';
+  const file = join(IMAGE_DIR, `${createHash('sha256').update(data).digest('hex').slice(0, 16)}.${ext}`);
+  try { writeFileSync(file, Buffer.from(data, 'base64'), { flag: 'wx', mode: 0o600 }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; }
+  return file;
+}
+
+export const GROK_API = 'grok-acp' as Api;
+export const MODEL_IDS = ['grok-4.7', 'grok-4.7-build-fast', 'grok-4.6', 'grok-4.5'];
+const BATCH_GRACE_MS = 150;
+const PREAMBLE_LIMIT = 60_000;
+
+export interface SessionResolver { current(): GrokModelSession | undefined; piTools?: PiToolPolicy; }
+
+function zeroUsage(): Usage { return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }; }
+
+/**
+ * Pi usage from Grok's `turn_completed` accounting. Grok's `inputTokens` includes the cached portion
+ * (per-sample frames show input_tokens + cache_read_input_tokens = turn inputTokens); Pi keeps them apart.
+ * Cost is what Grok reports (USD ticks / 1e9), attributed to input since Grok gives one number per turn.
+ */
+function usageFrom(turn: GrokTurnUsage | undefined): Usage {
+  const usage = zeroUsage();
+  if (!turn) return usage;
+  usage.cacheRead = turn.cachedReadTokens;
+  usage.cacheWrite = turn.cacheCreationTokens;
+  usage.input = Math.max(0, turn.inputTokens - turn.cachedReadTokens - turn.cacheCreationTokens);
+  usage.output = turn.outputTokens;
+  // Pi's context token calculation uses message.usage.totalTokens as the active conversation context size.
+  // Grok's turn_completed accounting is cumulative across all sub-calls in the turn (which can sum to >500k),
+  // whereas turn.contextTokens (from session/prompt response _meta.totalTokens) is Grok's actual context window size.
+  usage.totalTokens = turn.contextTokens ?? (usage.input + usage.output + usage.cacheRead + usage.cacheWrite);
+  usage.cost = { input: turn.costUsd, output: 0, cacheRead: 0, cacheWrite: 0, total: turn.costUsd };
+  return usage;
+}
+
+/** Messages after the last assistant message: the new user input and/or tool results. */
+/**
+ * Messages after the last assistant message, keeping only what is input to Grok: user messages and tool
+ * results. Custom messages (our own `grok-media`, `grok-command`, other extensions' notes) are Pi-side display
+ * and never become prompt text; otherwise Grok would be told the image it just generated was "attached" and
+ * read it back, which Grok Build itself never does.
+ */
+export function splitTail(messages: Message[]): { history: Message[]; tail: Message[] } {
+  let last = -1;
+  for (let i = messages.length - 1; i >= 0; i--) if (messages[i].role === 'assistant') { last = i; break; }
+  const tail = messages.slice(last + 1).filter((m) => (m.role === 'user' && !isDisplayOnly(m)) || m.role === 'toolResult');
+  return { history: messages.slice(0, last + 1), tail };
+}
+
+function textOf(content: string | { type: string; text?: string; data?: string; mimeType?: string }[]): string {
+  if (typeof content === 'string') return content;
+  return content.map((c) => {
+    if (c.type === 'text') return c.text ?? '';
+    if (c.type === 'image' && c.data) { try { return `\n[attached image: ${spillImageFile(c.data, c.mimeType ?? 'image/png')} — read this file to view it]\n`; } catch { return '[image]'; } }
+    return `[${c.type}]`;
+  }).join('');
+}
+
+/** Render prior conversation for a fresh Grok session that has no history of its own. */
+export function renderPreamble(history: Message[]): string {
+  const lines: string[] = [];
+  for (const m of history) {
+    if (m.role === 'user') lines.push(`[user]\n${textOf(m.content)}`);
+    else if (m.role === 'assistant') {
+      const text = m.content.filter((c) => c.type === 'text').map((c) => (c as { text: string }).text).join('');
+      const calls = m.content.filter((c) => c.type === 'toolCall').map((c) => { const t = c as ToolCall; return `${t.name}(${JSON.stringify(t.arguments)})`; });
+      lines.push(`[assistant]\n${text}${calls.length ? `\n[tool calls] ${calls.join('; ')}` : ''}`);
+    } else if (m.role === 'toolResult') lines.push(`[tool result ${m.toolName}]\n${textOf(m.content)}`);
+  }
+  let text = lines.join('\n\n');
+  if (text.length > PREAMBLE_LIMIT) text = '…' + text.slice(-PREAMBLE_LIMIT);
+  return text;
+}
+
+export function promptTextFor(tail: Message[], orphans: ToolResultMessage[], preamble?: string): string {
+  const parts: string[] = [];
+  if (preamble) parts.push(`Conversation so far (Pi transcript):\n\n${preamble}\n\n---`);
+  for (const r of orphans) parts.push(`[tool result ${r.toolName}${r.isError ? ' (error)' : ''}]\n${textOf(r.content)}`);
+  for (const m of tail) if (m.role === 'user') parts.push(textOf(m.content));
+  return parts.join('\n\n');
+}
+
+export function createGrokStream(connection: GrokModelConnection, sessions: SessionResolver) {
+  return function streamGrok(model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions): AssistantMessageEventStream {
+    const stream = createAssistantMessageEventStream();
+    const signal = options?.signal;
+    const message: AssistantMessage = { role: 'assistant', content: [], api: model.api, provider: model.provider, model: model.id, usage: zeroUsage(), stopReason: 'pending', timestamp: Date.now() };
+    const fail = (reason: 'error' | 'aborted', text: string) => {
+      message.stopReason = reason; message.errorMessage = text;
+      stream.push({ type: 'error', reason, error: message }); stream.end(message);
+    };
+    (async () => {
+      const session = sessions.current();
+      if (!session) throw new Error('No active Pi session for the Grok model provider.');
+      await connection.open(signal);
+      const isNew = !session.grokSessionId;
+      const piTools = getCurrentTools(context.messages);
+      session.piToolNames = piTools.map((t) => t.name);
+      session.tools = selectPiTools(piTools, sessions.piTools ?? 'extensions');
+      await session.attach(getCurrentSystemPrompt(context.messages) || undefined);
+      await session.applyEffort(options?.reasoning); // Pi's thinking level drives Grok's reasoning_effort
+      signal?.throwIfAborted();
+      const { history, tail } = splitTail(context.messages);
+      const results = tail.filter((m): m is ToolResultMessage => m.role === 'toolResult');
+      const orphans = session.promptActive ? session.resolveToolResults(results) : results;
+      if (!session.promptActive) {
+        const preamble = isNew && history.length ? renderPreamble(history) : undefined;
+        const text = promptTextFor(tail, orphans, preamble);
+        if (!text.trim()) throw new Error('Nothing to send to Grok: no user message or tool result after the last assistant message (custom messages are not prompt input).');
+        session.startPrompt(text);
+      } else if (orphans.length) {
+        // Results for calls Grok is not waiting on (e.g. after a restart). Let them reach Grok as text on the next prompt.
+        throw new Error(`Tool results ${orphans.map((o) => o.toolCallId).join(', ')} do not match any pending Grok tool call.`);
+      }
+      stream.push({ type: 'start', partial: message });
+      if (session.reconnected) {
+        const note = `[grok reconnected after: ${session.reconnected}; session ${session.grokSessionId} reloaded]\n`;
+        session.reconnected = undefined;
+        const index = message.content.push({ type: 'thinking', thinking: note }) - 1;
+        stream.push({ type: 'thinking_start', contentIndex: index, partial: message });
+        stream.push({ type: 'thinking_delta', contentIndex: index, delta: note, partial: message });
+        stream.push({ type: 'thinking_end', contentIndex: index, content: note, partial: message });
+      }
+      await new Promise<void>((resolve, reject) => {
+        let open: { type: 'text' | 'thinking'; index: number } | undefined;
+        let batchTimer: ReturnType<typeof setTimeout> | undefined;
+        let finished = false;
+        // Declared before consume(): consume() flushes buffered events synchronously, and a buffered completion
+        // could reach onAbort/finish (which call detach) before a `const` further down was initialized.
+        let detach: () => void = () => {};
+        const closeBlock = () => {
+          if (!open) return;
+          const block = message.content[open.index];
+          if (open.type === 'text') stream.push({ type: 'text_end', contentIndex: open.index, content: (block as { text: string }).text, partial: message });
+          else stream.push({ type: 'thinking_end', contentIndex: open.index, content: (block as { thinking: string }).thinking, partial: message });
+          open = undefined;
+        };
+        const finish = (reason: 'stop' | 'length' | 'toolUse') => {
+          if (finished) return; finished = true;
+          clearTimeout(batchTimer); detach(); signal?.removeEventListener('abort', onAbort);
+          closeBlock();
+          message.stopReason = reason;
+          stream.push({ type: 'done', reason, message }); stream.end(message); resolve();
+        };
+        const onAbort = () => {
+          if (finished) return; finished = true;
+          clearTimeout(batchTimer); detach();
+          session.rejectParked('Pi aborted the turn.');
+          session.abandonPrompt(); // cancels on Grok and frees the session for the next Pi message
+          closeBlock();
+          fail('aborted', 'Request was aborted'); resolve();
+        };
+        const onEvent = (event: TurnEvent) => {
+          if (finished) return;
+          switch (event.kind) {
+            case 'text':
+            case 'thought': {
+              const type = event.kind === 'text' ? 'text' : 'thinking';
+              if (open && open.type !== type) closeBlock();
+              if (!open) {
+                const index = message.content.push(type === 'text' ? { type: 'text', text: '' } : { type: 'thinking', thinking: '' }) - 1;
+                open = { type, index };
+                stream.push(type === 'text' ? { type: 'text_start', contentIndex: index, partial: message } : { type: 'thinking_start', contentIndex: index, partial: message });
+              }
+              const block = message.content[open.index] as { text?: string; thinking?: string };
+              if (type === 'text') { block.text! += event.delta; stream.push({ type: 'text_delta', contentIndex: open.index, delta: event.delta, partial: message }); }
+              else { block.thinking! += event.delta; stream.push({ type: 'thinking_delta', contentIndex: open.index, delta: event.delta, partial: message }); }
+              return;
+            }
+            case 'toolcall': {
+              closeBlock();
+              const toolCall: ToolCall = { type: 'toolCall', id: event.toolCallId, name: event.name, arguments: event.arguments as ToolCall['arguments'] };
+              const index = message.content.push(toolCall) - 1;
+              stream.push({ type: 'toolcall_start', contentIndex: index, partial: message });
+              stream.push({ type: 'toolcall_delta', contentIndex: index, delta: JSON.stringify(event.arguments), partial: message });
+              stream.push({ type: 'toolcall_end', contentIndex: index, toolCall, partial: message });
+              clearTimeout(batchTimer);
+              batchTimer = setTimeout(() => finish('toolUse'), BATCH_GRACE_MS);
+              return;
+            }
+            case 'complete': {
+              message.usage = usageFrom(event.usage);
+              message.rawStopReason = event.response.stopReason;
+              // Grok reports `cancelled` both for our session/cancel and for a rejected permission prompt.
+              // Only the former is a Pi abort; a rejected prompt is an ordinary end of turn Grok already narrated.
+              if (event.response.stopReason === 'cancelled') { if (signal?.aborted) onAbort(); else finish('stop'); return; }
+              finish(event.response.stopReason === 'max_tokens' ? 'length' : 'stop');
+              return;
+            }
+            case 'error': {
+              if (finished) return; finished = true;
+              detach(); signal?.removeEventListener('abort', onAbort);
+              closeBlock();
+              const dropped = /connection closed|socket|EPIPE|closed/i.test(event.error.message);
+              fail('error', dropped ? `Grok connection dropped mid-turn (${event.error.message}). Send the message again; the next turn reconnects and reloads the Grok session.` : event.error.message);
+              resolve();
+              return;
+            }
+          }
+        };
+        detach = session.consume(onEvent);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted) onAbort();
+        void reject;
+      });
+    })().catch((error) => {
+      const aborted = signal?.aborted || (error instanceof Error && error.name === 'AbortError');
+      fail(aborted ? 'aborted' : 'error', error instanceof Error ? error.message : String(error));
+    });
+    return stream;
+  };
+}

package/src/model/questions.ts

@@ -0,0 +1,65 @@
+// Grok's ask_user_question reaches the client as the ACP extension request `x.ai/ask_user_question`
+// (`_x.ai/ask_user_question` on the wire). The response is one of four outcomes Grok's tool already
+// understands; Pi maps them onto its own dialogs. No new outcome is invented.
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+
+export type QuestionOption = { label: string; description: string; preview?: string; id?: string };
+export type Question = { question: string; options: QuestionOption[]; multiSelect?: boolean; multi_select?: boolean };
+export type AskUserQuestionRequest = { sessionId: string; toolCallId: string; questions: Question[]; mode: 'default' | 'plan' };
+export type AskUserQuestionResponse =
+  | { outcome: 'accepted'; answers: Record<string, string[]>; annotations?: Record<string, { preview?: string; notes?: string }> }
+  | { outcome: 'chat_about_this'; partial_answers: Record<string, string> }
+  | { outcome: 'skip_interview'; partial_answers: Record<string, string> }
+  | { outcome: 'cancelled' };
+
+const OTHER = 'Other';
+const CHAT = 'Chat about this';
+const SKIP = 'Skip interview and plan immediately';
+const DONE = 'Done selecting';
+
+export type Answerer = (request: AskUserQuestionRequest) => Promise<AskUserQuestionResponse>;
+
+/** Interactive: one Pi dialog per question. Headless: cancelled, which Grok's tool reports to the model as unanswered. */
+export function questionAnswerer(ctx: Pick<ExtensionContext, 'hasUI' | 'ui'>): Answerer {
+  return async (request) => {
+    if (!ctx.hasUI) return { outcome: 'cancelled' };
+    const answers: Record<string, string[]> = {};
+    const annotations: Record<string, { preview?: string; notes?: string }> = {};
+    const partial = () => Object.fromEntries(Object.entries(answers).map(([q, a]) => [q, a[0] ?? OTHER]));
+    for (const [index, q] of request.questions.entries()) {
+      const multi = q.multiSelect === true || q.multi_select === true;
+      const title = `Grok asks (${index + 1}/${request.questions.length}): ${q.question}`;
+      const labels = q.options.map((o) => o.description ? `${o.label} — ${o.description}` : o.label);
+      const extras = [OTHER, ...(request.mode === 'plan' ? [CHAT, SKIP] : [])];
+      const byLabel = new Map(labels.map((l, i) => [l, q.options[i]]));
+      const picked: QuestionOption[] = [];
+      for (;;) {
+        const menu = multi ? [...labels.filter((l) => !picked.includes(byLabel.get(l)!)), ...(picked.length ? [DONE] : []), ...extras] : [...labels, ...extras];
+        const choice = await ctx.ui.select(picked.length ? `${title} (selected: ${picked.map((p) => p.label).join(', ')})` : title, menu);
+        if (choice === undefined) return { outcome: 'cancelled' };
+        if (choice === CHAT) return { outcome: 'chat_about_this', partial_answers: partial() };
+        if (choice === SKIP) return { outcome: 'skip_interview', partial_answers: partial() };
+        if (choice === DONE) break;
+        if (choice === OTHER) {
+          const notes = await ctx.ui.input('Your answer', 'Type a reply for Grok');
+          if (notes === undefined) return { outcome: 'cancelled' };
+          answers[q.question] = [OTHER];
+          annotations[q.question] = { notes };
+          picked.length = 0;
+          break;
+        }
+        const option = byLabel.get(choice);
+        if (!option) continue;
+        picked.push(option);
+        if (!multi) break;
+      }
+      if (picked.length) {
+        answers[q.question] = picked.map((p) => p.label);
+        if (!multi && picked[0].preview) annotations[q.question] = { preview: picked[0].preview };
+      }
+    }
+    const response: AskUserQuestionResponse = { outcome: 'accepted', answers };
+    if (Object.keys(annotations).length) response.annotations = annotations;
+    return response;
+  };
+}