@preapexis/piexis 0.1.2 → 0.2.4

package/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish npm package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - run: npm ci --ignore-scripts
+      - run: npm run check
+      - run: npm test
+
+      - name: Verify version tag
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          TAG=${GITHUB_REF_NAME#v}
+          test "$VERSION" = "$TAG"
+
+      - run: npm publish --access public

package/AGENTS.md

@@ -1,58 +1,38 @@
 # Agents Guide
 
-## Project
+## Project and layout
 
-Piexis (`@preapexis/piexis`) is a TypeScript Pi package providing permission-mode extensions, skills, prompts, and themes. It requires Node.js 24+ and a current Pi release; `README.md` names Pi 0.85.1 as tested.
+Piexis (`@preapexis/piexis`) is a TypeScript Pi package providing interactive questions, UI extensions, skills, prompts, and themes. Node.js 22.19+ and a current Pi release are required.
 
-## Layout
-
-- `extensions/mode.ts`: permission approvals, mode commands/flags, session restoration, and mode-specific agent instructions.
-- `extensions/ask-question.ts`: sequential, interactive `AskQuestion` tool; requires the TUI to collect answers.
-- `extensions/ui.ts`: local Pi header, footer, and activity/status integration.
-- `lib/mode-policy.ts`: mode names, tool allowlists, and Accept Edits bash-command classification.
-- `lib/permission-classifier.ts`: Auto-mode model review, response validation, timeout, and cancellation.
-- `lib/permission-config.ts`: project configuration initialization and classifier model selection.
-- `skills/`: bundled skills with task-specific `SKILL.md` guidance; `prompts/init.md`: bundled `/init` prompt; `themes/orange.json`: bundled theme.
-- `package.json`: Pi resource manifest and npm scripts; `tsconfig.json`: strict TypeScript configuration.
+- `extensions/ask-question.ts`: sequential interactive `AskQuestion` tool; requires the TUI.
+- `extensions/agents.ts`: five agent profiles and sequential subprocess subagents; `lib/agents.ts` owns configuration/routing, and `lib/subagent-runner.ts` owns protocol/cancellation. User/project `agent.json` files configure models and effort, with legacy `agents.json` fallback. Accepted project setup creates a missing `.pi/agent.json` scaffold without overwriting existing configuration.
+- `extensions/ui.ts`: project header, activity footer, Git branch, model, and context usage.
+- `extensions/recommended-tools.ts`: automatic opt-in project setup for Pi's native `grep`, `find`, and `ls` tools.
+- `skills/`: task-specific `SKILL.md` guidance.
+- `prompts/`: bundled `/init`, `/commit`, and `/summary` prompts.
+- `themes/orange.json`: bundled theme.
+- `package.json`: resource manifest and npm scripts; `tsconfig.json`: strict TypeScript configuration.
 
 ## Development
 
-Commands supported by the manifest or README:
-
-| Command | Purpose / caveat |
+| Command | Purpose |
 | --- | --- |
 | `npm ci --ignore-scripts` | Install locked dependencies without lifecycle scripts. |
 | `npm run check` | Type-check with `tsc --noEmit`. |
-| `npm test` | Runs `node --test tests/*.test.mjs`, including extension and skill-routing contracts. |
-| `npm run test:sandbox` | Runs `PIEXIS_REQUIRE_SANDBOX=1 node --test tests/mode-sandbox.test.mjs`; target is currently absent, and the script uses POSIX environment-assignment syntax. |
-| `pi -e ./extensions/mode.ts` | Preview the permission extension only, not the bundled prompts, skills, themes, or other extensions. |
-
-There are no separate build, lint, or format scripts. No CI configuration is present in this checkout; do not infer CI coverage from the README.
+| `npm test` | Run `node --test tests/*.test.mjs`. |
+| `pi -e ./extensions/ask-question.ts` | Preview only the question extension. |
 
-## Current-checkout caveats
+There are no separate build, lint, or format scripts, and no CI configuration in this checkout.
 
-- Parts of `README.md` and `MODE.md` describe older or intended behavior. Check `extensions/` and `lib/` before relying on security or lifecycle claims.
-- The sandbox workers, broker, guards, and test suites from the previous implementation are absent. Although `@anthropic-ai/sandbox-runtime` remains pinned in `package.json`, the current permission implementation does not invoke it. Do not claim OS containment, protected-path enforcement, or workspace-only writes.
-- Plan currently blocks all tools except the read-tool allowlist and `AskQuestion`, including all bash calls and file edits. The README's writable `.pi/plans/*.md` exception and `delete_plan` tool are not implemented in the current source.
-- The current default is Manual (`default`), not Auto. Old Build/YOLO mode names and user-level `readRoots`/`allowedDomains` configuration do not describe the current implementation.
-
-## Conventions
+## Conventions and safety
 
 - Use ESM and strict TypeScript with NodeNext module resolution and ES2022 targeting. Local imports use explicit `.ts` extensions.
-- Match nearby source style: two-space indentation, double-quoted strings, and semicolons. Extensions export a default registration function receiving `ExtensionAPI`; shared permission logic belongs in `lib/`.
-- Keep changes focused and preserve existing permission checks, approval/cancellation behavior, and headless handling.
-- Add or update tests for behavior changes. Historical tests used `node:test`, `node:assert/strict`, and `.test.mjs` files; use disposable fixtures, not real credentials.
-- Do not commit generated output, secrets, dependency directories, or local configuration. `.pi/` and `.kilo/` are ignored local state, not package resources.
-
-## Security and workflow
-
-- Permission-mode changes belong to the user. Do not bypass denied operations or change modes to evade restrictions.
-- The six modes are `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, and `bypassPermissions`. `Alt+M` cycles the first four, omitting Auto when unavailable; `/plan` enters Plan. `dontAsk` and `bypassPermissions` are launch-only. Mode changes require an idle agent.
-- Preserve Auto's fail-closed behavior on classifier failure or invalid responses. The classifier treats task/action contents as untrusted data and uses Pi's existing authentication; never persist credentials in project settings.
-- Configuration lives under Pi's `CONFIG_DIR_NAME` (normally `.pi/`). Initialization creates missing `settings.json` and `permission-modes.json` without overwriting existing files. `PI_PERMISSION_CLASSIFIER=provider/model` overrides the configured classifier model.
-- Session approvals are in-memory and scoped to a tool. Without permission UI, actions requiring approval are denied; `dontAsk` denies non-pre-approved actions. Bypass skips extension-level permission checks and is not isolation.
-- Keep `AskQuestion` available in every permission mode.
+- Match nearby source style: two-space indentation, double-quoted strings, and semicolons. Extensions export a default registration function receiving `ExtensionAPI`.
+- Preserve interactive cancellation and non-TUI handling. Add or update `node:test`/`node:assert/strict` tests for behavior changes, using disposable fixtures rather than credentials.
+- Preserve unrelated working-tree changes and intentional deletions. Do not commit generated output, secrets, dependency directories, or local configuration. `.pi/` and `.kilo/` are ignored local state, not package resources.
+- Permission modes, approval/classifier logic, plan execution handoffs, and background workers have been removed. Piexis does not enforce tool-access restrictions or provide sandboxing; respect host restrictions and other installed extensions.
+- Do not delete existing user settings, session records, or retained task worktrees as part of routine package changes.
 
 ## Validation
 
-For implementation changes, run `npm run check` and relevant tests when their files are available. Report missing suites and unexecuted checks explicitly; an empty or skipped run does not establish coverage or security. Review the diff and confirm that no credentials or unrelated files are included.
+Run `npm run check` and relevant tests for implementation changes. Report unexecuted checks explicitly; skipped or empty runs do not establish coverage. Review the diff for credentials and unrelated changes before finishing.

package/README.md

@@ -1,181 +1,125 @@
-# Piexis
+# PieXis
 
-Piexis is a Pi package with permission/approval controls, background Git-worktree tasks, prompts, skills, and UI resources. It requires Node.js 22.19+ and a current Pi release (local runtime checks passed with Pi 0.85.1 and 0.87.1 on Linux).
+PieXis is a Pi package with interactive questions, coding skills, prompts, and terminal UI resources. It requires Node.js 22.19+ and a current Pi release.
 
-> [!WARNING]
-> **Piexis permission controls are not a security boundary.** They help prevent accidental or unapproved agent tool actions; they do **not** provide OS-level sandboxing, filesystem isolation, workspace-only filesystem enforcement, protected-path enforcement, network isolation, or network allowlisting. Run Pi in an appropriate container, VM, sandbox, or restricted user account when executing untrusted code or allowing unattended/high-autonomy agents.
-
-## Install and use
+## Installation
 
 ```sh
-npm ci --ignore-scripts
-pi install /absolute/path/to/piexis
+pi install npm:@preapexis/piexis
 ```
 
-Installing the package loads its declared extensions, prompts, skills, and theme. Loading only `extensions/mode.ts` loads only the permission extension. Restart Pi or run `/reload` after installation.
+Restart Pi or run `/reload` after installation. The package loads AskQuestion, agent profiles/subagents, the custom header/footer, automatic recommended-tool setup, prompts, skills, and the theme.
 
-Use `Alt+M` while the agent is idle to cycle Manual → Accept Edits → Plan → Auto (when configured). `/plan [task]` enters Plan mode. Start `dontAsk` and `bypassPermissions` only with `--permission-mode`; `--dangerously-skip-permissions` selects `bypassPermissions`.
+## Resources
 
-## Permission modes
+- **AskQuestion** provides keyboard-driven single/multi selection and text questions in the interactive TUI, with validation, answer review, and cancellation. It requires terminal input and output.
+- **UI** shows project information, agent activity, Git branch, model, and context usage. The startup header shows three random, category-labelled tips from `lib/ui-tips.json`, preferring different categories and staying stable across redraws. Tips cycle without repeats until the list is exhausted within the extension runtime; `/reload` starts a new cycle. Each JSON entry has `category` and `text` fields; edit them to change the recommendations.
+- **Recommended tools** offers to enable native `grep`, `find`, and `ls` for the project at startup; no slash command is needed.
+- **Agents** provides `plan`, `orchestrator`, `debug`, `ask`, and `code` profiles, all callable through the `subagent` tool. Small delegated tasks can automatically use a cheaper model.
+- **Skills** cover implementation, debugging, review, design, refactoring, validation, and document workflows. Bundled **caveman** adds concise chat style; **ponytail** guides the smallest complete coding change. Only their core instructions are included, not upstream hooks or companion skills. Source revisions and licenses live beside each skill.
+- **Prompts** include `/init`, `/commit`, and `/summary`. `/init` adds workflow guidance to `AGENTS.md`: caveman for responses, grilling for clarification questions, and ponytail for building. These are agent instructions, not runtime enforcement.
 
-| Mode | Behavior |
-| --- | --- |
-| **Manual** (`default`) | Project-local ordinary reads/searches, a tiny harmless Bash-builtin set, and `AskQuestion` are pre-approved; other actions need approval. **Allow once** applies only to the current call. |
-| **Accept Edits** (`acceptEdits`) | Also pre-approves ordinary project-local `edit` and `write` calls. Bash outside the harmless-builtin set, external paths, and sensitive paths still require approval. |
-| **Plan** (`plan`) | Allows project-local ordinary reads, task status/diff inspection/cancellation, and `AskQuestion`; Bash, external/sensitive path-tool reads, task creation/apply/cleanup, and file mutations are blocked. |
-| **Auto** (`auto`) | Directly permits ordinary project-local reads, `edit`, and `write`. Sensitive paths, protected configuration edits, uncertain recursive searches, and malformed or unsupported paths/tools remain denied. Bash outside the harmless-builtin set and eligible narrow session grants, plus remaining known external actions, receive intent-aware model review. Missing authorization, timeout, error, or invalid review denies the action. |
-| **Don't Ask** (`dontAsk`) | Permits only pre-approved reads/questions and harmless Bash builtins; denies other calls without a dialog. Launch-only. |
-| **Bypass Permissions** (`bypassPermissions`) | Skips **Piexis extension-level permission checks**. It does not enter or escape a sandbox, and does not override OS permissions or other extensions. Task scope/confirmation safeguards remain. Launch-only. |
+- **Theme** provides the bundled orange palette.
+
+Caveman and ponytail ship with this package; no separate installation is needed. Their upstream standalone installation commands are:
+
+```sh
+npx skills add https://github.com/juliusbrussee/caveman --skill caveman
+npx skills add https://github.com/dietrichgebert/ponytail --skill ponytail
+```
 
-Approval UI is fail-closed: calls requiring approval are denied when no permission UI is available. Relative paths resolve against the tool's current working directory, independently of the repository boundary. Both requested and resolved paths are checked; a symlink that resolves outside the project is treated as external, and malformed or unresolvable paths are denied. This is a permission policy, not filesystem sandboxing.
+Avoid loading standalone copies alongside the bundled skills, which can cause name collisions. In Pi, explicitly invoke the bundled skills with `/skill:caveman` and `/skill:ponytail`.
 
-`grep`, `find`, and `glob` receive a bounded, metadata-only subtree preflight. Sensitive descendants, symlinks, external trees, inspection errors, or exhaustion of the 2,000-entry/directory budget require fresh one-time approval in Manual/Accept Edits and are denied in Auto/Plan/Don't Ask. No file contents are read by this preflight. It deliberately does not assume ignore rules exclude sensitive files; large repositories (including their `.git` contents) may require narrowing the search directory. It does not filter tool results or prevent filesystem races.
+## Automatic tool setup
 
-Credential categories include environment files, common credential files, SSH/cloud/key directories, and Pi authentication files. Path-tool mutations (`edit`/`write`) beneath `.git` and Pi's configuration directory (`CONFIG_DIR_NAME`, normally `.pi`) require explicit approval, including settings, permission configuration, and extensions. Ordinary non-secret configuration reads remain permitted. `.env.example` is not automatically assumed secret-free: explicitly approve that exact file in Manual/Accept Edits without granting access to other environment files.
+On startup in a trusted project with terminal input/output, Piexis offers any pending setup: available, inactive `grep`, `find`, and `ls` tools, or a missing project agent configuration when the agent extension is loaded. Earlier tool approval does not hide the new agent setup; if tools are already configured, the prompt offers only `.pi/agent.json` creation and leaves tool settings unchanged:
 
-Session approvals are in-memory and never persisted. Filesystem approvals remain scoped to the file/directory and exact tool operation (`read`, `write`, `edit`, etc.). Broad grants do not authorize credential paths or protected path-tool configuration edits. Recursive-boundary requests offer only one-time approval or denial. Auto now honors eligible exact-file/directory grants and fingerprinted Bash grants after non-overridable checks, but only for the same verified current request. Whole-tool/project and legacy executable grants never bypass Auto review. Session approvals are cleared on branch navigation and session replacement.
+- **Enable** saves the project choice and tool additions in `.pi/settings.json`, then activates them in the current session without removing active tools or extensions. It also creates `.pi/agent.json` if neither that file nor legacy `.pi/agents.json` exists. The scaffold uses the current model for `model`, `small_model`, and `subagent_model`, preserves user-level agent overrides, and populates all five `subagent_variant_overrides` with `model` and `effort`. Default effort is `high` for plan/orchestrator/debug, `low` for ask, and `medium` for code. Existing agent configuration is never overwritten. If creation fails or no model is selected, tools remain enabled and a warning explains how to configure agents manually.
+- **Not now** (the default) or Esc changes nothing. The prompt is shown at most once per project per extension runtime; a subsequent startup or reload may offer it again.
+- **Don't ask again** records `"disabled"` only for features offered in that prompt: `piexis.recommendedTools` for tool setup and `piexis.agentSetup` for agent setup. It changes neither tools nor agent files. Approval records `"enabled"`. An existing `agent.json` or legacy `agents.json` completes agent setup; if creation failed or the file was removed, startup offers it again unless `agentSetup` is `"disabled"`. Remove the corresponding disabled preference to allow another offer.
 
-The advanced Manual/Accept Edits option remains **Allow ALL bash actions for this session**. This is deliberately broad: it can still modify configuration or access host resources. The bounded Bash checks do not constrain arbitrary program or extension internals. `AskQuestion` remains available in every mode, including after a denial stop.
+User-level settings are never written. Other project settings and existing `piexis` keys are preserved. Modern Pi uses additive `defaultTools` entries such as `["+grep", "+find", "+ls"]`. Older Pi releases without additive support use a plain list of the four default tools plus the approved additions, only when no tool selection is configured.
 
-### Permission decision order
+Setup skips non-TUI/non-TTY runs, untrusted projects, and runs with CLI tool-selection overrides (`--tools`, `--exclude-tools`, `--no-tools`, or `--no-builtin-tools`, including their short forms). Explicit `defaultTools` allowlists, including an empty list, are left alone; they can still receive an agent-only setup offer. Additive `-tool` exclusions remain respected. Only Pi's available built-in tools are offered. Malformed or non-regular settings files and settings changed during the prompt are not overwritten; a warning explains why setup was skipped.
 
-`lib/mode-policy.ts` exposes the shared, UI-independent `evaluatePermission` function. Foreground mode handling and the parent task broker supply the mode, tool arguments, current directory, workspace boundary, and authorization context; actor identity itself grants no authority. Worker calls also require a live delegated authorization and pass capability/path-scope checks. Foreground grants are never inherited by workers. The host still validates tool schemas.
+The setup extension is `extensions/recommended-tools.ts`; package resource filtering can omit it. Native `find` provides file discovery by glob pattern; no wrapper extension is needed.
 
-1. `AskQuestion` retains its exception. Worker capability/path-scope checks precede the parent mode's Bypass exception.
-2. Reject malformed inputs and unresolvable paths.
-3. Apply Plan restrictions, bounded Bash analysis, and Auto non-overridable checks.
-4. Match eligible scoped approvals and mode defaults. Auto rejects broad/stale grants; unsupported shell forms cannot match a reusable narrow Bash grant.
-5. Return `require-approval`, or deny in Don't Ask. Model review and approval UI are handled by the extension and fail closed.
+## Agents and subagents
 
-Repository configuration currently selects models only; there are no repository-provided allow rules or trusted-environment grants. Future permission-widening settings must require user confirmation rather than trusting repository declarations. Background tools are classified individually. Their handlers authorize task creation with the complete brief and require explicit confirmation for actual patch application and validated cleanup; this is not a blanket allow for custom tools.
+Use `/agent` to select a profile, `/agent plan` to switch directly, or `pi --agent orchestrator` at startup. **Alt+A** cycles `plan → orchestrator → debug → ask → code` while idle; cycling is blocked while an agent is running. The footer shows the active profile (`agent:code`) and, on wider terminals, the shortcut hint. `/hotkeys` lists the shortcut. `code` is the default. Profile choices follow the active session branch. Profiles add instructions rather than replacing repository guidance or changing the main session's tools:
 
-## Configuration
+| Profile | Purpose |
+| --- | --- |
+| `plan` | Explore and return a plan; no implementation |
+| `orchestrator` | Delegate focused tasks and combine verified results |
+| `debug` | Establish evidence, diagnose, fix, and verify |
+| `ask` | Answer questions from code/documentation; no changes |
+| `code` | Implement scoped changes and run checks |
 
-Launching Piexis does not create `.pi/` or project configuration. It uses in-memory defaults when `.pi/permission-modes.json` is absent. Run `/piexis-init` to explicitly create `.pi/settings.json` and `.pi/permission-modes.json`; existing files are never overwritten.
+All five are callable with `subagent({ "agent": "ask", "task": "Locate the configuration loader" })`. The orchestrator chooses when to delegate; delegation is not an automatic pipeline. Each child receives its task, normal Pi resources, and profile instructions, **not** the parent's conversation. Supply necessary context explicitly. Children share the workspace, so calls are sequential; delegation stops at two child levels. A delegated orchestrator can call other subagents at the second level.
 
-`permission-modes.json` can select Auto's authenticated classifier and permitted background models:
+Optional configuration lives in `~/.pi/agent/agent.json` (or `$PI_CODING_AGENT_DIR/agent.json`) and trusted-project `.pi/agent.json`. Legacy `agents.json` is still read when `agent.json` is absent in that scope; no files are renamed or deleted. Project fields override user fields; per-variant overrides merge by field. Accepting **Enable** during project setup creates the project scaffold only when no project agent configuration exists; user-level files are never written. Defaults use the current model unless user-level configuration specifies another model. New scaffolds set `delegate_exploration` to `false`; edit it to opt in. `/agent-config` creates a missing project config or fills only its missing settings with defaults, preserving every configured value. It uses the active model when it must choose a model. Generated files include `$schema` for editor validation; configuration reloads on each profile switch and delegation. Use exact `provider/model-id` strings from `/model`, not fuzzy aliases:
 
 ```json
 {
-  "version": 1,
-  "initialized": true,
-  "classifier": {
-    "provider": "anthropic",
-    "model": "claude-haiku-4-5",
-    "timeoutMs": 15000
-  },
-  "background": { "models": ["anthropic/claude-haiku-4-5"] }
+  "$schema": "https://raw.githubusercontent.com/VarunGaikwad/piexis/main/schemas/agent.schema.json",
+  "model": "provider/default-model",
+  "small_model": "provider/default-model",
+  "subagent_model": "provider/default-model",
+  "delegate_exploration": true,
+  "subagent_variant_overrides": {
+    "plan": { "model": "provider/default-model", "effort": "high" },
+    "orchestrator": { "model": "provider/default-model", "effort": "high" },
+    "debug": { "model": "provider/default-model", "effort": "high" },
+    "ask": { "model": "provider/default-model", "effort": "low" },
+    "code": { "model": "provider/default-model", "effort": "medium" }
+  }
 }
 ```
 
-`PI_PERMISSION_CLASSIFIER=provider/model` overrides the configured classifier. Configuration contains no credentials; Pi authentication is reused.
-
-## Auto review policy and privacy
-
-Auto uses **deterministic policy → one model reviewer**, not a multi-model pipeline. Ordinary local reads/edits do not call the reviewer. Review compares the proposed action against the current user request and earlier user constraints, rather than treating ordinary-looking command names as sufficient authorization.
-
-| Review category | Rule |
-| --- | --- |
-| Ordinary development | Must serve the current requested task |
-| External filesystem | Intent must cover the external target and operation |
-| Destructive changes | Specific authorization for operation, target, and scope |
-| Credential exploration/exposure | Denied; normal use of an authenticated CLI is distinct |
-| Data egress | Authorization must cover destination, payload, and purpose |
-| Production/shared systems | Explicit target and operation required |
-| Privilege/security weakening | Denied in unattended Auto |
-| Safeguard bypasses | Explicit authorization for the particular bypass |
-| Opaque execution or ambiguity | Denied when effects/authorization cannot be established |
-
-The taxonomy lives in `lib/permission-taxonomy.ts`. Shell syntax is boundedly parsed; full program semantics remain model-assessed. These are permission-review policies, not guarantees that every shell effect will be detected. Every model allow must cite the current user message and any supporting user messages using valid IDs. Unknown categories, missing/currently invalid evidence, malformed output, abnormal completion, and provider failure fail closed. The host rejects allows in prohibited categories even if the model returns them. Auto does not add approval dialogs or change modes on denial. Repeated denials stop the run under the limits below.
-
-### What is sent
-
-For reviewed actions, the configured provider receives:
-- Tool name and Bash command or requested filesystem path.
-- Working directory, workspace boundary, and deterministic path-policy findings.
-- Bounded, provenance-labelled user messages from the active branch.
-- Eligible file/directory approval scopes from that same current request when review is still needed. Invalid or stale Bash grants are not forwarded as authorization.
-- Bounded shell parsing results and risk findings; no script or Git configuration contents.
-- For task creation and worker review, the proposed task/brief, selected model, and delegated path/Bash scope, explicitly marked as untrusted action data—not user authorization.
-
-Other than the proposed delegation brief described above, it does **not** receive assistant prose/reasoning, raw tool-output history, worker result summaries, compaction summaries, file contents, edit/write replacement text, environment-variable objects, or Pi authentication credentials. The reviewer has no tool access. User prose, paths, commands, and approval strings can themselves contain secrets: recognition/redaction is best-effort, not a secret-detection guarantee. Do not use Auto when those details must not be disclosed to the selected provider. Recognizably secret-bearing or oversized review payloads are denied locally, without contacting the provider. Piexis does not log review payloads; Pi's normal user-message/session storage still applies.
-
-### Provenance and context limits
-
-`lib/permission-intent.ts` observes Pi's `input` source and exactly matches delivered user text. It stores only a content digest, timestamp, and source in non-model session metadata, not another prompt copy. Only matched `interactive` (including normal CLI input) and `rpc` inputs count as user authorization. This is observational provenance inside a trusted extension runtime, not cryptographic proof of human identity or protection against malicious extensions.
-
-Raw active-branch user entries preserve constraints across resume and compaction. Abandoned branches and generated summaries cannot supply authorization. Unknown/extension-injected messages are excluded; if the current request has no verified provenance, reviewed actions are denied. Older sessions without provenance need a new direct, self-contained request. Expanded/transformed prompts that do not match the observed input are conservatively unverified; submit the request directly instead. Changes to historical user entries invalidate completeness rather than silently dropping constraints. Undelivered queued input pauses reviewed actions; authorization is rechecked after model review so a changed request, branch, or session cannot reuse an in-flight allow.
+**Alt+A** and `/agent` apply the selected profile's `model` and `effort` from `subagent_variant_overrides` to the main session too. Without a profile model override, switching uses the top-level `model` if configured; otherwise it keeps the current model. Missing effort overrides leave the current thinking level alone (subject to Pi's model-capability clamping). `subagent_model` and `small_model` remain delegation-only settings. Invalid configuration or an unavailable model leaves the current profile unchanged and shows a warning.
 
-The context budget is 16 verified messages, 6,000 characters per message, and 24,000 characters total. Omitted history, oversized messages, recognizable secret redaction, or unsupported non-text input marks the context incomplete. Reviewed actions then fail closed rather than allowing on a truncated authorization record; start a fresh session with the necessary constraints when history exceeds the budget. Direct local reads/edits remain available. Unit tests cover these contracts with mocked reviewers; they do not establish live-model classification accuracy.
+Replace the example model IDs with available, authenticated models. `model` initializes a new main session; explicit CLI model selections and resumed sessions win at startup. An explicit profile switch subsequently applies the configured settings. `subagent_model` defaults to the current main-session model. A per-variant `model` wins over all automatic routing. New scaffolds explicitly pin each variant to the default subagent model; remove the `model` field from a variant's override to let it follow automatic routing or later `subagent_model` changes. Otherwise, short lookups/summaries in `ask` and clearly mechanical typo/comment/label/symbol edits in `code` use `small_model` when configured. Ambiguous, longer, or complex tasks, including planning, debugging, and orchestration, keep the normal subagent model. This is a conservative text heuristic, not a classifier or a guarantee of task difficulty. Omit `small_model` to disable automatic small-task routing.
 
-## Bash analysis and permission management
+Set `delegate_exploration` to `true` to let every profile offload bounded, read-only codebase discovery to the small model. Call `subagent({ "agent": "ask", "purpose": "explore", "task": "Locate configuration loading and summarize the relevant files" })`. Exploration always uses `small_model` at low effort, even if `ask` has a per-variant model override. It is rejected unless the option and `small_model` are configured. Exploration children receive only `read`, `grep`, `find`, and `ls`; they cannot delegate further. The parent retains planning, judgment, edits, and final verification. This is opt-in because child-process overhead can cost more than a trivial direct read.
 
-`lib/bash-policy.ts` implements a bounded literal-shell lexer/parser (16,000 characters, 256 tokens, 32 commands). It recognizes quoted words, command chains, pipelines, simple redirections, assignments, working-directory changes, wrappers/interpreters, and advisory destructive/network/shared-system/safeguard-bypass findings. Literal filesystem targets of supported commands/redirections receive path checks. This is not exhaustive command-effect analysis: it does not execute substitutions, inspect script bodies, or resolve arbitrary wrappers. Unsupported expansions, compound syntax, heredocs, descriptor redirections, and exhausted budgets require review/approval, never a narrow reusable grant.
+Effort accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Variant effort overrides win; small tasks otherwise request `low`, and other tasks inherit the parent's thinking level. Pi clamps effort to the chosen model's capabilities. Results/progress show the selected model, **requested** effort, routing reason, output, and usage. Invalid configuration or unavailable child models fail explicitly rather than silently switching providers.
 
-Only standalone `pwd`, `pwd -L`, `pwd -P`, `true`, and `false` are automatic Bash fast paths outside Plan, and shell startup/function overrides disable that fast path. Chains, redirections, scripts, package commands, and Git commands are not automatically considered safe. Plan still blocks all Bash. A trusted shell/tool installation is assumed; this is not containment.
+Child agents run in separate Pi processes with ephemeral sessions and the same OS permissions. Their tool selection is a subset of the parent's active tools; `plan`/`ask` children select only `read`, `grep`, `find`, and `ls`, and disable native MCP access. With `delegate_exploration`, a non-exploration `plan` or `ask` child may also receive `subagent` to perform one nested exploration; exploration children never receive it. `plan`/`ask` parents may delegate only to those two profiles. Other children omit `AskQuestion` and return questions to the parent. Main profile instructions and child tool selection are **not sandboxing**. Normal configured extensions and explicitly supplied CLI extensions load in children, with the parent's project-trust decision. Runtime-only provider/tool registrations, CLI `--api-key` overrides, credentials supplied only to an embedded SDK session, and in-memory state in other extensions are not copied to child processes. Use Pi's stored or environment-based authentication for delegation. Other extensions remain responsible for their own restrictions; verify their subprocess behavior before using delegation in a restricted host.
 
-### Reusable grants
+Abort and shutdown terminate active children (including their process group on Unix). Windows termination is best-effort for descendants. Model-facing output is capped at 50,000 characters; tool details retain up to 1 MB. JSON/print mode supports subagents but has no profile picker or child terminal interaction. Avoid loading another extension that registers `subagent`, `/agent`, or `--agent` alongside this one.
 
-For this first bounded implementation, reusable Bash grants cover only **Git status queries** with a fixed option vocabulary: `--short`/`-s`, `--branch`/`-b`, `--porcelain[=v1|=v2]`, and `--untracked-files=no|normal|all`. Choose either the exact command or that narrow query family. Both are bound to the canonical working directory and a fingerprint of the resolved Git executable's metadata, relevant environment, Git configuration, and Piexis settings/permission configuration. A changed fingerprint requires fresh approval/review. A status query can update Git's optional index caches; it is not part of the automatic read-only builtin set.
+## AskQuestion
 
-Configuration is inspected locally with bounded reads and never sent to the classifier. Unknown Git configuration keys, includes, aliases, hooks/fsmonitor/pager settings, shell startup overrides, script wrappers named Git, and linked worktrees decline reusable grants. Only a small set of inert core/user/remote/branch Git configuration keys is supported. Reuse is currently unavailable on Windows. Ordinary one-time approval or Auto review remains available when reuse is declined. Scripts (`npm test`, `make`, Python, shell scripts, etc.) do **not** receive reusable narrow grants; arbitrary dependency changes cannot therefore silently reuse such a grant. Full script-dependency analysis is not implemented.
+Existing `{ questions: [{ question, options, multiSelect?, allowOther? }] }` calls remain supported. New optional fields:
 
-Use:
-- `/permissions` or `/permissions list` — inspect grants, IDs, mode, and denial count.
-- `/permissions revoke <id>` — revoke one grant.
-- `/permissions clear` — remove all grants.
+- Question `id`, `type` (`single`, `multi`, `text`), and `required` (defaults to true). Explicit text questions may omit `options`; legacy optionless questions require `allowOther: true`.
+- Option `id`, `label`, and optional `description`. Missing IDs become `question-1` / `option-1`, etc.; IDs must be unique within their scope. Labels need not be unique.
+- `defaultSelection`: option ID or array of IDs. `minSelections` / `maxSelections` apply to multi-select answers. Required questions always need an answer.
+- `maxLength`: maximum text length in Unicode code points. Text is not trimmed; whitespace-only required answers are rejected. Text input is single-line, using Pi's native Input component.
 
-Revocation/clearing requires an idle agent. These commands never widen permissions or change modes. Grant IDs are session-local; there are no persisted allow rules.
+Use ↑↓ to navigate, Space to toggle multiple choices, Enter to confirm, and Esc/Ctrl+C to cancel the interaction. For related questions, Tab/Shift+Tab revisits questions without losing drafts; all questions must be confirmed before the final review can be submitted. “Type something else” is available only with `allowOther`; its answer replaces, rather than mixes with, selected options. Selection-count limits do not apply to custom text.
 
-### Denial limits
+Results have `status`: `answered`, `cancelled`, `aborted`, `requires_interaction`, or `error`. Both model-facing JSON and tool `details` contain the same result. Legacy `answers` and `cancelled` fields remain; each confirmed answer retains `question` and label-based `answer`, with added question `id`, `optionIds`, and `custom`. Optional empty answers are `""` or `[]`, never cancellation. Cancellation returns only already-confirmed answers. `cancelled` remains true for every non-answered outcome; use `status` to distinguish them.
 
-Denials include a reason and suggest a genuinely narrower action, clarification, or explicit authorization—not changing tools to perform the same denied effect. By default, **3 identical denials or 6 total denials per user request** stop the run via Pi's abort API. Successful intervening calls do not erase the budget. Configure limits at launch with `--permission-repeat-limit 3` and `--permission-denial-limit 6` (integers 1–50); repository configuration cannot silently raise them.
+Pi owns stdin, raw mode, cursor state, and focus restoration. Agent abort and session shutdown dismiss the screen; input closure/errors also settle it. Concurrent AskQuestion calls are explicitly rejected with `status: "error"`, in addition to Pi's sequential execution. Other extensions must respect Pi's UI ownership; this extension does not coordinate unrelated prompts. Non-TUI/non-TTY runs return `requires_interaction` without reading input.
 
-Once stopped, subsequent tool calls remain blocked except `AskQuestion` (and the deliberately launch-only Bypass mode). A newly delivered provenance-verified user request resets the budget; extension-injected messages and automatic retries do not. Pending sibling approvals cannot grant or execute after the stop. Already executing processes are subject to Pi's normal cancellation, not OS isolation.
+## Removed features
 
-Without permission UI, approval-required actions are immediately denied. At the threshold Piexis emits a `permission_blocked` diagnostic on **stderr**, records a count-only session stop entry, and aborts the run without waiting for input or forcing the whole host process to exit. Pi JSON/RPC consumers must inspect the blocked/aborted outcome; this extension does not promise a nonzero JSON-mode exit status.
+PieXis no longer provides permission modes, tool approvals, classifier review, plan-to-execution handoffs, filtered search, or background worktree tasks. Their commands, shortcuts, flags, and configuration initialization have been removed. Tool execution follows Pi and any other installed extensions; PieXis does not provide sandboxing or access restrictions.
 
-## Background tasks
-
-`/task <work>` (or `background_task`) starts a worker from `HEAD` in a disposable **Git worktree**, with at most two running workers. The permission extension must be active. Worktrees isolate Git changes, **not host filesystem, process, credential, or network access**. Foreground uncommitted changes and the full conversation are not copied; a dirty foreground checkout produces a warning.
-
-### Delegation and approvals
-
-- Status, cancellation, and diff inspection are recognized operations, including in Plan. Creation, application, and cleanup are denied in Plan/Don't Ask. Unknown custom tools remain unknown.
-- Manual/Accept Edits require one-time approval for agent-requested task creation. A direct `/task <work>` command supplies explicit user authorization. Auto reviews creation against verified user intent; direct task commands receive their own in-memory user-request identifier.
-- The proposed brief is untrusted action data. Optional `brief` fields include goal, context, constraints, files, acceptance criteria (`acceptanceCriteria`), decisions, and verification. Task plus brief is limited to 20,000 characters and is never silently truncated. Keep secrets out of descriptions: briefs go to the worker, may go to the classifier, and are stored in local task metadata.
-- Optional `paths` narrows file-tool scope to relative files/directories (default `["."]`, maximum 32 entries). Traversal, external symlink targets, credentials/protected path-tool writes, uncertain recursive searches, and tools outside the worker capability set are denied. There are no recursive task-delegation tools.
-- Every worker tool call goes through the parent broker and shared evaluator. Workers inherit no foreground session grants. Auto additionally reviews worker mutations against both the original user intent and the delegated brief. Manual approvals are one-time; missing UI, unavailable/expired brokers, and classifier failures deny rather than escalate.
-- New user input, mode changes, grant revocation, branch navigation, session replacement, and shutdown invalidate outstanding task authorizations and cancel queued/running workers. Existing worktrees are retained. Worker denial limits inherit the parent's launch settings and stop that worker, not unrelated tasks.
-
-### Opt-in command execution
-
-Start Pi with `--background-bash` to expose worker Bash for tests/builds/debugging. This is **permission-controlled command execution**, not sandboxing. It uses the same parent approval/classifier pipeline. Bash requires whole-worktree scope; narrower `paths` cannot be combined with this flag. Known literal external/protected targets are rejected, but parsing/model review cannot constrain arbitrary script effects or descendants. Cancellation revokes future approvals and terminates the worker process; it does not promise that all spawned descendants have stopped.
-
-Workers load only their explicit guard extension and worker-only tool wrappers, with built-ins disabled, so a missing guard cannot fall back to unguarded tools. Project trust-gated resources and automatic context-file discovery are disabled; needed repository instructions can be read through the broker. Task text is passed as literal prompt data, not CLI options or `@file` arguments. Pi's trusted user-level runtime and authentication are still used.
-
-### Inspect, apply, and clean
-
-Use `/task status`, `/task review <id>`, `/task diff <id>`, `/task cancel <id>`, `/task apply <id>`, `/task clean <id>`, and `/task interrupted` (or their corresponding tools where available).
-
-`task_diff` snapshots actual tracked/untracked/deleted files using a **temporary index and object store**; it does not stage into the real index or write repository objects. Checkout and inspection use raw bytes rather than executing Git hooks or clean/smudge filters; this skips LFS hydration and normal checkout conversions. Submodules/special files and exhausted inspection budgets fail closed: 10,000 files, 4 MiB per file, 128 MiB total file bytes, and 8 MiB Git output. Active workers must stop before inspection. Diff display is bounded to 50,000 characters, and sensitive/configuration/symlink patch bodies are withheld rather than leaked through the inspection tool.
-
-Apply always requires a user dialog showing the **actual changed paths**, sensitive/configuration warnings, and observed command results—even in Auto/Bypass. The patch digest and destination findings are checked again after confirmation, followed by Git apply validation. Worker prose cannot establish successful verification: observations come from post-execution tool records, not claimed test results or blocked tool-start events. Successful command completion is not proof of test coverage; verify again in the parent workspace after application. Repeatedly declined or headless agent-requested apply/cleanup actions use the foreground denial budget.
-
-Cleanup confirms deletion and validates the Piexis ownership marker, temporary directory, Git worktree, and repository before removal. Completed unapplied changes are retained rather than discarded. Headless apply/cleanup is denied. Trusted Pi/Git executables are assumed. These checks are not protection against arbitrary host code or filesystem races.
-
-Metadata lives at `<agent-dir>/piexis/tasks/<project-hash>.json`, not in the repository. Legacy `.pi/piexis-tasks.json` is imported if user-level state is absent; the source is retained. Interrupted worktrees can be reviewed/cleaned, but authorization, process handles, broker tokens, and user-intent snapshots are never restored from metadata. Fast tests use Git fixtures, mocked worker processes, and mocked reviewers. A separate [runtime suite](tests/runtime/README.md) checks actual Pi RPC/JSON flows, worker processes, and TUI permissions through a pseudo-terminal on Linux, using a deterministic local provider. Live-model accuracy, other platforms, and full visual/terminal compatibility remain unvalidated.
+Existing `piexis` settings, legacy configuration files, session records, and retained task worktrees are not deleted automatically. Old classifier, execution-model, and background-model settings are no longer read. Remove obsolete configuration manually if desired, preserving unrelated settings and any work you need. Remove explicit references to deleted extensions from your Pi resource settings or launch arguments.
 
 ## Select package resources
 
-Piexis uses Pi's native package resource filtering; it does not add its own plugin manager. Run `pi config` (or `pi config --local` for a trusted project) to enable or disable discovered resources. In settings, the package object can narrow resources declared by this package:
+Use Pi's native resource filtering with `pi config` (or `pi config --local` for a trusted project), or narrow resources in settings:
 
 ```json
 {
   "packages": [
     {
       "source": "npm:@preapexis/piexis",
-      "extensions": ["extensions/mode.ts", "extensions/ask-question.ts"],
+      "extensions": ["extensions/ask-question.ts"],
       "skills": ["skills/code-review", "skills/diagnosing-bugs", "skills/safe-refactor"],
       "themes": []
     }
@@ -183,25 +127,14 @@ Piexis uses Pi's native package resource filtering; it does not add its own plug
 }
 ```
 
-Omit a resource type to load all resources of that type; use `[]` to load none; and use Pi glob exclusions such as `"!skills/docx/**"` to omit document workflows. This lets users keep permission controls while disabling the custom UI/theme, or retain coding skills while excluding DOCX/PDF/PPTX/XLSX skills. See Pi's package configuration documentation for the complete filtering syntax.
+Omit a resource type to load all declared resources of that type; use `[]` to load none. Glob exclusions such as `"!skills/docx/**"` can omit document workflows.
 
 ## Development
 
 ```sh
+npm ci --ignore-scripts
 npm run check
 npm test
-npm run test:runtime
-npm run eval:permissions -- --validate
 ```
 
-### Local runtime checks
-
-`npm run test:runtime` launches the resolved peer dependency's packaged Pi CLI with all manifest extensions, disposable repositories and agent directories, and a deterministic loopback provider. It uses no real credentials or paid model calls. Tests cover permission dialogs, six-mode behavior, reviewer failures/timeouts, worker Bash opt-in, patch confirmation, stale approvals, cancellation, and shutdown. The Linux PTY check exercises the bundled UI and mode shortcuts; it requires `script` and `stty` and is explicitly skipped elsewhere. See [runtime validation results and limits](tests/runtime/README.md).
-
-### Classifier evaluation
-
-[`eval/permission-cases.json`](eval/permission-cases.json) contains 26 synthetic, labeled cases covering all policy categories, paired authorization changes, injection attempts, and worker scope. The offline runner validates the corpus, exports unlabeled requests using the production reviewer prompt, and scores externally collected model responses. It never executes fixture commands or automatically contacts a provider.
-
-See [`eval/README.md`](eval/README.md) for the opt-in live-evaluation procedure, response format, coverage map, and remaining manual release checks. Raw false allows, host policy overrides, false denials, invalid responses, and missing cases are reported separately. Scorer unit tests are not evidence of live model accuracy; no live-model result is claimed.
-
-There is currently no `tests/mode-sandbox.test.mjs`; consequently `npm run test:sandbox` cannot establish sandbox coverage. Unit tests do not establish containment or protection of host paths/network.
+Tests cover retained extension/resource contracts, agent configuration/routing/profile state, child-process protocol/cancellation, AskQuestion validation/lifecycle, recommended-tool setup/settings preservation, and skill routing. On Unix with Python 3, automated PTY tests drive the real Pi TUI renderer and native selector, checking keyboard interactions, startup choices, cancellation, cursor/raw-mode restoration, and listener cleanup. They use UI adapters rather than a live agent session; unsupported hosts explicitly skip these tests. Tests do not establish OS containment or live-model behavior. The permission evaluation, sandbox, and background-task runtime suites have been removed with those features.