@ssweens/pi-huddle 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssweens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# pi-huddle
+
+![Huddle mode — permission-gated exploration](screenshot.png)
+
+![ask_user — structured multi-question elicitation](ask-user-screenshot.png)
+
+```bash
+pi install @ssweens/pi-huddle
+```
+
+Huddle mode for [pi](https://github.com/badlogic/pi-mono). Safe exploration with permission gates, plus a powerful `ask_user` tool for structured multi-question elicitation. Toggle with `/huddle`, `/holup`, `/plan`, or `Alt+H`.
+
+## Features
+
+- **Huddle mode** — read-only by default; writes require your approval
+- **`ask_user` tool** — rich TUI dialog for structured elicitation (available in all modes)
+- **Permission gates** — approve or deny individual edit/write operations inline
+- **Bash allowlist** — safe commands execute freely, destructive ones prompt first
+- **Three commands** — `/huddle` (primary), `/holup`, `/plan` all toggle the mode
+- **`Alt+H` shortcut** — Option+H on Mac
+- **CLI flag** — `pi --plan` to start in huddle mode
+- **Session persistence** — huddle state survives session resume
+
+## Installation
+
+```bash
+pi install /path/to/pi-huddle
+
+# Or project-local
+pi install -l /path/to/pi-huddle
+```
+
+## Usage
+
+### Toggle Huddle Mode
+
+```
+/huddle              # primary command
+/holup               # alias
+/plan                # alias (backward compat)
+Alt+H (Option+H)     # keyboard shortcut
+```
+
+### Start in Huddle Mode
+
+```bash
+pi --huddle          # start pi directly in huddle mode
+pi --plan            # alias (backward compat)
+```
+
+### Workflow
+
+1. **Enter huddle mode** — `/huddle` or `Alt+H`
+2. **Use `ask_user`** — gather requirements and clarify before acting
+3. **Explore safely** — read, search, and analyze freely
+4. **Approve edits on demand** — each write operation requires approval
+5. **Exit when ready** — toggle off to restore full access
+
+---
+
+## ask_user Tool
+
+The `ask_user` tool is available **in all modes** — not just huddle. It presents a rich TUI dialog with one tab per question, numbered options, freeform text input, and a submit/review view.
+
+### Dialog UX
+
+```
+← □ Auth method  □ Library  ✓ Submit →
+
+Which auth approach should I use?
+
+  1. JWT tokens
+     Stateless, scales well, standard choice.
+  2. Session cookies
+     Simpler for server-rendered apps.
+  3. OAuth2 / OIDC
+     Best for third-party login integration.
+  4. API keys
+     Simplest for machine-to-machine auth.
+  5. |ype something.      ← freeform field, type immediately
+  ────────────────────────────────────────
+  6. Chat about this
+
+Enter to select · Tab/↑↓ to navigate · Esc to cancel
+```
+
+- **Tab bar** — `←`/`→` or `Tab`/`Shift+Tab` to navigate between questions and Submit
+- **Options** — `↑`/`↓` to move, `Enter` to select
+- **Freeform** — navigate to row 5, start typing immediately; `Enter` to confirm
+- **Chat about this** — tells the agent the user wants to discuss before deciding
+- **Submit view** — recap of all answers before final submission
+- **`multiSelect: true`** — `Space` or `Enter` to toggle, multiple selections allowed
+
+### Tool Call Example
+
+```json
+{
+  "questions": [
+    {
+      "question": "Which auth approach should I use?",
+      "header": "Auth method",
+      "options": [
+        {
+          "label": "JWT tokens (Recommended)",
+          "description": "Stateless, scales well, standard choice",
+          "markdown": "Authorization: Bearer <token>"
+        },
+        {
+          "label": "Session cookies",
+          "description": "Simpler for server-rendered apps"
+        },
+        {
+          "label": "OAuth2 / OIDC",
+          "description": "Best for third-party login integration"
+        }
+      ],
+      "multiSelect": false
+    },
+    {
+      "question": "Which features do you want to enable?",
+      "header": "Features",
+      "options": [
+        { "label": "Logging", "description": "Structured JSON logs" },
+        { "label": "Metrics", "description": "Prometheus /metrics endpoint" },
+        { "label": "Tracing", "description": "OpenTelemetry spans" },
+        { "label": "Alerts", "description": "PagerDuty integration" }
+      ],
+      "multiSelect": true
+    }
+  ]
+}
+```
+
+### Return Value
+
+```json
+{
+  "answers": {
+    "Which auth approach should I use?": "JWT tokens (Recommended)",
+    "Which features do you want to enable?": "Logging, Tracing"
+  },
+  "annotations": {},
+  "metadata": {}
+}
+```
+
+### Usage Notes
+
+- 1–4 questions per call
+- 2–4 options per question
+- `markdown` field shows a code preview when an option is focused
+- `multiSelect: true` for feature flags, configuration choices, etc.
+- Put "(Recommended)" at end of preferred option label
+- If user selects "Chat about this", agent should respond conversationally
+
+---
+
+## Permission Gates
+
+### ✅ Always Allowed
+
+| Tool | Description |
+|------|-------------|
+| `read` | Read file contents |
+| `bash` | Allowlisted safe commands |
+| `grep` | Search within files |
+| `find` | Find files |
+| `ls` | List directories |
+| `ask_user` | Structured elicitation |
+
+### ⚠️ Requires Permission
+
+- **`edit`** — file modifications
+- **`write`** — file creation/overwriting
+- **Non-allowlisted bash commands**
+
+### Permission Dialog
+
+```
+⚠ Huddle Mode — edit: /path/to/file.ts
+[Allow]  [Deny]  [Deny with feedback]
+```
+
+**Deny with feedback** sends the reason to the agent so it can adjust.
+
+### Safe Bash Commands (No Prompt)
+
+`cat`, `head`, `tail`, `grep`, `find`, `rg`, `fd`, `ls`, `pwd`, `tree`,
+`git status`, `git log`, `git diff`, `git branch`, `npm list`, `curl`, `jq`
+
+### Blocked Bash Commands (Prompt Required)
+
+`rm`, `mv`, `cp`, `mkdir`, `touch`, `git add`, `git commit`, `git push`,
+`npm install`, `yarn add`, `pip install`, `sudo`, `>`, `>>`
+
+---
+
+## Architecture
+
+```
+pi-huddle/
+├── package.json          # Package manifest
+├── extensions/
+│   ├── index.ts          # Commands, shortcuts, ask_user tool, permission gates
+│   └── lib/
+│       ├── ask-user-dialog.ts  # TUI dialog component
+│       └── utils.ts            # Bash command classification
+├── skills/
+│   └── huddle/
+│       └── SKILL.md      # Teaches the agent huddle mode behaviour
+├── LICENSE
+└── README.md
+```
+
+Two pi primitives:
+
+- **Extension** — registers `/huddle`, `/holup`, `/plan` commands, `Alt+H` shortcut, `ask_user` tool, permission gates, and context injection
+- **Skill** — documents huddle mode and `ask_user` behaviour so the agent knows how to use them
+
+## Development
+
+```bash
+/reload    # Hot-reload after editing
+/huddle    # Test huddle mode
+```
+
+## License
+
+[MIT](LICENSE)

package/extensions/index.ts

@@ -0,0 +1,325 @@
+/**
+ * Huddle Extension
+ *
+ * Safe exploration mode with permission gates for file modifications.
+ * Read-only by default; writes require user approval.
+ *
+ * Features:
+ * - /huddle, /holup, or /plan commands to toggle
+ * - Alt+P shortcut to toggle
+ * - Bash restricted to allowlisted commands (others prompt for permission)
+ * - edit/write tools prompt for permission during huddle mode
+ * - ask_user tool for structured elicitation during planning
+ */
+
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import type { TextContent } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { AskUserDialog, type AskUserDialogResult } from "./lib/ask-user-dialog.js";
+import { isSafeCommand } from "./lib/utils.js";
+
+// Tools
+const HUDDLE_MODE_TOOLS = ["read", "bash", "grep", "find", "ls", "ask_user"];
+const NORMAL_MODE_TOOLS = ["read", "bash", "edit", "write", "ask_user"];
+
+export default function huddleExtension(pi: ExtensionAPI): void {
+	let huddleEnabled = false;
+
+	pi.registerFlag("huddle", {
+		description: "Start in huddle mode (read-only exploration)",
+		type: "boolean",
+		default: false,
+	});
+
+	pi.registerFlag("plan", {
+		description: "Start in huddle mode (alias for --huddle)",
+		type: "boolean",
+		default: false,
+	});
+
+	function updateStatus(ctx: ExtensionContext): void {
+		if (huddleEnabled) {
+			ctx.ui.setStatus("huddle", ctx.ui.theme.fg("warning", "⏸ huddle"));
+		} else {
+			ctx.ui.setStatus("huddle", undefined);
+		}
+		ctx.ui.setWidget("plan-todos", undefined);
+	}
+
+	function toggleHuddle(ctx: ExtensionContext): void {
+		huddleEnabled = !huddleEnabled;
+
+		if (huddleEnabled) {
+			pi.setActiveTools(HUDDLE_MODE_TOOLS);
+			ctx.ui.notify(`Huddle mode enabled. Tools: ${HUDDLE_MODE_TOOLS.join(", ")}. Safe: cd, rg, fd, cat, git status/log/diff`);
+		} else {
+			pi.setActiveTools(NORMAL_MODE_TOOLS);
+			ctx.ui.notify("Huddle mode disabled. Full access restored.");
+		}
+		updateStatus(ctx);
+	}
+
+	// Primary command
+	pi.registerCommand("huddle", {
+		description: "Toggle huddle mode (read-only exploration + structured elicitation)",
+		handler: async (_args, ctx) => toggleHuddle(ctx),
+	});
+
+	// Aliases
+	pi.registerCommand("holup", {
+		description: "Toggle huddle mode (alias for /huddle)",
+		handler: async (_args, ctx) => toggleHuddle(ctx),
+	});
+
+	pi.registerCommand("plan", {
+		description: "Toggle huddle mode (alias for /huddle)",
+		handler: async (_args, ctx) => toggleHuddle(ctx),
+	});
+
+	pi.registerShortcut("alt+h", {
+		description: "Toggle huddle mode",
+		handler: async (ctx) => toggleHuddle(ctx),
+	});
+
+	// Ask User Question tool - structured elicitation
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask User Question",
+		description: `Use this tool when you need to ask the user questions during execution. This allows you to:
+- Gather user preferences or requirements
+- Clarify ambiguous instructions
+- Get decisions on implementation choices as you work
+- Offer choices to the user about what direction to take
+
+Usage notes:
+- Users will always be able to type a custom answer in the freeform field
+- Use multiSelect: true to allow multiple answers to be selected for a question
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+
+Huddle mode note: In huddle mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" - use ExitHuddleMode for plan approval. IMPORTANT: Do not reference "the plan" in your questions (e.g. "Do you have feedback about the plan?", "Does the plan look good?") because the user cannot see the plan in the UI until you call ExitHuddleMode. If you need plan approval, use ExitHuddleMode instead.`,
+		parameters: Type.Object({
+			questions: Type.Array(
+				Type.Object({
+					question: Type.String({
+						description: "The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: 'Which library should we use for date formatting?' If multiSelect is true, phrase it accordingly, e.g. 'Which features do you want to enable?'",
+					}),
+					header: Type.String({
+						description: "Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'.",
+					}),
+					options: Type.Array(
+						Type.Object({
+							label: Type.String({
+								description: "The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice.",
+							}),
+							description: Type.String({
+								description: "Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications.",
+							}),
+							markdown: Type.Optional(Type.String({
+								description: "Optional preview content shown in a monospace box when this option is focused. Use for ASCII mockups, code snippets, or diagrams that help users visually compare options. Supports multi-line text with newlines.",
+							})),
+						}),
+						{
+							minItems: 2,
+							maxItems: 4,
+						}
+					),
+					multiSelect: Type.Boolean({
+						default: false,
+						description: "Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive.",
+					}),
+				}),
+				{
+					minItems: 1,
+					maxItems: 4,
+					description: "Questions to ask the user (1-4 questions)",
+				}
+			),
+			metadata: Type.Optional(Type.Object({
+				source: Type.Optional(Type.String({
+					description: "Optional identifier for the source of this question (e.g., 'remember' for /remember command). Used for analytics tracking.",
+				})),
+			}, {
+				description: "Optional metadata for tracking and analytics purposes. Not displayed to user.",
+			})),
+		}),
+		execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+			const { questions, metadata } = params;
+
+			const result = await ctx.ui.custom<AskUserDialogResult>(
+				(tui, theme, _kb, done) => {
+					const dialog = new AskUserDialog(questions, theme);
+					dialog.onDone = (r) => done(r);
+					return {
+						get focused() { return dialog.focused; },
+						set focused(v: boolean) { dialog.focused = v; },
+						render: (w: number) => dialog.render(w),
+						invalidate: () => dialog.invalidate(),
+						handleInput: (data: string) => {
+							dialog.handleInput(data);
+							tui.requestRender();
+						},
+					};
+				},
+			);
+
+			// Cancelled (Esc)
+			if (!result) {
+				return {
+					content: [{ type: "text", text: "User cancelled the question." }],
+					details: { answers: {}, annotations: {}, metadata },
+				};
+			}
+
+			// "Chat about this"
+			if ("chatMode" in result) {
+				return {
+					content: [{ type: "text", text: "The user selected 'Chat about this'. They want to discuss the options before deciding. Respond conversationally." }],
+					details: { chatMode: true, metadata },
+				};
+			}
+
+			// Normal submission
+			const summary = Object.entries(result.answers)
+				.map(([q, a]) => `- ${q}\n  → ${a}`)
+				.join("\n");
+
+			return {
+				content: [{ type: "text", text: `User answers:\n${summary}` }],
+				details: { ...result, metadata },
+			};
+		},
+	});
+
+	// Permission gate for blocked operations in huddle mode
+	pi.on("tool_call", async (event, ctx) => {
+		if (!huddleEnabled) return;
+
+		const toolName = event.toolName;
+
+		if (toolName === "write" || toolName === "edit") {
+			const path = event.input.path || event.input.file || "unknown";
+			const theme = ctx.ui.theme;
+			const title = `${theme.fg("warning", theme.bold("⚠ Huddle Mode"))} — ${theme.fg("accent", toolName)}: ${theme.fg("accent", path)}`;
+			const choice = await ctx.ui.select(title, [
+				"Allow",
+				"Deny",
+				"Deny with feedback",
+			]);
+
+			if (choice === "Allow") return;
+
+			let reason = `User denied ${toolName} permission in huddle mode`;
+			if (choice === "Deny with feedback") {
+				const feedback = await ctx.ui.input("Why? (feedback sent to agent):");
+				if (feedback) reason = feedback;
+			}
+
+			return { block: true, reason };
+		}
+
+		if (toolName === "bash") {
+			const command = event.input.command as string;
+			if (!isSafeCommand(command)) {
+				const theme = ctx.ui.theme;
+				const title = `${theme.fg("warning", theme.bold("⚠ Huddle Mode"))} — ${theme.fg("accent", command)}`;
+				const choice = await ctx.ui.select(title, [
+					"Allow",
+					"Deny",
+					"Deny with feedback",
+				]);
+
+				if (choice === "Allow") return;
+
+				let reason = `User denied bash command in huddle mode: ${command}`;
+				if (choice === "Deny with feedback") {
+					const feedback = await ctx.ui.input("Why? (feedback sent to agent):");
+					if (feedback) reason = feedback;
+				}
+
+				return { block: true, reason };
+			}
+		}
+	});
+
+	// Filter out stale huddle context when not in huddle mode
+	pi.on("context", async (event) => {
+		if (huddleEnabled) return;
+
+		return {
+			messages: event.messages.filter((m) => {
+				const msg = m as AgentMessage & { customType?: string };
+				if (msg.customType === "huddle-context") return false;
+				if (msg.role !== "user") return true;
+
+				const content = msg.content;
+				if (typeof content === "string") {
+					return !content.includes("[HUDDLE MODE ACTIVE]");
+				}
+				if (Array.isArray(content)) {
+					return !content.some(
+						(c) => c.type === "text" && (c as TextContent).text?.includes("[HUDDLE MODE ACTIVE]"),
+					);
+				}
+				return true;
+			}),
+		};
+	});
+
+	// Inject huddle context before agent starts
+	pi.on("before_agent_start", async () => {
+		if (huddleEnabled) {
+			return {
+				message: {
+					customType: "huddle-context",
+					content: `[HUDDLE MODE ACTIVE]
+You are in huddle mode - a read-only exploration mode for safe code analysis and structured elicitation.
+
+IMPORTANT: Do NOT attempt to use edit or write tools while huddle mode is active. They are disabled. If you believe a file change is needed, tell the user and ask them to exit huddle mode first (via /huddle, /holup, /plan, or Alt+P).
+
+Available Tools:
+- read, bash, grep, find, ls, ask_user (always allowed)
+
+Safe Bash Commands (always allowed):
+cat, cd, rg, fd, grep, head, tail, ls, find, git status/log/diff/branch, npm list
+
+Other bash commands will prompt for permission.
+
+Use the ask_user tool for structured elicitation — gathering requirements, clarifying ambiguity, and getting decisions from the user before acting.
+
+Create a detailed numbered plan under a "Plan:" header:
+
+Plan:
+1. First step description
+2. Second step description
+...
+
+Do NOT execute the plan. Only plan and analyze. When you are ready to execute, ask the user to exit huddle mode.`,
+					display: false,
+				},
+			};
+		}
+	});
+
+	// Restore state on session start/resume
+	pi.on("session_start", async (_event, ctx) => {
+		if (pi.getFlag("huddle") === true || pi.getFlag("plan") === true) {
+			huddleEnabled = true;
+		}
+
+		const entries = ctx.sessionManager.getEntries();
+
+		const huddleEntry = entries
+			.filter((e: { type: string; customType?: string }) => e.type === "custom" && e.customType === "huddle")
+			.pop() as { data?: { enabled: boolean } } | undefined;
+
+		if (huddleEntry?.data) {
+			huddleEnabled = huddleEntry.data.enabled ?? huddleEnabled;
+		}
+
+		if (huddleEnabled) {
+			pi.setActiveTools(HUDDLE_MODE_TOOLS);
+		}
+		updateStatus(ctx);
+	});
+}

package/extensions/lib/ask-user-dialog.ts

@@ -0,0 +1,443 @@
+/**
+ * AskUserDialog - TUI component matching the Claude Code AskUserQuestion UI.
+ */
+
+import type { Component, Focusable } from "@mariozechner/pi-tui";
+import { Input, Key, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
+
+// Inline block cursor: inverse-video character (used after typed text)
+const BLOCK_CURSOR = "\x1b[7m \x1b[27m";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+
+export interface QuestionOption {
+	label: string;
+	description: string;
+	markdown?: string;
+}
+
+export interface QuestionDef {
+	question: string;
+	header: string;
+	options: QuestionOption[];
+	multiSelect: boolean;
+}
+
+export interface AskUserResult {
+	answers: Record<string, string>;
+	annotations: Record<string, { markdown?: string; notes?: string }>;
+}
+
+export type AskUserDialogResult = AskUserResult | { chatMode: true } | null;
+
+const SUBMIT_VIEW = -1;
+
+export class AskUserDialog implements Component, Focusable {
+	private questions: QuestionDef[];
+	private theme: Theme;
+
+	private currentQ = 0;
+	private selectedIdx = 0;
+	private submitIdx = 0;
+
+	// Regular option selections: question → selected labels
+	private selections = new Map<string, string[]>();
+	// Freeform text per question
+	private freeformValues = new Map<string, string>();
+	// Questions where freeform was explicitly confirmed (Enter pressed)
+	private confirmedFreeform = new Set<string>();
+	private annotations = new Map<string, { markdown?: string }>();
+
+	// Single Input instance — value swapped when switching questions
+	private freeformInput: Input;
+
+	// Focusable — kept so TUI recognises us, but we use inline BLOCK_CURSOR not CURSOR_MARKER
+	private _focused = false;
+	get focused(): boolean { return this._focused; }
+	set focused(value: boolean) { this._focused = value; }
+
+	onDone?: (result: AskUserDialogResult) => void;
+
+	constructor(questions: QuestionDef[], theme: Theme) {
+		this.questions = questions;
+		this.theme = theme;
+		this.freeformInput = new Input();
+		// No onSubmit/onEscape — we intercept keys in handleInput ourselves
+	}
+
+	private get currentQuestion(): QuestionDef | null {
+		if (this.currentQ === SUBMIT_VIEW) return null;
+		return this.questions[this.currentQ] ?? null;
+	}
+
+	private get isOnFreeform(): boolean {
+		const q = this.currentQuestion;
+		if (!q) return false;
+		return this.selectedIdx === q.options.length;
+	}
+
+	private get chatIdx(): number {
+		const q = this.currentQuestion;
+		if (!q) return 0;
+		return q.options.length + 1;
+	}
+
+	private get totalOptions(): number {
+		const q = this.currentQuestion;
+		if (!q) return 0;
+		return q.options.length + 2; // options + freeform + chat
+	}
+
+	// ── Freeform helpers ──────────────────────────────────────────
+
+	private saveFreeform(): void {
+		const q = this.currentQuestion;
+		if (!q) return;
+		const val = this.freeformInput.getValue().trim();
+		if (val) {
+			this.freeformValues.set(q.question, val);
+		} else {
+			this.freeformValues.delete(q.question);
+		}
+	}
+
+	private restoreFreeform(): void {
+		const q = this.currentQuestion;
+		if (!q) return;
+		this.freeformInput.setValue(this.freeformValues.get(q.question) ?? "");
+	}
+
+	private clearFreeform(): void {
+		const q = this.currentQuestion;
+		if (!q) return;
+		this.freeformValues.delete(q.question);
+		this.confirmedFreeform.delete(q.question);
+		this.freeformInput.setValue("");
+	}
+
+	// ── Answer state helpers ──────────────────────────────────────
+
+	private isAnswered(q: QuestionDef): boolean {
+		const sel = this.selections.get(q.question);
+		return (!!sel && sel.length > 0) || this.confirmedFreeform.has(q.question);
+	}
+
+	// ── Navigation helpers ────────────────────────────────────────
+
+	private setQuestion(idx: number): void {
+		// Save freeform if leaving a question on the freeform row
+		if (this.currentQ !== SUBMIT_VIEW && this.isOnFreeform) {
+			this.saveFreeform();
+		}
+		this.currentQ = idx;
+		this.selectedIdx = 0;
+		// If landing on a question and its freeform was previously filled, restore
+		if (this.currentQ !== SUBMIT_VIEW) {
+			this.freeformInput.setValue(this.freeformValues.get(this.currentQuestion!.question) ?? "");
+			this.freeformInput.focused = false;
+		}
+	}
+
+	private setSelectedIdx(idx: number): void {
+		const wasOnFreeform = this.isOnFreeform;
+		if (wasOnFreeform) this.saveFreeform();
+
+		this.selectedIdx = idx;
+
+		if (this.isOnFreeform) {
+			this.restoreFreeform();
+		} else {
+			this.freeformInput.focused = false;
+		}
+	}
+
+	private goNext(): void {
+		if (this.currentQ === SUBMIT_VIEW) {
+			this.setQuestion(0);
+		} else if (this.currentQ < this.questions.length - 1) {
+			this.setQuestion(this.currentQ + 1);
+		} else {
+			if (this.isOnFreeform) this.saveFreeform();
+			this.currentQ = SUBMIT_VIEW;
+			this.selectedIdx = 0;
+			this.submitIdx = 0;
+		}
+	}
+
+	private goPrev(): void {
+		if (this.currentQ === SUBMIT_VIEW) {
+			this.setQuestion(this.questions.length - 1);
+		} else if (this.currentQ === 0) {
+			if (this.isOnFreeform) this.saveFreeform();
+			this.currentQ = SUBMIT_VIEW;
+			this.selectedIdx = 0;
+			this.submitIdx = 0;
+		} else {
+			this.setQuestion(this.currentQ - 1);
+		}
+	}
+
+	// ── Selection logic ───────────────────────────────────────────
+
+	private selectCurrentOption(): void {
+		if (this.currentQ === SUBMIT_VIEW) {
+			if (this.submitIdx === 0) this.doSubmit();
+			else this.onDone?.(null);
+			return;
+		}
+
+		const q = this.currentQuestion!;
+		const qKey = q.question;
+		const freeformIdx = q.options.length;
+
+		if (this.selectedIdx === freeformIdx) {
+			// Enter on freeform = confirm the typed value
+			const val = this.freeformInput.getValue().trim();
+			if (val) {
+				this.saveFreeform();
+				this.confirmedFreeform.add(qKey);
+				if (!q.multiSelect) this.goNext();
+			}
+			return;
+		}
+
+		if (this.selectedIdx === this.chatIdx) {
+			this.onDone?.({ chatMode: true });
+			return;
+		}
+
+		const opt = q.options[this.selectedIdx];
+		if (q.multiSelect) {
+			const current = this.selections.get(qKey) ?? [];
+			const idx = current.indexOf(opt.label);
+			if (idx >= 0) {
+				current.splice(idx, 1);
+				this.selections.set(qKey, [...current]);
+			} else {
+				this.selections.set(qKey, [...current, opt.label]);
+				if (opt.markdown) this.annotations.set(qKey, { markdown: opt.markdown });
+			}
+		} else {
+			this.selections.set(qKey, [opt.label]);
+			if (opt.markdown) this.annotations.set(qKey, { markdown: opt.markdown });
+			// Clear freeform if a real option was chosen
+			this.clearFreeform();
+			this.goNext();
+		}
+	}
+
+	private doSubmit(): void {
+		const answers: Record<string, string> = {};
+		const annotations: Record<string, { markdown?: string }> = {};
+		for (const q of this.questions) {
+			const sel = this.selections.get(q.question);
+			// Only include freeform if explicitly confirmed with Enter
+			const freeform = this.confirmedFreeform.has(q.question)
+				? this.freeformValues.get(q.question)
+				: undefined;
+			const parts: string[] = [];
+			if (sel && sel.length > 0) parts.push(...sel);
+			if (freeform) parts.push(freeform);
+			answers[q.question] = parts.length > 0 ? parts.join(", ") : "(skipped)";
+			const ann = this.annotations.get(q.question);
+			if (ann) annotations[q.question] = ann;
+		}
+		this.onDone?.({ answers, annotations });
+	}
+
+	// ── Input handling ────────────────────────────────────────────
+
+	handleInput(data: string): void {
+		if (this.currentQ === SUBMIT_VIEW) {
+			if (matchesKey(data, Key.up))                                 this.submitIdx = Math.max(0, this.submitIdx - 1);
+			else if (matchesKey(data, Key.down))                          this.submitIdx = Math.min(1, this.submitIdx + 1);
+			else if (matchesKey(data, Key.enter))                         this.selectCurrentOption();
+			else if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) this.goNext();
+			else if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) this.goPrev();
+			else if (matchesKey(data, Key.escape))                        this.onDone?.(null);
+			return;
+		}
+
+		// Navigation keys always take priority, even on the freeform row
+		if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+			this.goNext(); return;
+		}
+		if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) {
+			this.goPrev(); return;
+		}
+		if (matchesKey(data, Key.escape)) {
+			this.onDone?.(null); return;
+		}
+
+		// On the freeform row — up/down navigate away; everything else goes to Input
+		if (this.isOnFreeform) {
+			if (matchesKey(data, Key.up)) {
+				this.setSelectedIdx(this.selectedIdx - 1);
+			} else if (matchesKey(data, Key.down)) {
+				this.setSelectedIdx(this.selectedIdx + 1);
+			} else if (matchesKey(data, Key.enter)) {
+				this.selectCurrentOption();
+			} else {
+				// Character input — goes straight to freeformInput
+				this.freeformInput.handleInput(data);
+				// Keep freeformValues in sync live
+				this.saveFreeform();
+			}
+			return;
+		}
+
+		// Normal option navigation
+		if (matchesKey(data, Key.up)) {
+			if (this.selectedIdx > 0) this.setSelectedIdx(this.selectedIdx - 1);
+		} else if (matchesKey(data, Key.down)) {
+			if (this.selectedIdx < this.totalOptions - 1) this.setSelectedIdx(this.selectedIdx + 1);
+		} else if (matchesKey(data, Key.enter)) {
+			this.selectCurrentOption();
+		}
+	}
+
+	invalidate(): void {
+		this.freeformInput.invalidate?.();
+	}
+
+	// ── Rendering ─────────────────────────────────────────────────
+
+	render(width: number): string[] {
+		const t = this.theme;
+		const lines: string[] = [];
+
+		// ── Tab bar ──────────────────────────────────────────────
+		const tabParts: string[] = [];
+		for (let i = 0; i < this.questions.length; i++) {
+			const q = this.questions[i];
+			const isActive = i === this.currentQ;
+			const isDone = this.isAnswered(q);
+			const icon = isDone ? "☒" : "□";
+			const label = `${icon} ${q.header}`;
+			tabParts.push(isActive
+				? t.bg("selectedBg", ` ${t.bold(label)} `)
+				: t.fg("muted", ` ${label} `));
+		}
+		const submitActive = this.currentQ === SUBMIT_VIEW;
+		tabParts.push(submitActive
+			? t.bg("selectedBg", t.bold(" ✓ Submit "))
+			: t.fg("dim", " ✓ Submit "));
+
+		lines.push(truncateToWidth(`← ${tabParts.join("")} →`, width));
+		lines.push("");
+
+		// ── Submit view ──────────────────────────────────────────
+		if (this.currentQ === SUBMIT_VIEW) {
+			lines.push(t.bold("Review your answers"));
+			lines.push("");
+
+			const unanswered = this.questions.filter((q) => !this.isAnswered(q));
+			if (unanswered.length > 0) {
+				lines.push(t.fg("warning", "⚠ You have not answered all questions"));
+				lines.push("");
+			}
+
+			for (const q of this.questions) {
+				const sel = this.selections.get(q.question) ?? [];
+				const freeform = this.confirmedFreeform.has(q.question)
+					? this.freeformValues.get(q.question)
+					: undefined;
+				const parts = [...sel, ...(freeform ? [freeform] : [])];
+				if (parts.length > 0) {
+					lines.push(truncateToWidth(`  ● ${q.question}`, width));
+					lines.push(truncateToWidth(`    ${t.fg("accent", `→ ${parts.join(", ")}`)}`, width));
+					lines.push("");
+				}
+			}
+
+			lines.push(t.fg("muted", "Ready to submit your answers?"));
+			lines.push("");
+			lines.push("  " + (this.submitIdx === 0
+				? t.fg("accent", `> 1. ${t.bold("Submit answers")}`)
+				: `  1. ${t.bold("Submit answers")}`));
+			lines.push("  " + (this.submitIdx === 1
+				? t.fg("accent", "> 2. Cancel")
+				: "  2. Cancel"));
+			lines.push("");
+			lines.push(t.fg("dim", "Enter to select · ←/→ or Tab to go back · Esc to cancel"));
+			return lines.map((l) => truncateToWidth(l, width));
+		}
+
+		// ── Question view ────────────────────────────────────────
+		const q = this.currentQuestion!;
+		const freeformIdx = q.options.length;
+		const checkedLabels = this.selections.get(q.question) ?? [];
+		const freeformValue = this.freeformValues.get(q.question) ?? "";
+
+		lines.push(t.bold(q.question));
+		lines.push("");
+
+		for (let i = 0; i < q.options.length; i++) {
+			const opt = q.options[i];
+			const isCursor = i === this.selectedIdx;
+			const isChecked = checkedLabels.includes(opt.label);
+			const num = `${i + 1}.`;
+			const checkmark = isChecked ? ` ${t.fg("success", "✓")}` : "";
+
+			let labelLine: string;
+			if (isCursor && isChecked) {
+				labelLine = `${t.fg("accent", `> ${num} ${opt.label}`)}${checkmark}`;
+			} else if (isCursor) {
+				labelLine = t.fg("accent", `> ${num} ${opt.label}`);
+			} else if (isChecked) {
+				labelLine = `  ${t.fg("accent", `${num} ${opt.label}`)}${checkmark}`;
+			} else {
+				labelLine = `  ${num} ${opt.label}`;
+			}
+			lines.push(truncateToWidth("  " + labelLine, width));
+			if (opt.description) {
+				lines.push(truncateToWidth(`       ${t.fg("muted", opt.description)}`, width));
+			}
+		}
+
+		// ── Freeform row ─────────────────────────────────────────
+		const isOnFreeform = this.selectedIdx === freeformIdx;
+		const otherNum = `${freeformIdx + 1}.`;
+
+		if (isOnFreeform) {
+			const inputVal = this.freeformInput.getValue();
+			if (inputVal === "") {
+				// Block cursor over the "T" — invert the first char of the placeholder
+				const placeholder = "Type something.";
+				const cursorChar = `\x1b[7m${placeholder[0]}\x1b[27m`;
+				const row = `  ${t.fg("accent", `> ${otherNum}`)} ${cursorChar}${t.fg("dim", placeholder.slice(1))}`;
+				lines.push(truncateToWidth(row, width));
+			} else {
+				// Block cursor after typed text — no checkmark until Enter confirms
+				const row = `  ${t.fg("accent", `> ${otherNum} ${inputVal}`)}${BLOCK_CURSOR}`;
+				lines.push(truncateToWidth(row, width));
+			}
+		} else if (freeformValue && this.confirmedFreeform.has(q.question)) {
+			// Confirmed — show with checkmark
+			lines.push(truncateToWidth(`    ${t.fg("accent", `${otherNum} ${freeformValue}`)} ${t.fg("success", "✓")}`, width));
+		} else if (freeformValue) {
+			// Typed but not yet confirmed — show without checkmark
+			lines.push(truncateToWidth(`    ${t.fg("dim", `${otherNum} ${freeformValue}`)}`, width));
+		} else {
+			// Not active, empty
+			lines.push(truncateToWidth(`    ${otherNum} ${t.fg("dim", "Type something.")}`, width));
+		}
+
+		// ── Separator + Chat ─────────────────────────────────────
+		lines.push("");
+		lines.push(t.fg("dim", "─".repeat(Math.max(width - 2, 10))));
+		lines.push("");
+
+		const isChatCursor = this.selectedIdx === this.chatIdx;
+		lines.push(isChatCursor
+			? truncateToWidth(`  ${t.fg("accent", `> ${this.chatIdx + 1}. Chat about this`)}`, width)
+			: truncateToWidth(`    ${this.chatIdx + 1}. ${t.fg("muted", "Chat about this")}`, width));
+
+		lines.push("");
+		lines.push(truncateToWidth(
+			t.fg("dim", "Enter to select · Tab/↑↓ to navigate · Esc to cancel"),
+			width,
+		));
+
+		return lines.map((l) => truncateToWidth(l, width));
+	}
+}

package/extensions/lib/utils.ts

@@ -0,0 +1,166 @@
+/**
+ * Pure utility functions for plan mode.
+ * Extracted for testability.
+ */
+
+// Destructive commands blocked in plan mode
+const DESTRUCTIVE_PATTERNS = [
+	/\brm\b/i,
+	/\brmdir\b/i,
+	/\bmv\b/i,
+	/\bcp\b/i,
+	/\bmkdir\b/i,
+	/\btouch\b/i,
+	/\bchmod\b/i,
+	/\bchown\b/i,
+	/\bchgrp\b/i,
+	/\bln\b/i,
+	/\btee\b/i,
+	/\btruncate\b/i,
+	/\bdd\b/i,
+	/\bshred\b/i,
+	/(^|[^<])>(?!>)/,
+	/>>/,
+	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
+	/\byarn\s+(add|remove|install|publish)/i,
+	/\bpnpm\s+(add|remove|install|publish)/i,
+	/\bpip\s+(install|uninstall)/i,
+	/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
+	/\bbrew\s+(install|uninstall|upgrade)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bsudo\b/i,
+	/\bsu\b/i,
+	/\bkill\b/i,
+	/\bpkill\b/i,
+	/\bkillall\b/i,
+	/\breboot\b/i,
+	/\bshutdown\b/i,
+	/\bsystemctl\s+(start|stop|restart|enable|disable)/i,
+	/\bservice\s+\S+\s+(start|stop|restart)/i,
+	/\b(vim?|nano|emacs|code|subl)\b/i,
+];
+
+// Safe read-only commands allowed in plan mode
+const SAFE_PATTERNS = [
+	/^\s*cd\b/,
+	/^\s*cat\b/,
+	/^\s*head\b/,
+	/^\s*tail\b/,
+	/^\s*less\b/,
+	/^\s*more\b/,
+	/^\s*grep\b/,
+	/^\s*find\b/,
+	/^\s*ls\b/,
+	/^\s*pwd\b/,
+	/^\s*echo\b/,
+	/^\s*printf\b/,
+	/^\s*wc\b/,
+	/^\s*sort\b/,
+	/^\s*uniq\b/,
+	/^\s*diff\b/,
+	/^\s*file\b/,
+	/^\s*stat\b/,
+	/^\s*du\b/,
+	/^\s*df\b/,
+	/^\s*tree\b/,
+	/^\s*which\b/,
+	/^\s*whereis\b/,
+	/^\s*type\b/,
+	/^\s*env\b/,
+	/^\s*printenv\b/,
+	/^\s*uname\b/,
+	/^\s*whoami\b/,
+	/^\s*id\b/,
+	/^\s*date\b/,
+	/^\s*cal\b/,
+	/^\s*uptime\b/,
+	/^\s*ps\b/,
+	/^\s*top\b/,
+	/^\s*htop\b/,
+	/^\s*free\b/,
+	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
+	/^\s*git\s+ls-/i,
+	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
+	/^\s*yarn\s+(list|info|why|audit)/i,
+	/^\s*node\s+--version/i,
+	/^\s*python\s+--version/i,
+	/^\s*curl\s/i,
+	/^\s*wget\s+-O\s*-/i,
+	/^\s*jq\b/,
+	/^\s*sed\s+-n/i,
+	/^\s*awk\b/,
+	/^\s*rg\b/,
+	/^\s*fd\b/,
+	/^\s*bat\b/,
+	/^\s*exa\b/,
+];
+
+/**
+ * Split command into parts respecting quoted strings.
+ * Handles: &&, ;, | (but not inside quotes)
+ */
+function splitCommandRespectingQuotes(command: string): string[] {
+	const parts: string[] = [];
+	let current = "";
+	let inSingleQuote = false;
+	let inDoubleQuote = false;
+	let i = 0;
+
+	while (i < command.length) {
+		const char = command[i];
+		const nextChar = command[i + 1];
+
+		if (char === "'" && !inDoubleQuote) {
+			inSingleQuote = !inSingleQuote;
+			current += char;
+		} else if (char === '"' && !inSingleQuote) {
+			inDoubleQuote = !inDoubleQuote;
+			current += char;
+		} else if (!inSingleQuote && !inDoubleQuote) {
+			// Check for separators outside quotes
+			if (char === "&" && nextChar === "&") {
+				parts.push(current.trim());
+				current = "";
+				i += 2; // Skip both &
+				continue;
+			} else if (char === ";") {
+				parts.push(current.trim());
+				current = "";
+			} else if (char === "|") {
+				parts.push(current.trim());
+				current = "";
+			} else {
+				current += char;
+			}
+		} else {
+			current += char;
+		}
+		i++;
+	}
+
+	if (current.trim()) {
+		parts.push(current.trim());
+	}
+
+	return parts;
+}
+
+export function isSafeCommand(command: string): boolean {
+	// Check for destructive patterns anywhere in the command
+	const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
+	if (isDestructive) return false;
+
+	// Split compound commands and check each part
+	const parts = splitCommandRespectingQuotes(command);
+
+	for (const part of parts) {
+		const trimmed = part.trim();
+		if (!trimmed) continue;
+
+		// Check if this part starts with a safe command
+		const isPartSafe = SAFE_PATTERNS.some((p) => p.test(trimmed));
+		if (!isPartSafe) return false;
+	}
+
+	return true;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ssweens/pi-huddle",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Huddle mode for pi - safe exploration and structured elicitation before execution",
+  "keywords": [
+    "pi-package",
+    "huddle-mode",
+    "plan-mode",
+    "safe-mode",
+    "read-only",
+    "ask-user"
+  ],
+  "author": "ssweens",
+  "license": "MIT",
+  "files": [
+    "extensions/",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "screenshot.png",
+    "ask-user-screenshot.png"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-agent-core": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/huddle/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: huddle
+description: Use this skill when working in pi's Huddle Mode. Huddle Mode is a safe exploration mode where read operations are always allowed, write operations require user permission, and the ask_user tool enables structured multi-question elicitation with a rich TUI dialog.
+---
+
+# Huddle Mode Skill
+
+## Overview
+
+Huddle Mode is a safety feature that allows free read-only exploration while requiring user approval for any file modifications. It also provides the `ask_user` tool for structured elicitation — gathering requirements, clarifying ambiguity, and getting decisions from the user via a rich multi-question TUI dialog.
+
+## When to Use
+
+- **Initial code exploration** - Understanding a new codebase safely
+- **Complex refactoring** - Planning multi-step changes before executing
+- **Requirements gathering** - Using `ask_user` to clarify intent before acting
+- **Safety-critical changes** - When you want explicit approval for each modification
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/huddle` | Toggle huddle mode on/off (primary) |
+| `/holup` | Toggle huddle mode on/off (alias) |
+| `/plan` | Toggle huddle mode on/off (alias) |
+| `--huddle` | CLI flag to start pi in huddle mode |
+| `--plan` | CLI flag alias (backward compat) |
+| `Alt+H` (Option+H on Mac) | Keyboard shortcut to toggle |
+
+## Workflow
+
+### 1. Enter Huddle Mode
+
+```
+/huddle      # or /holup, /plan, Alt+H
+```
+
+### 2. Permission Gates
+
+**Always Allowed:**
+- `read`, `grep`, `find`, `ls` - Read and search operations
+- `bash` - Allowlisted safe commands (cat, grep, ls, git status, etc.)
+- `ask_user` - Structured user elicitation
+
+**Requires Permission:**
+- `edit` - File modifications (user must approve each edit)
+- `write` - File creation (user must approve each write)
+- Non-allowlisted bash commands (npm install, git commit, etc.)
+
+### 3. Exit Huddle Mode
+
+When ready to execute changes:
+- Toggle off with `/huddle`, `/holup`, `/plan`, or `Alt+H`
+- Full tool access restored
+
+## ask_user Tool
+
+The `ask_user` tool is available in **both huddle mode and normal mode**. It presents a rich TUI dialog with tabs for each question, multiple-choice options, freeform text input, and a submit/review view.
+
+### When to Use
+
+- Gather user preferences or requirements before acting
+- Clarify ambiguous instructions
+- Get decisions on implementation choices
+- Offer architectural choices with descriptions and code previews
+
+**Huddle mode:** Use `ask_user` to clarify requirements BEFORE finalizing your plan. Do NOT ask "Is my plan ready?" — the user cannot see the plan until they exit huddle mode.
+
+### Tool Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `questions` | array | 1–4 questions to ask |
+| `questions[].question` | string | Full question text (should end with ?) |
+| `questions[].header` | string | Short tab label (max 12 chars). E.g. "Auth method", "Library" |
+| `questions[].options` | array | 2–4 options per question |
+| `questions[].options[].label` | string | Display text (1–5 words) |
+| `questions[].options[].description` | string | Trade-off explanation shown below label |
+| `questions[].options[].markdown` | string | Optional code/ASCII preview shown when focused |
+| `questions[].multiSelect` | boolean | Allow multiple selections (default: false) |
+| `metadata` | object | Optional `{ source }` for tracking |
+
+### UX Behaviour
+
+- **Tab bar** at top — one tab per question + Submit tab; `←`/`→` or `Tab`/`Shift+Tab` navigate
+- **Numbered options** — `↑`/`↓` to move, `Enter` to select
+- **Freeform field** — navigate to it and start typing immediately; `Enter` confirms the typed answer
+- **Chat about this** — last row on each question; returns a "discuss" signal to the agent
+- **Submit view** — recap of all answers with `● Question → Answer` format
+- **Esc** to cancel at any time
+
+### Example
+
+```json
+{
+  "questions": [
+    {
+      "question": "Which approach should I use for error handling?",
+      "header": "Errors",
+      "options": [
+        {
+          "label": "Return early (Recommended)",
+          "description": "Exit on first error, simplest code path",
+          "markdown": "if (err) return { error: err };"
+        },
+        {
+          "label": "Collect errors",
+          "description": "Gather all errors, report at end"
+        }
+      ],
+      "multiSelect": false
+    },
+    {
+      "question": "Which features do you want to enable?",
+      "header": "Features",
+      "options": [
+        { "label": "Logging", "description": "Structured JSON logs" },
+        { "label": "Metrics", "description": "Prometheus endpoint" },
+        { "label": "Tracing", "description": "OpenTelemetry spans" },
+        { "label": "Alerts", "description": "PagerDuty integration" }
+      ],
+      "multiSelect": true
+    }
+  ]
+}
+```
+
+### Return Value
+
+```json
+{
+  "answers": {
+    "Which approach should I use for error handling?": "Return early (Recommended)",
+    "Which features do you want to enable?": "Logging, Tracing"
+  },
+  "annotations": {},
+  "metadata": {}
+}
+```
+
+## Allowed Bash Commands (No Prompt)
+
+- File inspection: `cat`, `head`, `tail`, `less`, `more`
+- Search: `grep`, `find`, `rg`, `fd`
+- Directory: `ls`, `pwd`, `tree`
+- Git read: `git status`, `git log`, `git diff`, `git branch`
+- Package info: `npm list`, `npm outdated`, `yarn info`
+- Utilities: `curl`, `jq`, `uname`, `whoami`, `date`
+
+## Blocked Bash Commands (Prompt Required)
+
+- File mutation: `rm`, `mv`, `cp`, `mkdir`, `touch`
+- Git writes: `git add`, `git commit`, `git push`
+- Package installs: `npm install`, `yarn add`, `pip install`
+- System: `sudo`, `kill`, `reboot`
+- Redirections: `>`, `>>`
+
+## Tips
+
+1. **Use `ask_user` early** — clarify intent before exploring, not after
+2. **Up to 4 questions per call** — batch related questions together
+3. **Use `markdown` field** for code previews in option descriptions
+4. **multiSelect** for feature flags, configuration choices, etc.
+5. **Exit huddle when ready** — the user controls when to execute