shariq-pi-extensions 0.3.7 → 0.4.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.
 
-## 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",
   }),
 });
 
@@ -348,11 +348,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);

package/extensions/background-terminals/README.md

@@ -10,7 +10,9 @@ Session-scoped background pseudo-terminals for Pi. The extension combines Codex-
 - `list_terminals` — list running and settled terminals.
 - `stop_terminal` — stop complete process groups with TERM-to-KILL escalation.
 
-Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Terminal lifecycle tools render as compact main-chat cards with expandable output, and running terminals appear in the shared bounded **Active work** dock with elapsed time and the latest output line. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. 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 bounded output guaranteed in model context and never rendered as user-authored or follow-up input, so the parent can continue other work or end its turn rather than poll.
+Each output response carries a byte cursor; pass it to the next read or write to get only new output. The tools render as compact cards with expandable output, use `model-only` exposure, and running terminals appear in the shared **Active work** dock with elapsed time and the latest output line.
+
+When a model-started terminal exits, its status and a bounded output tail are delivered as a custom message. An idle parent starts a new turn for it; a busy parent receives it, together with any other pending results, when its run settles. The message never appears as user-authored or follow-up input, and reading the terminal does not suppress it.
 
 ## User interface
 
@@ -34,10 +36,4 @@ Each output response carries a byte cursor. Pass it to the next read/write opera
 - Output is sanitized before TUI or model rendering.
 - Processes run in their own PTY process group and are stopped on session shutdown, replacement, or reload.
 - Shutdown and stop operations are bounded and escalate from SIGTERM to SIGKILL.
-- Model-started terminals immediately hand one model-visible completion/failure follow-up to Pi; Pi queues it while the parent is active or starts the next parent turn when idle.
-- Reading settled output does not consume or suppress the automatic completion delivery.
-- Completion delivery is keyed by terminal id to prevent duplicate follow-ups.
-
-## Validation
-
-From the repository root, run `npm run validate`.
+- Completion delivery is keyed by terminal id, so each terminal produces at most one result message.

package/extensions/background-terminals/index.ts

@@ -149,21 +149,20 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     name: "start_terminal",
     label: "Start Background Terminal",
     description:
-      "Start a command in a real background pseudo-terminal (PTY) and return its terminal id. " +
-      "Use for development servers, watchers, long builds, and commands that need terminal semantics. " +
-      "The PTY accepts later input through write_terminal, captures a bounded live tail in memory, writes a size-limited private temporary log, and is stopped at session shutdown. " +
-      `At most ${MAX_RUNNING_TERMINALS} terminals may run concurrently.`,
-    promptSnippet: "Start an interactive or long-running command in a managed background PTY.",
+      "Run a shell command in a background pseudo-terminal (PTY) and return its terminal id. " +
+      "The process keeps running while you work; when it exits, its final output arrives as a new message that starts your next turn. " +
+      `At most ${MAX_RUNNING_TERMINALS} terminals run at once, and all of them stop when the session ends.`,
+    promptSnippet: "Run a long or interactive command in a background PTY.",
     promptGuidelines: [
-      "Use start_terminal by default for servers, watchers, downloads, long or uncertain builds and tests, interactive shells, and any command that should not occupy the main turn; reserve bash for short commands whose result is needed immediately. Never use a large bash timeout merely to wait for long work.",
-      "After start_terminal returns, continue only genuinely independent work. If none remains, end the turn immediately. Terminal settlement stays in a private extension queue while the parent is active and starts one custom-result turn at Pi's safe idle edge. When that result invokes the parent, continue the original task immediately without waiting for the user or rereading the same terminal; do not call read_terminal, list_terminals, or start a timer merely to check whether it finished.",
-      "Use stop_terminal when a managed process is no longer needed. Background terminals are session-scoped and are stopped during session shutdown or reload.",
+      "Use start_terminal for servers, watchers, long builds or test runs, and interactive commands. Use bash for short commands whose output you need now, not with a long timeout.",
+      "After start_terminal, continue independent work or end the turn. When the terminal's result message arrives, continue the task from it instead of polling with read_terminal or list_terminals.",
     ],
+    exposure: "model-only",
     parameters: Type.Object({
-      command: Type.String({ minLength: 1, maxLength: 32_000, description: "Shell command to run in the PTY." }),
-      title: Type.Optional(Type.String({ maxLength: 100, description: "Short human-readable terminal name; defaults to the command." })),
-      working_dir: Type.Optional(Type.String({ description: "Working directory relative to the current workspace, or an absolute directory." })),
-      wait_ms: Type.Optional(Type.Integer({ minimum: 0, maximum: 5_000, description: "Optional initial wait for startup output; default 300ms." })),
+      command: Type.String({ minLength: 1, maxLength: 32_000, description: "Shell command." }),
+      title: Type.Optional(Type.String({ maxLength: 100, description: "Short name; defaults to the command." })),
+      working_dir: Type.Optional(Type.String({ description: "Directory, relative to the workspace or absolute." })),
+      wait_ms: Type.Optional(Type.Integer({ minimum: 0, maximum: 5_000, description: "Wait for startup output; default 300." })),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const command = params.command.trim();
@@ -229,14 +228,14 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     name: "read_terminal",
     label: "Read Background Terminal",
     description:
-      "Read output from a managed background terminal only when the user asks for progress or current output is required for immediate interaction. " +
-      "Do not use it to wait for completion: terminal settlement automatically sends a follow-up that starts the next parent turn. " +
-      "Pass the cursor from the previous terminal result to receive only newer output. Output is tail-truncated for model context; the private log path is reported when available.",
-    promptSnippet: "Read new output from a managed background terminal by id and cursor.",
+      "Read a background terminal's output since a cursor; omit the cursor for the retained tail. " +
+      "Use it when the user asks for progress or the process is waiting for input. Completion output arrives on its own.",
+    exposure: "model-only",
+    annotations: { readOnlyHint: true, openWorldHint: false },
     parameters: Type.Object({
-      id: Type.String({ description: 'Terminal id, for example "term-1".' }),
-      cursor: Type.Optional(Type.Integer({ minimum: 0, description: "Cursor returned by the previous terminal operation; omit for the retained tail." })),
-      wait_ms: Type.Optional(Type.Integer({ minimum: 0, maximum: 10_000, description: "Long-poll duration when no newer output exists; default 0." })),
+      id: Type.String({ description: 'Terminal id, such as "term-1".' }),
+      cursor: Type.Optional(Type.Integer({ minimum: 0, description: "Cursor from the previous terminal result." })),
+      wait_ms: Type.Optional(Type.Integer({ minimum: 0, maximum: 10_000, description: "Wait for new output; default 0." })),
     }),
     async execute(_toolCallId, params, signal) {
       const result = await getManager().read(params.id, {
@@ -271,15 +270,15 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     name: "write_terminal",
     label: "Write Background Terminal",
     description:
-      "Send input to a running background PTY, optionally press Enter, wait briefly, and return output produced since the supplied cursor. " +
-      "Use input \\u0003 with press_enter=false to send Ctrl+C inside the PTY; use stop_terminal to terminate the managed process tree.",
-    promptSnippet: "Send input to a running background PTY and collect its response.",
+      "Send input to a running background terminal and return the output it produces. Enter is appended unless press_enter is false; " +
+      "send \\u0003 with press_enter=false for Ctrl+C. Use stop_terminal to end the process.",
+    exposure: "model-only",
     parameters: Type.Object({
       id: Type.String({ description: "Terminal id." }),
-      input: Type.String({ maxLength: 65_536, description: "Text or control character to write." }),
-      press_enter: Type.Optional(Type.Boolean({ description: "Append Enter after the input; default true." })),
-      cursor: Type.Optional(Type.Integer({ minimum: 0, description: "Previous output cursor for incremental output." })),
-      wait_ms: Type.Optional(Type.Integer({ minimum: 0, maximum: 5_000, description: "Wait for resulting output; default 250ms." })),
+      input: Type.String({ maxLength: 65_536, description: "Text or control characters." }),
+      press_enter: Type.Optional(Type.Boolean({ description: "Default true." })),
+      cursor: Type.Optional(Type.Integer({ minimum: 0, description: "Cursor from the previous terminal result." })),
+      wait_ms: Type.Optional(Type.Integer({ minimum: 0, maximum: 5_000, description: "Wait for output; default 250." })),
     }),
     async execute(_toolCallId, params, signal) {
       const current = getManager().get(params.id);
@@ -317,7 +316,9 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
   pi.registerTool({
     name: "list_terminals",
     label: "List Background Terminals",
-    description: "List managed background terminals with status, pid, elapsed time, output size, and working directory.",
+    description: "List background terminals with id, status, pid, elapsed time, and working directory.",
+    exposure: "model-only",
+    annotations: { readOnlyHint: true, openWorldHint: false },
     parameters: Type.Object({}),
     async execute() {
       const terminals = getManager().list();
@@ -340,10 +341,11 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
   pi.registerTool({
     name: "stop_terminal",
     label: "Stop Background Terminals",
-    description: "Stop one or more managed background terminal process groups, escalating from SIGTERM to SIGKILL when needed, and return their final states.",
-    promptSnippet: "Stop managed background terminals and their process trees.",
+    description: "Stop background terminals by id (SIGTERM, then SIGKILL) and return their final status.",
+    exposure: "model-only",
+    annotations: { destructiveHint: true, openWorldHint: false },
     parameters: Type.Object({
-      ids: Type.Array(Type.String(), { minItems: 1, maxItems: 32, description: "Terminal ids to stop." }),
+      ids: Type.Array(Type.String(), { minItems: 1, maxItems: 32 }),
     }),
     async execute(_toolCallId, params) {
       const terminals = await getManager().kill(params.ids);

package/extensions/context-usage/index.ts

@@ -168,9 +168,11 @@ type ContextUsageGlobal = typeof globalThis & {
 
 const g = globalThis as ContextUsageGlobal;
 
-const PROJECT_CONTEXT_RE = /\n?<project_context>\n\n[\s\S]*?\n<\/project_context>\n?/;
+// Pi 1.0 renders structured sections as `<name>\n...\n</name>`; older releases
+// separated the project context with a blank line. Accept both.
+const PROJECT_CONTEXT_RE = /\n?<project_context>\n\n?[\s\S]*?\n<\/project_context>\n?/;
 const PROJECT_INSTRUCTIONS_RE = /<project_instructions path="([^"]*)">\n([\s\S]*?)\n<\/project_instructions>/g;
-const AVAILABLE_SKILLS_RE = /\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<available_skills>[\s\S]*?<\/available_skills>/;
+const AVAILABLE_SKILLS_RE = /(?:\n?<skills>\n|\n\n)The following skills provide specialized instructions for specific tasks\.[\s\S]*?<available_skills>[\s\S]*?<\/available_skills>(?:\n<\/skills>)?/;
 const SKILL_RE = /<skill>\s*<name>([\s\S]*?)<\/name>[\s\S]*?<description>([\s\S]*?)<\/description>[\s\S]*?<location>([\s\S]*?)<\/location>\s*<\/skill>/g;
 const DEFAULT_MODE: ViewMode = "summary";
 const OPENAI_TOOL_TEXT_FRAGMENT_DENOMINATOR = 6.6;
@@ -1538,9 +1540,12 @@ function renderSummary(snapshot: PrefixSnapshot, theme: Theme, width = 80): stri
     window && window > 0 ? `/ ${contextWindowLabel(window)}` : undefined,
     percent ? `· ${percent}` : undefined,
   ].filter(Boolean).join(" ");
-  const breakdown = snapshot.sections
-    .map((section) => `${summarySectionLabel(section.title)} ~${compactCount(sectionTokens(section))}`)
-    .join(SEP);
+  const totals = new Map<string, number>();
+  for (const section of snapshot.sections) {
+    const label = summarySectionLabel(section.title);
+    totals.set(label, (totals.get(label) ?? 0) + sectionTokens(section));
+  }
+  const breakdown = [...totals].map(([label, tokens]) => `${label} ~${compactCount(tokens)}`).join(SEP);
   const ctrlO = keyText("app.tools.expand") || "Ctrl+O";
   const rows = [
     ` ${theme.fg("text", budgetParts)}`,