shariq-pi-extensions 0.3.7 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Shariq's Pi extensions
 
-Cross-platform extensions and operating skills for the Pi coding agent. Credentials and runtime state stay on each machine and are never bundled with the package.
+Cross-platform extensions and skills for the [Pi](https://github.com/earendil-works/pi) coding agent. Credentials and runtime state stay on each machine and are never bundled with the package.
 
 ## Install
 
@@ -20,24 +20,22 @@ Run `/reload` in an existing Pi session after installation; new sessions load th
 
 ## Included extensions
 
-The package contains:
-
-- structured user questions
+- structured user questions (`ask_user`)
+- persistent goals with evidence checklists and budgets
+- a task list for multi-deliverable work, with a live progress dock
+- Pi subagents with profiles, worktree isolation, and a takeover dashboard
+- Smart Compaction: structured checkpoints with file and worktree state
 - managed background terminals
-- Firecrawl web and developer search plus scraping
-- persistent task goals
-- branch-safe model-maintained task lists with live progress UI and compaction continuity
-- configurable steer, interrupt, or follow-up input behavior
-- Smart Compaction with high-fidelity checkpointing, delta-merging, and custom model routing
-- per-response TPS, TTFT, elapsed-time, and output status
-- Context Usage display
-- small shell and command shortcuts
-- Pi subagents
+- Firecrawl web search, scraping, and developer search
 - lightweight URL fetching
+- Context Usage startup card
+- per-response TPS, time-to-first-token, and output status
+- configurable steer, interrupt, or follow-up Enter behavior
+- `/exit` as an alias for `/quit`
 
-The package also includes the `ember-warm-dark` TUI theme and declares the `background-terminals` and `subagents` skills so Pi loads their operating guidance automatically. Pi reads them from the installed package; duplicating files under `<agent-dir>/skills` is unnecessary and would leave stale copies after removal.
+The package also ships the `ember-warm-dark` theme and the `background-terminals` and `subagents` skills. Pi loads the skills from the installed package; copying them into `<agent-dir>/skills` would leave stale duplicates after removal.
 
-See [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md) for commands, tools, configuration, and external dependencies.
+The suite is developed and tested against Pi 1.0. See [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md) for commands, tools, configuration, and external dependencies.
 
 ## Enable or disable extensions
 

package/docs/ARCHITECTURE.md

@@ -1,53 +1,58 @@
 # Architecture
 
-Last verified: 2026-09-04
-
 ## Package boundary
 
-The repository has one Pi package boundary at its root. Every extension is an independently declared resource in `package.json#pi.extensions`. Pi therefore loads only intentional extension factories, and `pi config` can toggle each one without separate installation.
+The repository is one Pi package. Every extension is declared on its own in `package.json#pi.extensions`, so Pi loads only intended entrypoints and `pi config` can enable or disable each one.
 
 ## Source layout
 
 ```text
-extensions/<name>/index.ts       suite extension entrypoints
-extensions/<name>/src/           extension-owned implementation
-extensions/shared/               runtime helpers shared across extensions
-skills/                          operating guidance paired with async extensions
-docs/                            package-level maintenance documentation
-scripts/                         repository validation helpers
+extensions/<name>/index.ts       extension entrypoint
+extensions/<name>/src/           extension-owned implementation, when large enough to split
+extensions/shared/               helpers used by more than one extension
+skills/                          operating guidance shipped with the async extensions
+themes/                          TUI themes
+docs/                            package-level documentation
+scripts/                         test runner and package validation
 ```
 
-Extension entrypoints register tools, commands, providers, events, or UI. Shared code stays in `extensions/shared` only when more than one extension owns the behavior. The shared activity dock combines active Task List, terminal, and subagent rows under one bounded widget; shared tool cards keep lifecycle operations compact in the timeline while preserving expanded output. Provider-specific protocol and authentication code remains inside its provider directory. The background-terminal and subagent skills ship beside their extensions so a new machine receives the required lifecycle guidance with the tools.
+Entrypoints register tools, commands, events, renderers, and UI. Code moves to `extensions/shared` only when several extensions use the same contract. Two shared pieces tie the async extensions together:
 
-## Dependency model
+- the **Active work** dock merges live rows from Task List, Background Terminals, and Subagents into one bounded widget;
+- settlement delivery gives each Pi session one private queue for terminal and subagent results, delivered at the parent's idle edge.
 
-Pi-owned packages and `typebox` are optional peer dependencies at runtime. Pi supplies them when it loads the package. Exact versions are development dependencies so local typechecking and tests use a reproducible API surface.
+The background-terminal and subagent skills ship beside their extensions, so a new machine gets the lifecycle guidance together with the tools.
 
-Third-party runtime dependencies are normal package dependencies:
+## Model-facing text
 
-- `@lydell/node-pty` powers managed background terminals;
-- `effect` powers subagent lifecycle and coordination.
+Tool descriptions, parameter descriptions, prompt snippets, and prompt guidelines are sent with every model request, and guidelines become system-prompt rules. They cost tokens on every turn and are read literally. Each rule has one home: a tool's description says what it does and its contract, one guideline at most says when to use it, and longer operating guidance belongs in a skill. Extensions do not inject reminders that push the model toward a tool.
+
+## Dependency model
 
-The repository uses one root manifest and lockfile for the full extension suite.
+Pi packages (`@earendil-works/pi-*`) and `typebox` are optional peer dependencies; Pi provides them at runtime. Pinned development dependencies give typechecking and tests a reproducible API surface. Third-party runtime modules are normal dependencies:
+
+- `@lydell/node-pty` runs background terminals;
+- `effect` runs the subagent lifecycle.
+
+`bun.lock` is the lockfile CI installs from. `package-lock.json` is kept in sync for npm-based installs: Pi installs Git packages with `npm install`.
 
 ## Runtime state
 
-Installed package directories are treated as immutable. Extensions resolve writable state through Pi's APIs:
+Installed package directories are treated as read-only. Writable state goes through Pi's APIs:
 
-- Smart Compaction configuration and details ledgers: `<agent-dir>/smart-compaction.json`
-- Input mode configuration: `<agent-dir>/input-mode.json`
-- Subagent configuration and catalog: paths derived from `getAgentDir()`
-- Goal and Task List state: branch-local Pi session entries; neither writes a separate runtime-state file
-- project configuration: paths derived from Pi's `CONFIG_DIR_NAME`
+- Smart Compaction settings: `<agent-dir>/smart-compaction.json`
+- Input mode setting: `<agent-dir>/input-mode.json`
+- Subagent configuration, catalog, run snapshots, and worktrees: under `getAgentDir()`
+- Goal and Task List state: branch-local Pi session entries
+- Project configuration: under Pi's `CONFIG_DIR_NAME`
+- Terminal logs and oversized web responses: the system temporary directory
 
-Credentials remain in Pi auth storage, environment variables, service credential stores, or ignored machine-local files. Package source never contains an API key, OAuth token, database, cache, or session.
+Credentials stay in Pi auth storage, environment variables, service credential stores, or ignored machine-local files.
 
 ## Portability
 
-Runtime paths use `node:path`, `getAgentDir()`, `CONFIG_DIR_NAME`, `os.homedir()`, and platform checks where service credential locations differ. Code must not assume `/Users`, `/home`, Homebrew, a particular shell, or a package installation path. Native PTY support is installed through npm for the active Node platform.
+Paths are built with `node:path`, `getAgentDir()`, `CONFIG_DIR_NAME`, and `os.homedir()`, with platform branches only where a third-party credential location differs. No code assumes `/Users`, `/home`, Homebrew, a shell, or the package's install path. The PTY layer uses Bun's terminal API under Bun and `@lydell/node-pty` under Node.
 
 ## Loading and updates
 
-Pi manages npm and Git package installations and may replace their contents during updates, so user state must never be written beside extension source.
-
-`pi config` controls every individual package resource. Disabling an extension prevents its factory from loading after reload.
+Pi manages npm and Git installs and may replace their contents on update, so user state is never written beside extension source. Disabling an extension in `pi config` stops its factory from loading after `/reload`.

package/docs/DEVELOPMENT.md

@@ -1,14 +1,12 @@
-# Development and cutover
-
-Last verified: 2026-09-04
+# Development
 
 ## Requirements
 
 - mise
-- Pi matching the pinned development dependency version
-- platform build support required by `@lydell/node-pty`
+- Pi at or above the version in `devDependencies`
+- platform build support for `@lydell/node-pty`
 
-Install the exact toolchain and dependencies:
+Install the pinned toolchain and dependencies:
 
 ```bash
 mise install --locked
@@ -17,66 +15,45 @@ mise exec --locked -- bun install
 
 ## Validation
 
-Validate the complete suite and inspect the package payload:
-
 ```bash
 mise exec --locked -- bun run validate
 mise exec --locked -- bun run pack:inspect
 ```
 
-The root validation checks TypeScript, runtime tests, declared extension and skill entrypoints, and forbidden runtime files. Inspect the package file list before committing. It must not contain credentials, `.env`, first-party caches, databases, sessions, logs, or `node_modules`.
+`validate` runs the TypeScript check, every `*.test.ts` file under `extensions/` with Node's test runner, and `scripts/validate-package.mjs`. The package check confirms that declared extensions and skills exist, are sorted, have READMEs and tests, and that the npm payload contains no credentials, `.env` files, caches, databases, sessions, logs, or first-party tests.
+
+Read the `pack:inspect` file list before committing a package change.
 
 ## Adding an extension
 
-1. Add a self-contained directory under `extensions/` with an `index.ts` entrypoint.
-2. Use relative imports for extension-owned code and `extensions/shared` only for genuinely shared behavior.
-3. Put external runtime modules in root `dependencies`.
-4. Add the exact entrypoint to root `package.json#pi.extensions`.
-5. Add focused runtime tests and update `docs/EXTENSIONS.md`.
-6. Run both validations and inspect the package payload.
+1. Create `extensions/<name>/index.ts` and `extensions/<name>/README.md`.
+2. Import extension-owned code relatively, and `extensions/shared` only for behavior another extension already shares.
+3. Put third-party runtime modules in root `dependencies`.
+4. Add the entrypoint to `package.json#pi.extensions` in sorted order.
+5. For each tool, choose its `exposure` and `annotations` (see [Tool exposure](EXTENSIONS.md#tool-exposure)) and keep its model-facing text short (see [Model-facing text](ARCHITECTURE.md#model-facing-text)).
+6. Add focused tests and a section in `docs/EXTENSIONS.md`.
+7. Run both validations.
 
-Do not add nested package manifests or lockfiles to default-suite extensions. The workspace root owns their dependencies and tooling.
+Do not add nested package manifests or lockfiles under `extensions/`.
 
 ## Runtime configuration
 
-Use `getAgentDir()` for user-level state and `CONFIG_DIR_NAME` for project-level Pi configuration. Use `node:path` and explicit platform branches where third-party credential locations differ. Never infer a writable location from `import.meta.url` or the installed package directory.
-
-Keep secrets out of examples and fixtures. Tests should inject temporary roots, fake environment objects, or local test servers rather than reading real credentials.
+Use `getAgentDir()` for user-level state and `CONFIG_DIR_NAME` for project-level Pi configuration. Never derive a writable location from `import.meta.url` or the install directory. Tests use temporary roots, fake environments, or local servers, never real credentials.
 
 ## Skills paired with extensions
 
-The root manifest declares `skills/background-terminals` and `skills/subagents`. Pi loads them directly from the managed package. Do not copy them into the agent directory from install scripts; that would create duplicates and leave stale files after removal.
-
-When any paired skill changes, validate its structure and keep its behavior aligned with the corresponding extension tools.
-
-## Current-machine cutover
+`package.json#pi.skills` declares `skills/background-terminals` and `skills/subagents`, and Pi loads them from the installed package. Do not copy them into the agent directory. When a paired extension's tools or delivery behavior change, update its skill in the same change.
 
-Do not remove a working local extension set before the managed package is available.
+## Upgrading Pi
 
-1. Push and validate the public GitHub repository.
-2. Run `pi install git:https://github.com/shariqriazz/shariq-pi-extensions`; do not reload yet.
-3. Move old auto-discovered extension directories out of the active Pi extension directory so package and local copies cannot load together.
-4. Move the old paired skill directories out of active discovery; the Git package supplies them.
-5. Run `/reload` once.
-6. Verify package provenance through `pi list`, then check representative commands, tools, providers, and both packaged skills.
+1. Raise the `@earendil-works/pi-*` development dependencies, then run `mise exec --locked -- bun install` and `npm install --package-lock-only --ignore-scripts` to refresh both lockfiles.
+2. Read the Pi changelog for extension API changes, especially tool, event, and TUI changes.
+3. Run both validations, then load the working tree in Pi (`pi -ne -e ./extensions/<name>/index.ts`) to check commands and overlays that tests do not render.
 
-Rollback is the reverse: remove the Git package from Pi settings, restore the local extension and skill directories, and reload. Never delete credentials or databases during rollback.
-
-## Distribution
-
-GitHub hosts the public source and npm distributes versioned releases. Push validated changes to `main` under the repository's normal Git policy.
-
-```bash
-git push origin main
-gh repo view shariqriazz/shariq-pi-extensions --json visibility,url
-```
+## Releases
 
-Before publishing a new npm version:
+GitHub hosts the source and npm distributes versioned releases. Any functional change bumps `package.json#version` (semantic versioning). Pushing to `main` runs `.github/workflows/ci.yml` and `.github/workflows/publish-npm.yml`; the publish workflow validates and publishes with npm trusted publishing and provenance whenever the version is not yet on npm.
 
-1. Update `package.json#version` using semantic versioning.
-2. Run `mise exec --locked -- bun install` and `mise exec --locked -- bun run validate`.
-3. Inspect `mise exec --locked -- bun run pack:inspect` for secrets, runtime state, and accidental files.
-4. Run the `Publish npm package` workflow. npm trusted publishing authenticates it through GitHub OIDC and records provenance without a long-lived token.
-5. Verify the registry version and install it with `pi install npm:shariq-pi-extensions`.
+After the publish run succeeds, confirm the release with `npm view shariq-pi-extensions version` and update installed copies with `pi update --extensions`.
 
-Use npm for stable versioned installs. Use an unpinned Git source for updates directly from `main`, and a tag or commit when a machine should remain fixed to a known revision.
+An npm install follows published versions. An unpinned Git install follows `main`; pin a tag or commit to keep a machine on a known revision.

package/docs/EXTENSIONS.md

@@ -1,80 +1,61 @@
 # Extension catalog
 
-Last verified: 2026-09-04
+Each extension's README covers its full behavior. This page is the short version.
 
 ## Agent workflow
 
 ### [Structured questions](../extensions/ask-user/README.md)
 
-`ask_user` presents one blocking multiple-choice decision with an optional custom answer. It is intended for decisions that cannot be resolved safely from available context.
+`ask_user` shows one multiple-choice decision, with an optional written answer, when a missing user choice blocks safe progress. Outside the TUI it reports that no interactive answer is available.
 
 ### [Goals](../extensions/goal/README.md)
 
-The goal extension adds persistent, branch-safe objectives, progress evidence, budgets, pause/resume controls, and strict completion/blocker gates. Use `/goal` for the operator UI and the `create_goal`, `get_goal`, `update_goal_progress`, and `update_goal` tools for agent-controlled state.
+Persistent, branch-safe objectives with an evidence checklist, token budgets, pause and resume, automatic continuation, and strict completion and blocker gates. `/goal` opens the control center; the model uses `create_goal`, `get_goal`, `update_goal_progress`, and `update_goal`. Goals are created only on explicit request.
 
 ### [Task List](../extensions/task-list/README.md)
 
-`task_list` gives the active model a branch-safe ordered checklist for ordinary multi-step work; it is separate from persistent Goals and may be used alongside them. Writes replace the full list, retain stable IDs, support pending/in-progress/completed/blocked/cancelled states and priorities, and require an active item while pending work remains. The prompt contract requires same-message list/action calls and verified updates only at task-level transitions—not after routine file reads, edits, commands, or other tool calls. A runtime reminder catches multi-action work that starts without a list; final reconciliation catches unfinished bookkeeping.
-
-State is stored in Pi session entries and reconstructed on resume, reload, and tree navigation. Active work is re-injected when compaction removes the latest snapshot from model context. `/tasks` opens the interactive dashboard and direct editor; the compact live widget auto-hides after all work finishes. Subagents receive the same tool under every capability policy, but each child maintains its own session-local list rather than changing the parent's list.
+`task_list` keeps a branch-safe checklist for requests with several separate deliverables, long multi-phase work, or an explicit request for a plan. Single-objective work goes ahead without a list, and the extension never prompts the model to create one. When compaction removes the latest list from context, the unfinished items are added back. `/tasks` opens the dashboard and editor. Task List is independent of Goals and can run alongside one.
 
 ### [Subagents](../extensions/subagents/README.md)
 
-The subagent extension runs flat Pi child agents with profiles, capability policies, continuation, result delivery, optional worktrees, pre-warmed task dispatch, instant cascading cancellation, cross-session persistence, and a dashboard. Configuration lives in `<agent-dir>/subagents.json`; trusted projects may override it through their Pi config directory. The configured concurrency ceiling is 50.
-
-The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. These lifecycle operations render as compact expandable main-chat cards; only active manager entries contribute to the bounded Active work dock, while workflow progress is intentionally omitted from the footer so persisted history cannot inflate or duplicate live status. Cancellation and reload interruption use a distinct `cancelled` state rather than `error`. All completed and cancelled production subagent snapshots and transcripts persist across Pi restarts (`<agent-dir>/subagents/runs/`), allowing `resume_from` to resume completed workers at any point. Interruption immediately cascades across all child fibers in `<10ms`. Child settlement stays in a private extension queue while the parent is active, then starts one custom-result turn at Pi's safe idle edge with the summary guaranteed in model context and never rendered as user-authored or follow-up input; status tools are for explicit inspection, not waiting.
+Flat Pi child agents with profiles, capability policies, context forks, resumable sessions, optional git worktree isolation, peer messaging, and a takeover dashboard. Children cannot start agents. The model delegates only when the user asks. Results are delivered as custom messages that start a parent turn when the parent is idle. Configuration lives in `<agent-dir>/subagents.json`, with trusted-project overrides in `.pi/subagents.json`.
 
 ### [Smart Compaction](../extensions/smart-compaction/README.md)
 
-Replaces standard context compaction with a defensive, high-fidelity continuity engine. It intercepts `session_before_compact` events and synthesizes multi-turn conversations into structured checkpoint summaries capturing primary goals and negative constraints, progress ledgers (`Done`/`In Progress`/`Blocked`), verbatim code snippets for active/uncommitted edits, exact error root causes, architectural decisions, resume anchors, and deterministic file/diff state.
-
-Key capabilities include:
-- **Fail-Closed Validation**: Strictly enforces `stopReason === "stop"`, rejects tool calls and length-truncated output, and requires all 6 section headings.
-- **Deterministic State Ledger (Schema v3)**: Machine-readable tracking of `touchedReadFiles`, `touchedModifiedFiles`, and asynchronous NUL-delimited Git worktree parsing capturing `activeDirtyFiles`, staged diffs, unstaged diffs, and untracked file previews in `CompactionEntry.details` and `<uncommitted-diff>` context.
-- **Lockfile & Bundle Diff Filtering**: Automatically isolates `package-lock.json`, `Cargo.lock`, `yarn.lock`, and minified assets from raw diffs to preserve token budgets for source code logic.
-- **Active Background Terminal Awareness**: Automatically identifies running background processes and records them under `<active-background-processes>` to prevent duplicate server launches.
-- **Hierarchical Delta-Merging & Protected-Fact Validation**: Carries forward goals and constraints, extracts negative instructions and opaque identifiers into an explicit protected-facts ledger, and rejects summaries that omit them.
-- **Closed-Record Execution Guard & Zero-Chatter Resumption**: Marks historical tasks as closed milestones to prevent accidental re-execution of completed actions, and injects a resumption directive to immediately execute the next step without conversational chatter.
-- **Classified Retry Ladder**: Distinguishes non-retryable fatal auth/quota errors from transient reasoning/length limits (retrying with reasoning off) and falling back to the active session model.
-- **Tool-Aware Bounded Serialization**: Cleans terminal control/progress noise, preserves line-safe head and tail excerpts, prioritizes failures and mutations, and bounds large write/edit arguments without modifying active session history.
-- **Selectable Threshold Policy**: Supports percentage, hard-token, and hybrid safeguards; hybrid defaults to the earlier of 95% or 400,000 tokens without changing model catalogue context windows. Pi's native reserve-token threshold may still compact earlier.
-- **Engineering-State Coverage & Telemetry**: Keeps a complete changed-file inventory before allocating bounded per-patch excerpts, and records source/serialized/summary sizes, retries, and duration in compaction details.
-- **Custom Model Routing**: `/compaction-model` selects any custom compaction model (e.g. `anthropic/claude-3-5-sonnet`, `openai/gpt-4o`) or defaults to inheriting the active session model (`inherit`). `/smart-compaction` manages settings stored in `<agent-dir>/smart-compaction.json`.
+Replaces Pi's compaction summary with a six-section checkpoint plus computed file, worktree, and background-terminal state. Summaries that are truncated, incomplete, or drop protected identifiers are rejected or repaired; if every retry fails, compaction is cancelled instead of falling back to a weaker summary. An optional percent, hard, or hybrid threshold (default: 95% or 400,000 tokens, whichever is first) adds an upper bound to Pi's own trigger. `/compaction-model` and `/smart-compaction` manage `<agent-dir>/smart-compaction.json`.
 
 ### [Background terminals](../extensions/background-terminals/README.md)
 
-Managed PTYs support servers, watchers, long builds, downloads, and interactive processes. The extension tracks up to eight concurrent terminals, retains bounded output, stores full logs in restrictive temporary directories, and stops process groups during shutdown or reload.
-
-Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. All use compact expandable main-chat cards, while running PTYs share the bounded Active work dock with elapsed time and a latest-output preview. A model-started terminal keeps completion or failure in a private extension queue while the parent is active, then starts one custom-result turn at Pi's safe idle edge with bounded output guaranteed in model context and never rendered as user-authored or follow-up input. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
+Managed PTYs for servers, watchers, long builds, and interactive programs: up to eight at once, bounded output in memory, private size-limited logs, and process-group shutdown on reload or exit. The model uses `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`; `/term` and `/ps` open the control center. When a model-started terminal exits, its result arrives as a custom message instead of requiring the model to poll.
 
 ## Web access
 
 ### [Firecrawl web](../extensions/firecrawl-web/README.md)
 
-`web_search` discovers current web, news, images, GitHub, research, and PDF sources. `web_scrape` renders difficult or JavaScript-heavy pages. `dev_search` queries the Firecrawl Developer Index across 70M+ technical docs, GitHub issues, merged PRs, and READMEs with matched code passages. Authentication resolves from environment variables, the active Pi agent `.env`, or Firecrawl CLI credentials.
+`web_search` finds web, news, image, GitHub, research, and PDF results. `web_scrape` extracts rendered or JavaScript-heavy pages. `dev_search` searches the Firecrawl Developer Index of technical docs, GitHub issues, pull requests, and READMEs. Credentials come from the environment, `<agent-dir>/.env`, or the Firecrawl CLI login.
 
 ### [Web fetch](../extensions/web-fetch/README.md)
 
-`web_fetch` retrieves a known HTTP or HTTPS URL without spending Firecrawl credits. It supports Markdown, text, and HTML output with bounded time and response size.
+`web_fetch` retrieves one known HTTP or HTTPS URL as Markdown, text, or HTML, with time and size limits and no Firecrawl credits. Local and private network addresses are blocked unless `PI_WEB_FETCH_ALLOW_PRIVATE=1` is set.
 
-## Interface and quality of life
+## Interface
 
 ### [Context Usage](../extensions/context-usage/README.md)
 
-Displays the estimated prompt and session contribution to the active context window. The default summary is a compact context-budget card; use `Ctrl+O` or `/context-usage` to cycle to compact and expanded audit views.
+A startup card estimating how much of the context window the system prompt, `AGENTS.md` files, skill index, tools, and session take. `Ctrl+O` or `/context-usage` cycles summary, compact, and expanded views.
 
 ### [Performance status](../extensions/performance-status/README.md)
 
-Adds a responsive footer-area status row while each assistant message is active and for an eight-second completion linger, then clears it to avoid permanent footer noise. Live TPS/output are marked as estimates; final TPS uses conventional decode throughput from first streamed token to message completion. TTFT and total elapsed time separately expose provider latency, prefill, and hidden reasoning; output tokens and active tools remain separate.
+A status row for the current response with TPS, time to first token, elapsed time, output tokens, and the running tool. Live values are estimates; it clears eight seconds after the response ends.
 
 ### [Input mode](../extensions/input-mode/README.md)
 
-`/input-mode` chooses what ordinary Enter does while Pi is running: steer before the next model step, interrupt the active run, or wait as a follow-up. The global selection lives in `<agent-dir>/input-mode.json`; explicit Alt+Enter follow-ups and non-interactive inputs retain native behavior. Pi does not expose extension rows in core `/settings`, so this is a dedicated extension settings picker rather than a private TUI patch.
+`/input-mode` sets what Enter does while the agent runs: `steer` (default) queues the message before the next model step, `interrupt` aborts the run and resends the message, and `follow-up` waits until the run ends. The setting lives in `<agent-dir>/input-mode.json`.
 
 ### [Shell shortcuts](../extensions/shell-shortcuts/README.md)
 
-Adds `/exit` as an alias for Pi's normal quit command. Keep this extension limited to small, low-risk conveniences.
+Adds `/exit` as an alias for `/quit`.
 
-## Per-extension details
+## Tool exposure
 
-Implementation-specific behavior and maintenance notes remain next to each extension in its own README. Package-wide installation, dependencies, state boundaries, and release rules belong in the root documentation.
+Pi 1.0 lets each tool choose how the model reaches it. Tools that ask the user, manage lifecycles, or change session state (questions, goals, task list, terminals, subagents) use `model-only` exposure: they stay declared to the model even with `codemode.mode: "only"`, and codemode scripts cannot call them. The read-only web tools keep the default `direct` exposure so scripts can call them in parallel. Read-only tools also declare `readOnlyHint` annotations for permission extensions.

package/extensions/ask-user/README.md

@@ -15,7 +15,3 @@ The tool is deliberately narrow: agents should first inspect available context a
 - Escape or Ctrl+C dismisses the question without inventing an answer.
 - In non-TUI modes, returns an unavailable result so the agent can ask plainly only if still blocked.
 - Questions, labels, descriptions, and custom answers are bounded and sanitized before display.
-
-## Validation
-
-From the repository root, run `npm run validate`.

package/extensions/ask-user/index.ts

@@ -29,12 +29,12 @@ const OptionSchema = Type.Object({
   label: Type.String({
     minLength: 1,
     maxLength: 200,
-    description: "Concise answer shown to the user",
+    description: "Short answer shown to the user",
   }),
   description: Type.Optional(
     Type.String({
       maxLength: 500,
-      description: "Optional consequence or clarification",
+      description: "Consequence or clarification",
     }),
   ),
 });
@@ -43,12 +43,12 @@ const AskUserParameters = Type.Object({
   question: Type.String({
     minLength: 1,
     maxLength: 4_000,
-    description: "One concrete decision the user needs to make",
+    description: "The one decision the user needs to make",
   }),
   options: Type.Array(OptionSchema, {
     minItems: MIN_OPTIONS,
     maxItems: MAX_OPTIONS,
-    description: "Distinct choices; include the recommended safe default when one exists",
+    description: "Distinct choices; the user can also write their own answer",
   }),
 });
 
@@ -77,8 +77,10 @@ function cleanMultiline(text: string): string {
   return sanitizeTerminalText(text).trim();
 }
 
+// Compare labels the way they are displayed (whitespace collapsed), so two
+// labels that look identical on screen are rejected as duplicates.
 function normalizedChoiceKey(label: string): string {
-  return label.normalize("NFKC").toLocaleLowerCase("en-US");
+  return oneLine(label).normalize("NFKC").toLocaleLowerCase("en-US");
 }
 
 function normalizeQuestionInput(
@@ -124,6 +126,7 @@ function createEditorTheme(theme: Theme): EditorTheme {
 export class AskUserView implements Focusable {
   private selected = 0;
   private editing = false;
+  private questionOffset = 0;
   private cachedWidth?: number;
   private cachedLines?: string[];
   private _focused = false;
@@ -133,6 +136,7 @@ export class AskUserView implements Focusable {
   private readonly requestRender: () => void;
   private readonly finish: (selection: Selection | null) => void;
   private readonly editor: Editor;
+  private readonly maxRows: () => number;
 
   constructor(
     question: string,
@@ -141,6 +145,7 @@ export class AskUserView implements Focusable {
     requestRender: () => void,
     finish: (selection: Selection | null) => void,
     editor: Editor,
+    maxRows: () => number = () => Number.POSITIVE_INFINITY,
   ) {
     this.question = question;
     this.options = options;
@@ -148,6 +153,7 @@ export class AskUserView implements Focusable {
     this.requestRender = requestRender;
     this.finish = finish;
     this.editor = editor;
+    this.maxRows = maxRows;
     this.editor.onSubmit = (value) => {
       const answer = cleanMultiline(value).slice(0, MAX_ANSWER_LENGTH);
       if (!answer) {
@@ -189,6 +195,15 @@ export class AskUserView implements Focusable {
   }
 
   handleInput(data: string): void {
+    if (matchesKey(data, Key.ctrl("c"))) {
+      this.finish(null);
+      return;
+    }
+    if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.pageDown)) {
+      this.questionOffset = Math.max(0, this.questionOffset + (matchesKey(data, Key.pageUp) ? -5 : 5));
+      this.refresh();
+      return;
+    }
     if (this.editing) {
       if (matchesKey(data, Key.escape)) {
         this.editing = false;
@@ -220,7 +235,7 @@ export class AskUserView implements Focusable {
       this.choose(this.selected);
       return;
     }
-    if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+    if (matchesKey(data, Key.escape)) {
       this.finish(null);
     }
   }
@@ -229,54 +244,61 @@ export class AskUserView implements Focusable {
     if (this.cachedWidth === width && this.cachedLines) return this.cachedLines;
     const safeWidth = Math.max(1, width);
     const inner = Math.max(1, safeWidth - 4);
-    const lines: string[] = [frameTop(this.theme, safeWidth, "Decision needed")];
-
-    for (const line of wrapTextWithAnsi(this.theme.bold(cleanMultiline(this.question)), inner)) {
-      lines.push(padLine(`  ${this.theme.fg("text", line)}`, safeWidth));
-    }
-    lines.push(padLine("", safeWidth));
+    const questionLines = wrapTextWithAnsi(this.theme.bold(cleanMultiline(this.question)), inner)
+      .map((line) => padLine(`  ${this.theme.fg("text", line)}`, safeWidth));
 
+    const rest: string[] = [padLine("", safeWidth)];
     this.options.forEach((option, index) => {
       const active = index === this.selected;
       const marker = option.custom ? "✎" : `${index + 1}.`;
       const prefix = active ? this.theme.fg("accent", "❯") : " ";
-      const label = `${prefix} ${marker} ${oneLine(option.label)}`;
-      lines.push(
-        padLine(
+      // Wrap long labels so options that differ only near the end stay distinguishable.
+      const labelLines = wrapTextWithAnsi(oneLine(option.label), Math.max(8, inner - 4));
+      labelLines.forEach((text, lineIndex) => {
+        const label = lineIndex === 0 ? `${prefix} ${marker} ${text}` : `${" ".repeat(marker.length + 3)}${text}`;
+        rest.push(padLine(
           active
             ? this.theme.bg("selectedBg", this.theme.fg("accent", label))
             : this.theme.fg(option.custom ? "muted" : "text", label),
           safeWidth,
-        ),
-      );
+        ));
+      });
       if (option.description) {
         for (const description of wrapTextWithAnsi(oneLine(option.description), Math.max(8, inner - 4))) {
-          lines.push(padLine(`      ${this.theme.fg("muted", description)}`, safeWidth));
+          rest.push(padLine(`      ${this.theme.fg("muted", description)}`, safeWidth));
         }
       }
     });
-
     if (this.editing) {
-      lines.push(padLine("", safeWidth));
-      lines.push(padLine(`  ${this.theme.fg("muted", "Your answer")}`, safeWidth));
+      rest.push(padLine("", safeWidth));
+      rest.push(padLine(`  ${this.theme.fg("muted", "Your answer")}`, safeWidth));
       for (const line of this.editor.render(Math.max(10, safeWidth - 4))) {
-        lines.push(padLine(`  ${line}`, safeWidth));
+        rest.push(padLine(`  ${line}`, safeWidth));
       }
     }
+    rest.push(padLine("", safeWidth));
+
+    // Keep the choices, editor, and controls on screen; a long question scrolls.
+    const questionRoom = this.maxRows() - rest.length - 3;
+    let visibleQuestion = questionLines;
+    let scrollHint = "";
+    if (questionLines.length > questionRoom) {
+      const room = Math.max(1, questionRoom);
+      this.questionOffset = Math.min(this.questionOffset, Math.max(0, questionLines.length - room));
+      visibleQuestion = questionLines.slice(this.questionOffset, this.questionOffset + room);
+      scrollHint = `pgup/pgdn question ${this.questionOffset + 1}-${this.questionOffset + visibleQuestion.length}/${questionLines.length} · `;
+    }
 
-    lines.push(padLine("", safeWidth));
-    lines.push(
-      padLine(
-        `  ${this.theme.fg(
-          "dim",
-          this.editing
-            ? "enter submit · escape choices"
-            : `up/down or 1-${this.options.length} choose · enter confirm · escape dismiss`,
-        )}`,
-        safeWidth,
-      ),
-    );
-    lines.push(frameBottom(this.theme, safeWidth));
+    const controls = this.editing
+      ? "enter submit · escape choices · ctrl+c dismiss"
+      : `up/down or 1-${this.options.length} choose · enter confirm · escape dismiss`;
+    const lines = [
+      frameTop(this.theme, safeWidth, "Decision needed"),
+      ...visibleQuestion,
+      ...rest,
+      padLine(`  ${this.theme.fg("dim", `${scrollHint}${controls}`)}`, safeWidth),
+      frameBottom(this.theme, safeWidth),
+    ];
     this.cachedWidth = width;
     this.cachedLines = lines.map((line) => truncateToWidth(line, safeWidth, ""));
     return this.cachedLines;
@@ -315,6 +337,8 @@ async function openQuestion(
         () => tui.requestRender(),
         complete,
         new Editor(tui, createEditorTheme(theme)),
+        // Matches the overlay's maxHeight (86%) minus its margin.
+        () => Math.max(8, Math.floor((tui.terminal.rows || 24) * 0.86) - 2),
       );
       return {
         get focused() {
@@ -348,11 +372,12 @@ export default function askUserExtension(pi: ExtensionAPI) {
     label: "Ask User",
     description:
       "Ask one multiple-choice question only when a missing user decision materially blocks safe progress. Do not use it when the answer is discoverable, the user already supplied it, or a reversible low-risk default is reasonable.",
-    promptSnippet: "Ask one materially blocking multiple-choice question with an optional custom answer",
+    promptSnippet: "Ask the user one blocking multiple-choice question.",
     promptGuidelines: [
-      "Use ask_user only when a missing choice materially blocks safe progress; first inspect available context and prefer a reversible low-risk default when that would not change scope or authority.",
-      "When using ask_user, ask one decision at a time with distinct options, explain consequences briefly, and include the recommended safe default when one exists.",
+      "Use ask_user only after checking available context, when a missing choice blocks safe progress and no reversible default fits; ask one decision with distinct options, brief consequences, and the recommended option when one exists.",
     ],
+    exposure: "model-only",
+    annotations: { readOnlyHint: true, openWorldHint: false },
     parameters: AskUserParameters,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const normalized = normalizeQuestionInput(params.question, params.options);
@@ -406,9 +431,12 @@ export default function askUserExtension(pi: ExtensionAPI) {
         invalidate() {},
       };
     },
-    renderResult(result, _options, theme) {
+    renderResult(result, _options, theme, context) {
       const details = result.details as AskUserDetails | undefined;
-      const text = !details || details.cancelled
+      const errorText = result.content.find((item) => item.type === "text")?.text ?? "invalid question";
+      const text = context.isError
+        ? `${theme.fg("error", "● not asked")} ${theme.fg("muted", oneLine(errorText))}`
+        : !details || details.cancelled
         ? theme.fg("warning", "● dismissed")
         : `${theme.fg("success", "● answered")} ${theme.fg("accent", oneLine(details.answer ?? ""))}`;
       return { render: (width: number) => [truncateToWidth(text, width)], invalidate() {} };