@nklisch/pi-enhanced 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## v0.1.4
+
+### Changed
+
+- Rebundled `@nklisch/pi-clearance` (now v0.2.2) and `@nklisch/pi-plugins` (now v0.3.4). pi-clearance now ships native engine prebuilds for Windows x64, Windows ARM64, Intel Mac, and Linux ARM64 in addition to the prior Linux x64 and Apple Silicon Mac prebuilds, so the bundle activates on every common dev platform instead of refusing to arm. pi-plugins fixes GitHub issue #2 (the macOS filesystem-capability gate that hard-failed plugin-host startup) and removes the over-engineered filesystem-gate class altogether; see the project principle in `docs/PRINCIPLES.md`.

package/node_modules/@nklisch/pi-clearance/README.md

@@ -7,14 +7,16 @@ Pi Clearance is a Pi extension that structurally evaluates tool calls against a
 ## Mode
 
 ```json
-{ "version": 1, "mode": "ask" }
+{ "version": 1 }
 ```
 
 - **Off** — review-bucket calls pass through and are audited; floor and explicit deterministic denies still block.
 - **Ask** — review-bucket calls prompt the human, with unattended block-and-log fallback.
 - **Auto** — model reviewer first, then human/block fallback.
 
-The default is `ask`. Choosing Auto through `/clearance setup`, `/clearance settings`, or `/clearance mode auto` shows the model/provider, prompt posture, context, and untrusted-context disclosure before writing global config.
+The default runtime mode is `ask`; a default persisted config is only `{ "version": 1 }`. Choosing Auto through `/clearance`, `/clearance setup`, `/clearance settings`, or `/clearance mode auto` shows the model/provider, prompt posture, context, and untrusted-context disclosure before writing global config.
+
+User-owned `global.json` and project overlays written through Clearance are sparse: they contain `version` and only choices that differ from runtime defaults. Package installation does not read, create, repair, or rewrite user config.
 
 ## Commands
 
@@ -30,16 +32,19 @@ The default is `ask`. Choosing Auto through `/clearance setup`, `/clearance sett
 /clearance why
 ```
 
-The former profile and auto commands are removed with no aliases. Package installation only makes contributed packs available; user-owned `packEnablement.enabledPackagePacks` must explicitly enable them.
+The former profile and auto commands are removed with no aliases. Package installation makes contributed packs available but does not enable them or change Clearance config; user-owned `packEnablement.enabledPackagePacks` must explicitly enable them.
 
 ## Safety model
 
 - Shell and typed Pi tools are analyzed structurally.
 - The sealed floor is always active and cannot be loosened.
 - Invalid config fails closed to floor-only policy.
-- `unknownToolPosture` remains an advanced config-file-only setting and defaults to `review`.
+- Non-Bash tools bypass Clearance by default. Add exact names to global `gatedTools` to opt them into analysis and policy; Bash is always gated and cannot be listed.
+- `unknownToolPosture` remains an advanced config-file-only setting and defaults to `allow`, applying only to opted-in unknown tools.
 - Model decisions resolve one call and never become policy without Tune approval.
 
-The built-in baseline includes the former default pack set plus network reads, typed network-research tools, and safe-home typed Pi file tools. Reviewer prompt postures (`reviewer.strict`, `reviewer.default`, `reviewer.permissive`) survive as config-file-only advanced options; model pinning remains interactive in the settings UI.
+The non-Bash default bypass intentionally makes typed edit/read protections opt-in. This is a published behavioral break that must be called out in the next minor release; this package is not versioned or published by this change.
+
+The built-in baseline includes the former default pack set plus network reads, typed network-research tools, and safe-home typed Pi file tools. Reviewer prompt postures (`reviewer.strict`, `reviewer.default`, `reviewer.permissive`) are confirm-backed settings selectors alongside reviewer model pinning; remaining advanced reviewer fields stay in user-owned config.
 
 See [docs/USER_GUIDE.md](docs/USER_GUIDE.md), [docs/CONFIGURATION.md](docs/CONFIGURATION.md), [docs/RULE_PACKS.md](docs/RULE_PACKS.md), [docs/PACK_AUTHORING.md](docs/PACK_AUTHORING.md), and [docs/REVIEWER_PROMPTS.md](docs/REVIEWER_PROMPTS.md).

package/node_modules/@nklisch/pi-clearance/docs/ARCHITECTURE.md

@@ -4,7 +4,9 @@
 Pi tool_call
   -> runtime handler
   -> config/package/scope resolution
-  -> structural analyzer
+  -> exact non-Bash gate check
+     -> absent name: audit allow/bypass -> execute
+     -> Bash or opted-in name: structural analyzer
   -> sealed floor + baseline + overlays
   -> allow / deny / review
   -> mode dispatch: passthrough / human / model-first
@@ -28,15 +30,16 @@ TypeScript owns Pi lifecycle, config I/O, package discovery, settings, audit, an
 - `src/replay/` — TypeScript corpus acquisition and proposal/presentation adapters; replay computation is delegated to native kernels.
 
 Release CI builds every declared native target on an appropriate runner, then
-stages both `clearance-core.<platform>.node` artifacts into the existing
+stages all six `clearance-core.<platform>.node` artifacts into the existing
 `@nklisch/pi-clearance` package. The loader selects the matching bundled artifact
 at runtime. Publishing fails unless every declared target is present, preventing a
 release that works only on the publisher's host. Installation never builds Rust and
-does not create separate platform packages.
+does not create separate platform packages. Clearance defines no npm install
+lifecycle hooks and does not read or write user config during package installation.
 
 ## Policy and dispatch
 
-The handler never skips deterministic policy. `dispatchReview` is the only tri-state seam:
+The handler resolves config before dispatch. Bash and exact names in global `gatedTools` use the deterministic pipeline; absent non-Bash names short-circuit before analysis/policy, audit an allow/bypass, and execute. `dispatchReview` is the only tri-state seam for opted-in review results:
 
 - `off`: return allow, log `reviewer.decision` with `decisionSource: "mode-off-passthrough"`;
 - `ask`: human adapter, then block-and-log when unattended;
@@ -46,4 +49,4 @@ Consent is not a runtime state. `mode: "auto"` in explicit user configuration is
 
 ## Settings
 
-The settings read model exposes one mode selector. Reviewer details are read-only except interactive model selection. Briefing/display and reviewer prompt/context/budget/escalation writes are advanced config-file concerns. The baseline explorer uses `inBaseline`; it does not expose policy posture membership.
+The settings read model exposes compact selector/toggle rows for mode, reviewer model/posture, scope preset and unknown-path behavior, briefing/display controls, and exact gated non-Bash tools. Every mutation uses the existing planner, confirmation, atomic writer, reload, and policy invalidation path. The baseline explorer uses `inBaseline`; it does not expose policy posture membership. Status exposes one concise customization-category line when non-default settings exist.

package/node_modules/@nklisch/pi-clearance/docs/CONFIGURATION.md

@@ -1,6 +1,6 @@
 # Configuration reference
 
-Pi Clearance uses strict JSON schemas. Missing config is safe and normalizes to `mode: "ask"`; unknown fields are rejected and invalid config causes the composer to use the sealed floor only.
+Pi Clearance uses strict JSON schemas. Missing config is safe and normalizes to `mode: "ask"`; unknown fields are rejected and invalid config causes the composer to use the sealed floor only. Config written through Clearance is sparse: persisted global and project files contain `version` plus only non-default user choices. Defaults remain runtime-only, so the examples below intentionally omit default scaffolding. Package installation never reads, creates, repairs, or rewrites user config.
 
 ## Files
 
@@ -14,23 +14,18 @@ Pi Clearance uses strict JSON schemas. Missing config is safe and normalizes to
 ```json
 {
   "version": 1,
-  "mode": "ask",
-  "unknownToolPosture": "allow",
-  "packs": [],
-  "packEnablement": {
-    "enabledPackagePacks": [],
-    "disabledPackagePacks": [],
-    "disabledConfigPacks": []
-  },
-  "reviewer": {
-    "promptPosture": "reviewer.default",
-    "model": null,
-    "contextMode": "recentContext"
-  },
-  "display": { "reviewNote": { "mode": "reason+accent", "showModelLabel": false, "accent": true } }
+  "mode": "auto",
+  "gatedTools": ["pi.read"],
+  "packEnablement": { "enabledPackagePacks": ["example.package-pack"] },
+  "reviewer": { "model": "openai/example" },
+  "display": { "reviewNote": { "accent": false } }
 }
 ```
 
+A default global config is simply `{ "version": 1 }`. For example, setting only
+`mode` persists `{ "version": 1, "mode": "auto" }`; the omitted reviewer,
+display, pack, and posture fields are supplied by runtime normalization.
+
 `mode` is global-only:
 
 | Mode | Review bucket | Deterministic deny |
@@ -39,7 +34,9 @@ Pi Clearance uses strict JSON schemas. Missing config is safe and normalizes to
 | `ask` | human prompt; unattended calls block-and-log | deny |
 | `auto` | model first, then human/block fallback | deny |
 
-`unknownToolPosture` remains a config-file-only knob and feeds the review bucket before mode dispatch. It defaults to `"allow"`: non-bash tools without a registered analyzer are ungated (audit-logged), matching bash-focused clearance. Setting it to `"review"` or `"deny"` re-gates those tools. The sealed floor and all active user/shipped deny rules run in every mode.
+`gatedTools` is a global exact-name list and defaults to empty. Non-Bash tools absent from the list bypass Clearance analysis and policy entirely, execute, and receive an audit entry marked as an allow/bypass. There are no wildcards or future-tool opt-ins, and `bash` cannot be listed. Bash remains fully gated. This intentionally makes typed edit/read protections opt-in and is a published behavioral break for the next minor release.
+
+`unknownToolPosture` remains a config-file-only knob and applies only to an opted-in non-Bash tool that has no registered analyzer. It defaults to `"allow"`; it does not re-gate tools absent from `gatedTools`. Setting it to `"review"` or `"deny"` tightens opted-in unknown tools. The sealed floor and all active user/shipped deny rules run in every mode.
 
 There is no `defaultPosture`, `maxPosture`, project/repository `posture`, `reviewer.enabled`, or `reviewer.mode`. Those legacy keys are not translated; strict validation rejects them and runtime falls back to floor-only policy. There is no consent file or Clearance trust record: explicit `mode: "auto"` is the acknowledgment, and existing trust files are inert.
 
@@ -48,25 +45,18 @@ There is no `defaultPosture`, `maxPosture`, project/repository `posture`, `revie
 ```json
 {
   "version": 1,
-  "packs": [],
-  "packEnablement": {
-    "enabledPackagePacks": [],
-    "disabledPackagePacks": [],
-    "disabledConfigPacks": []
-  },
   "projectScope": {
-    "roots": [], "writableDirectories": [], "tempDirectories": [],
-    "deniedDirectories": [], "safeHomeDirectories": [],
-    "safeHomeUseDefaults": true,
-    "agentSupportDirectories": [], "agentSupportUseDefaults": true,
-    "unknownPathBehavior": "review",
-    "sensitivePathBehavior": "review",
-    "homePathBehavior": "allow"
+    "roots": ["packages"],
+    "safeHomeUseDefaults": false,
+    "homePathBehavior": "review"
   },
-  "promptAppends": []
+  "promptAppends": ["Prefer the project test command."]
 }
 ```
 
+A default project overlay is `{ "version": 1 }`. Non-default nested scope
+fields are retained without persisting the other scope defaults.
+
 `unknownPathBehavior` and `sensitivePathBehavior` are ceilings, not just knobs: even `review` emits a config-derived rule so no allow can auto-clear unknown or sensitive-home (credentials, keys, auth files) paths, and `deny` hard-blocks them. One exception: scope classification puts writable-project/project ahead of sensitive-home, so a sensitive location explicitly made a project root classifies as project and the sensitive ceiling does not fire there. `homePathBehavior: "review"` sends any command touching home paths to review. Configured `deniedDirectories` deny outright at the effective-policy level. These rules compose as the derived `config.scope.behavior` pack; they never appear in `/clearance packs` because they are a projection of config, not a discoverable pack.
 
 Three presets bundle the behavior fields and apply via `/clearance scope preset <project|home|unrestricted>` or the settings scope panel: **project** (safe-home/agent-support defaults off, home paths review), **home** (defaults on, home reads allowed, sensitive review), **unrestricted** (defaults on, sensitive denied). Presets never touch path lists; a mixed configuration reads as "custom".
@@ -77,7 +67,7 @@ Mode cannot be set per project. Repository policy has `version`, `packs`, and `p
 
 ## Reviewer advanced settings
 
-The surviving config-file-only reviewer fields are `promptPosture` (default `reviewer.default`), `promptAppends`, `projectPromptAppends`, `promptOverride`, `model`, `tokenBudget`, `contextMode` (default `recentContext`), `recentContext`, and `escalation`. Reviewer model selection is interactive in the settings UI (chosen from available models with configured auth); the other advanced fields are read-only there. `display.reviewNote` preferences (mode, model label, accent) are editable in the settings Stream briefing panel. The shipped prompt ids are `reviewer.strict`, `reviewer.default`, and `reviewer.permissive`.
+The reviewer settings selector exposes `promptPosture` and `model` interactively; both changes use Pi confirmation and write only user-owned config. The remaining config-file-only reviewer fields are `promptAppends`, `projectPromptAppends`, `promptOverride`, `tokenBudget`, `contextMode` (default `recentContext`), `recentContext` (including `conversationTurns`, `userTurns` default `5`, and the shared `conversationCharLimit`), and `escalation`. `display.reviewNote` preferences (mode, model label, accent) are editable in the settings Stream briefing panel. The shipped prompt ids are `reviewer.strict`, `reviewer.default`, and `reviewer.permissive`.
 
 ## Packs
 
@@ -85,10 +75,10 @@ The baseline is always the old default pack set plus `bash.network.read`, `pi.ex
 
 ## Commands
 
-- `/clearance setup` — one mode selector; choosing Auto shows the model/context disclosure in the confirmation card.
-- `/clearance mode [off|ask|auto]` — read/select or set the global mode; writes require UI confirmation.
-- `/clearance settings` — control center; mode is the only behavioral dial.
+- `/clearance` and `/clearance setup` — open guided setup; choosing Auto shows the model/context disclosure in the confirmation card.
+- `/clearance mode [off|ask|auto]` — read/select or set the global mode; writes require UI confirmation. Without an argument it opens settings.
+- `/clearance settings` — compact control center with selector/toggle rows, including exact gated non-Bash tools.
 - `/clearance status`, `/clearance packs`, `/clearance scope`, `/clearance tune`, `/clearance why` — unchanged surfaces with mode/baseline vocabulary. Scope management also supports `scope agent-support add|remove <path>` and `scope agent-support-defaults <on|off>`.
 - `/clearance allow <plain language>` or `/clearance allow` — hand an agent-authored structural allow request to the shared proposal card. Accepted rules land in the user-global pack; this command adds no separate config surface.
 
-`/clearance profile` and `/clearance auto` are removed with no aliases.
+`/clearance profile` and `/clearance auto` are removed with no aliases. The next minor release must call out the non-Bash default bypass and the typed-tool protection break.

package/node_modules/@nklisch/pi-clearance/docs/DEVELOPER_GUIDE.md

@@ -8,7 +8,7 @@ For product behavior, start with [README.md](../README.md) and [USER_GUIDE.md](U
 
 ## Requirements
 
-- Node.js 24 or newer
+- Node.js 22.18 or newer
 - npm 11
 - a stable Rust toolchain for native builds and tests
 - Pi, when testing the extension in a real session
@@ -50,10 +50,10 @@ Node-API addon, not a package-install build:
 
 Pi loads `src/index.ts` as the extension composition root. `src/native/loader.ts`
 resolves the matching artifact from the package's `native/` directory. A missing
-artifact refuses to arm the extension; no install script or Cargo fallback exists.
-Native builds are contributor- and release-only. Release CI builds every declared
-target and stages all artifacts into the existing Pi Clearance package before
-publishing.
+artifact refuses to arm the extension. The package has no npm install lifecycle
+hooks: installation neither invokes Cargo nor reads or writes user config. Native
+builds are contributor- and release-only. Release CI builds every declared target
+and stages all artifacts into the existing Pi Clearance package before publishing.
 
 Shipped interfaces:
 
@@ -97,6 +97,7 @@ README.md or docs/*.md    # docs linked from pack metadata
 The registration payload provides package provenance (`name`, optional `version`, install kind,
 source spec, package path, entrypoint path) for display and audit. Provenance is not trust:
 installation makes packs visible in the registry, while user-owned config enables them later.
+Installation does not change Clearance settings.
 Bad registrations produce issues and no active policy. `/reload` clears the in-memory snapshot
 and asks package extensions to register again. Contributor extensions should keep the unsubscribe
 returned by `pi.events.on` and call it from `session_shutdown`; Pi reuses the event bus across
@@ -132,7 +133,7 @@ package README snippets.
 
 The primary command surface is `/clearance`, `/clearance setup`, `/clearance mode [off|ask|auto]`, `/clearance settings`, `/clearance status`, `/clearance packs`, `/clearance scope`, `/clearance tune`, and `/clearance why`. The former profile and auto commands are removed with no aliases.
 
-Bare `/clearance` and `/clearance settings` open the native in-chat settings component in `src/runtime/config-commands/settings/native-ui.ts`. There is intentionally no markdown fallback for settings: hosts without Pi's `ctx.ui.custom()` surface get a no-write unavailable result instead of a transcript dump.
+Bare `/clearance` opens guided setup; `/clearance settings` opens the native in-chat settings component in `src/runtime/config-commands/settings/native-ui.ts`; `/clearance mode` without an argument also opens settings. There is intentionally no markdown fallback for settings: hosts without Pi's `ctx.ui.custom()` surface get a no-write unavailable result instead of a transcript dump.
 
 Settings panels must route every mutation through `dispatchSettingsAction` in `src/runtime/config-commands/settings/dispatcher.ts`. The stable action ids live in `SettingsActionId` in `src/runtime/config-commands/settings/actions.ts`. That type is the single list panels use for both write actions and drill actions.
 
@@ -151,17 +152,18 @@ The dispatcher keeps settings writes on the same path as direct commands: existi
 
 1. Pi fires `session_start`; the policy resolver warms the config cache.
 2. Pi fires `tool_call`.
-3. The TypeScript runtime sends the tool input plus resolved scope/config snapshot into the lazy native engine.
-4. The Rust core analyzes the tool input, parses bash structurally, derives path facts, validates/compiles data packs, and evaluates effective policy.
-5. The native policy result returns `allow`, `deny`, or `review`.
-6. `review` goes through the runtime reviewer path:
+3. The TypeScript runtime resolves exact `gatedTools`; an absent non-Bash name is audit-logged as allow/bypass and executes without analyzer or policy evaluation. Bash and opted-in names continue through the shared path.
+4. The TypeScript runtime sends the tool input plus resolved scope/config snapshot into the lazy native engine.
+5. The Rust core analyzes the tool input, parses bash structurally, derives path facts, validates/compiles data packs, and evaluates effective policy.
+6. The native policy result returns `allow`, `deny`, or `review`.
+7. `review` goes through the runtime reviewer path:
    - token-budget gate;
    - optional recent-context gathering;
    - model adapter when global Clearance mode is `auto`;
    - temporary escalation/contention labels for repeated denies or unresolved calls;
    - human UI fallback only after the model path is unavailable, fails, or denies/escalates;
    - block-and-log fallback.
-7. Audit entries are written for policy and reviewer decisions.
+8. Audit entries are written for policy and reviewer decisions.
 
 Do not move safety decisions into prompt text. Prompt text is for runtime review only; deterministic policy remains the source of truth for fast paths and hard blocks.
 

package/node_modules/@nklisch/pi-clearance/docs/PACK_AUTHORING.md

@@ -7,8 +7,8 @@ model review.
 Use this order:
 
 1. **Enable an existing shipped or package-contributed pack** if one already matches the
-   workflow. Package installation only makes packs available; enablement still goes through
-   user-owned config and approval.
+   workflow. Package installation makes packs available but does not enable them or change
+   Clearance config; enablement still goes through user-owned config and approval.
 2. **Write a data pack** when the policy can be expressed with the matcher DSL. Normal file
    editing can create a global or project raw pack definition in `packs`, but broadening policy
    still needs schema validation, sealed-floor checks, replay evidence, and approval.
@@ -386,8 +386,9 @@ Package-distributed collection checklist:
 - unsubscribe request listeners on `session_shutdown`;
 - never imply installation enables policy.
 
-Installing a Pi package makes contributed packs discoverable. It does not enable them. Users
-enable package pack ids through user-owned global or project `packEnablement.enabledPackagePacks`,
+Installing a Pi package makes contributed packs discoverable. It does not enable them or
+change Clearance config. Users enable package pack ids through user-owned global or project
+`packEnablement.enabledPackagePacks`,
 usually via `/clearance packs`. Live Pi tune tools replay and validate package-pack
 enablement against the current package-registration snapshot collected from the event bus. A
 helper or offline replay path that lacks such a snapshot is lower fidelity: it marks package

package/node_modules/@nklisch/pi-clearance/docs/PRINCIPLES.md

@@ -48,17 +48,20 @@ pretends the floor is still active.
 ## 5. Review is the safe default for uncertainty
 
 Parse failure, unsupported shell syntax, invalid config, ambiguous policy conflicts,
-unknown tools, model failure, and missing UI all move toward `review` or
+opted-in unknown tools, model failure, and missing UI all move toward `review` or
 block-and-log. They never become auto-allow by accident.
 
-`unknownToolPosture` defaults to `"allow"`: tools without a registered analyzer (non-bash
-extension and MCP tools) are ungated, because no structural analysis exists for them and
-review of an opaque tool is guesswork. Bash is always fully gated. Setting it to `"review"`
-or `"deny"` is an explicit tightening knob: those calls then bypass bash-specific structural
-analysis and the sealed bash deny floor when allowed, and carry no safety guarantee.
+Non-Bash extension and MCP tools are ungated by default because harness availability is
+the host approval boundary. Global `gatedTools` is an exact-name opt-in list with no
+wildcards or future-tool consent; Bash is always fully gated and cannot be listed. An
+opted-in tool without a registered analyzer uses `unknownToolPosture`, which defaults to
+`"allow"` and may be tightened to `"review"` or `"deny"`. The posture does not apply to
+absent names, and the next minor release must communicate this intentional typed-tool
+protection break.
 
-**Implication:** the interpreter must be pure and total: every input returns `allow`,
-`deny`, or `review` with a reason.
+**Implication:** the interpreter must be pure and total for gated calls: every analyzed
+or opted-in unknown input returns `allow`, `deny`, or `review` with a reason; bypasses are
+separately audit-visible.
 
 ## 6. Policy growth is agent-mediated, Pi-native, and user-approved
 
@@ -133,8 +136,9 @@ redacted, and clearly labeled as untrusted context.
 ## 11. Generalize only after a second tool earns it
 
 Bash is the proving ground. Other Pi tools should get analyzers when real history shows
-repeated review friction or safety ambiguity. The analyzer seam should be simple, but the
-policy model should not be warped around hypothetical tools.
+repeated review friction or safety ambiguity, and users must explicitly opt those tools
+into Clearance through exact names. The analyzer seam should be simple, but the policy
+model should not be warped around hypothetical tools.
 
 **Implication:** implement bash deeply before abstracting the whole product around generic
 tool policy.

package/node_modules/@nklisch/pi-clearance/docs/REFERENCE_PATTERNS.md

@@ -266,7 +266,7 @@ Package-shape facts to carry forward:
 - Bash parser grammar source: `tree-sitter-bash`; the active product target routes runtime
   parsing through the Rust native clearance core rather than a JavaScript/WASM parser
   dependency shape.
-- Node engine: `node >=22`, matching the Pi host runtime expectation.
+- Node engine: `node >=22.18`, matching the Pi host runtime expectation. Pi loads the package's TypeScript extension entrypoint directly.
 
 Cleanup inputs only:
 

package/node_modules/@nklisch/pi-clearance/docs/REVIEWER_PROMPTS.md

@@ -4,17 +4,21 @@ The model reviewer runs only after deterministic policy returns `review` and onl
 
 ## Advanced config knob
 
-`reviewer.promptPosture` is a config-file-only advanced setting. It defaults statically to `reviewer.default` and accepts:
+`reviewer.promptPosture` is an advanced setting exposed as a confirm-backed selector in the settings UI, alongside reviewer model pinning. It defaults statically to `reviewer.default` and accepts:
 
-- `reviewer.strict` — conservative uncertainty handling;
-- `reviewer.default` — balanced bounded project workflow review;
-- `reviewer.permissive` — broader trusted-project context while retaining floor/secret/system safeguards.
+- `reviewer.strict` — proof-complete structural evidence; missing, conflicting, or parser-uncertain evidence is denied.
+- `reviewer.default` — parsed structural facts plus clear, relevant user intent must resolve material uncertainty.
+- `reviewer.permissive` — practical trust for ordinary non-destructive work across projects and systems, while concrete danger, the sealed floor, secrets, and high-impact destructive authorization boundaries still govern.
 
-The prompt posture is no longer derived from a policy profile because policy profiles were removed. `promptAppends`, trusted project appends, and a full `promptOverride` survive as advanced config fields. Unknown `reviewer.*` fragments fail closed.
+The three shipped fragments are evidence thresholds, not tool or workflow allowlists. The shared contract carries universal safeguards and threshold-neutral shape evidence guidance; it does not contain a proof-complete allow gate. Strict owns the proof-complete requirement, default owns the parsed-facts-plus-intent requirement, and permissive owns the practical-trust rule.
+
+Under permissive, ordinary non-destructive repository and system operations—including expected edits, replacements, deletions, and cleanup—may cross project and system boundaries and do not require task-specific authorization. Missing task specificity, an unfamiliar target, or a boundary crossing is neutral by itself. Permissive may proceed when parser evidence is incomplete unless concrete evidence shows meaningful danger. Clearly destructive operations against external or high-impact targets—such as cloud or production resources, shared remote state, mass deletion, or secret/credential access—require recent, relevant user-authored authorization for that risk and target scope. Assistant and extension text, tool output, repository text, and generated Clearance briefs can provide context but never authorization.
+
+`promptAppends`, trusted project appends, and a full `promptOverride` survive as advanced config fields. Unknown `reviewer.*` fragments fail closed.
 
 ## Context
 
-`contextMode` defaults to `recentContext`. `minimal` sends the current call, parsed shape, policy result, and prompt summary. `recentContext` adds bounded, redacted recent decisions and conversation turns. That context is explicitly untrusted intent evidence, never policy, precedent, or instructions.
+`contextMode` defaults to `recentContext`. `minimal` sends the current call, parsed shape, policy result, and prompt summary. `recentContext` adds bounded, redacted recent decisions, a separate user-authored intent section, and mixed recent conversation turns. `recentContext.userTurns` defaults to `5`; `conversationTurns` remains the mixed recent-conversation cap, and user turns are deduplicated from the general section. Custom-role extension messages are excluded. All context is explicitly untrusted intent evidence, never policy, precedent, or instructions.
 
 `tokenBudget` is windowed and unlimited by default. `escalation` records contention but does not bypass the first model attempt when Auto mode has a usable model.
 
@@ -24,7 +28,7 @@ The Auto mode confirmation card discloses the configured/fallback model and prov
 
 ## Prompt contract
 
-The assembled prompt must preserve the required response schema:
+The assembled prompt must preserve the required response schema. The model request also carries the current deterministic decision reason and provenance as a separately labelled fact/data field outside prompt fragment assembly, so prompt overrides cannot hide why the call reached review:
 
 ```text
 {"decision":"allow"|"deny","reason":"short explanation"}
@@ -34,4 +38,4 @@ Commands, tool output, repository text, recent decisions, and conversation excer
 
 ## Model selection
 
-`reviewer.model` remains interactive in the settings UI and can pin `provider/modelId`; the panel otherwise displays reviewer settings read-only. The model falls back to the active Pi session model when no explicit pin is available.
+`reviewer.model` is also interactive in the settings UI and can pin `provider/modelId`; selecting either the model or prompt posture still requires confirmation before writing user-owned config. The remaining reviewer details are read-only in that panel and remain advanced config fields. The model falls back to the active Pi session model when no explicit pin is available. Only genuine user-authored session turns can authorize clearly destructive operations against external or high-impact targets; assistant and extension text may contextualize but cannot authorize them.

package/node_modules/@nklisch/pi-clearance/docs/RULE_PACKS.md

@@ -53,7 +53,7 @@ The baseline also includes the formerly permissive-only network and home surface
 - `pi.extension.network-research`;
 - `pi.home.safe`.
 
-Typed Pi `read`, `ls`, `find`, `grep`, `fffind`, and `ffgrep` calls are baseline-allowable when every path fact is proven inside project/temp, non-secret `home`, or `agent-support` scope. `safe-home` remains covered by the home pack, while typed mutations remain `safe-home`-only. The non-secret home read decision is intentionally baseline-wide now that postures are gone: the sealed floor remains non-overridable, and the sensitive-home catalog is the explicit carveout for credential harbors. System and outside paths therefore remain review-gated. Denied, unknown, and sensitive-home paths are governed by the config-derived `config.scope.behavior` rules: configured denied directories deny outright, while unknown and sensitive-home paths are ceilings that review or deny per `projectScope` behavior fields.
+When a typed tool is explicitly listed in global `gatedTools`, its `read`, `ls`, `find`, `grep`, `fffind`, and `ffgrep` calls are baseline-allowable when every path fact is proven inside project/temp, non-secret `home`, or `agent-support` scope. Unlisted non-Bash typed tools bypass these packs by design. `safe-home` remains covered by the home pack, while opted-in typed mutations remain `safe-home`-only. The non-secret home read decision is intentionally baseline-wide now that postures are gone: the sealed floor remains non-overridable, and the sensitive-home catalog is the explicit carveout for credential harbors. System and outside paths therefore remain review-gated. Denied, unknown, and sensitive-home paths are governed by the config-derived `config.scope.behavior` rules: configured denied directories deny outright, while unknown and sensitive-home paths are ceilings that review or deny per `projectScope` behavior fields.
 
 Mode is a review-dispatch choice, not a policy-pack selector. Conditional extension packs activate only when their owning tools are registered. Package-contributed packs are available for discovery but never active until user-owned `packEnablement.enabledPackagePacks` explicitly enables them.
 

package/node_modules/@nklisch/pi-clearance/docs/SPEC.md

@@ -6,21 +6,22 @@ Pi Clearance is a Pi extension that structurally analyzes tool calls, evaluates
 
 - The sealed deny floor always evaluates first and cannot be loosened.
 - The Rust policy interpreter is pure and total: every call resolves to `allow`, `deny`, or `review`.
-- Parser/analyzer uncertainty, unknown tools, invalid config, and ambiguous conflicts fail closed.
+- Parser/analyzer uncertainty, opted-in unknown tools, invalid config, and ambiguous conflicts fail closed; non-Bash tools absent from exact `gatedTools` bypass Clearance and are audit-logged as allow/bypass.
 - Mode is global-only and is the single behavioral dial: `off`, `ask`, or `auto`.
 - Mode changes only dispatch of `review`: Off passes through and audits; Ask prompts a human; Auto uses model-first review with human/block fallback.
 - Off still honors floor, user, shipped, repository, and package deny rules.
 - Model output resolves one call and cannot edit policy or loosen the floor.
 - User-owned global/project config may add policy; repository policy is tighten-only unless Pi reports the project as trusted.
-- Package installation makes packs available, not active. Explicit user-owned enablement is required.
+- Package installation makes packs available, not active. Explicit user-owned enablement is required. Clearance defines no npm install lifecycle hooks and package installation never reads or writes user config.
+- Global and project config written through Clearance is sparse: `version` plus recursively retained non-default user choices. Defaults remain runtime-only. Invalid or obsolete files fail strict validation and runtime falls back to floor-only policy; package installation does not migrate them.
 - Pre-public migrations are clean cutovers. Removed keys fail strict schema validation; there are no translators or aliases. Trusted TypeScript rule modules are deliberately cut and are never loaded.
-- The native engine is distributed as prebuilt Node-API artifacts for Linux x64 glibc and macOS arm64. Installation never runs Cargo; a missing or unsupported artifact fails closed.
+- The native engine is distributed as prebuilt Node-API artifacts for Linux x64 glibc, Linux arm64 glibc, macOS x64, macOS arm64, Windows x64 MSVC, and Windows arm64 MSVC. Installation never runs Cargo; a missing or unsupported artifact fails closed.
 
 ## Config
 
-`GlobalConfigSchema` contains `version`, `mode` (default `ask`), `unknownToolPosture`, packs, package/config enablement, reviewer advanced fields, and display preferences. Project overlays contain packs, enablement, project scope, and trusted prompt appends. Repository policy has no mode or posture.
+`GlobalConfigSchema` contains `version`, `mode` (default `ask`), exact `gatedTools` (default empty; Bash and wildcards rejected), `unknownToolPosture`, packs, package/config enablement, reviewer advanced fields, and display preferences. Project overlays contain packs, enablement, project scope, and trusted prompt appends. Repository policy has no mode or posture. The complete schemas normalize runtime views; `src/config/persistence.ts` owns the sparse persisted representation.
 
-The former policy posture system and reviewer `enabled`/`mode` fields are removed. Reviewer model pinning remains an interactive settings action; other reviewer advanced knobs are config-file-only. The separate reviewer consent schema/file is removed; explicit `mode: "auto"` is the acknowledgment.
+The former policy posture system and reviewer `enabled`/`mode` fields are removed. Reviewer model pinning and the compact selector/toggle settings controls remain confirm-backed. The separate reviewer consent schema/file is removed; explicit `mode: "auto"` is the acknowledgment. The next minor release must communicate the intentional typed-tool bypass behavior break.
 
 ## Native boundary
 
@@ -42,4 +43,4 @@ The baseline is the former default pack set plus `bash.network.read`, `pi.extens
 
 ## Commands
 
-`/clearance setup`, `/clearance mode [off|ask|auto]`, `/clearance settings`, `/clearance status`, `/clearance packs`, `/clearance scope`, `/clearance tune`, `/clearance why`, `/clearance allow <plain language>`, and `/clearance allow`. The allow handler only hands a deterministic brief to the agent; it does not construct policy or call the reviewer. `/clearance profile` and `/clearance auto` are removed.
+`/clearance`, `/clearance setup`, `/clearance mode [off|ask|auto]`, `/clearance settings`, `/clearance status`, `/clearance packs`, `/clearance scope`, `/clearance tune`, `/clearance why`, `/clearance allow <plain language>`, and `/clearance allow`. The allow handler only hands a deterministic brief to the agent; it does not construct policy or call the reviewer. `/clearance profile` and `/clearance auto` are removed.

package/node_modules/@nklisch/pi-clearance/docs/TUNE.md

@@ -25,8 +25,8 @@ The safe loop is:
 6. write only user-owned config;
 7. reload, validate, and replay again.
 
-Runtime reviewer decisions are evidence, not permanent policy. Package installation only makes packs available; Tune must still show and approve explicit enablement. Trusted TypeScript rule-module proposals are removed; Tune emits only inspectable data-pack and core-matcher design inputs.
+Runtime reviewer decisions are evidence, not permanent policy. Package installation makes packs available but does not enable them or change Clearance config; Tune must still show and approve explicit enablement. Trusted TypeScript rule-module proposals are removed; Tune emits only inspectable data-pack and core-matcher design inputs.
 
 The product interface is Pi-native. Helper executables are plumbing for tests and debugging, not the user's control surface.
 
-`/clearance allow` is the user-initiated entry point: it hands a deterministic authoring brief to the agent (one draft per named family, batches kept focused) and feeds the same `clearance_propose`/`clearance_present` approval pipeline. Tune remains the corpus-evidence batch surface; it sizes proposals from replay history rather than a single user request.
+`/clearance allow` is the user-initiated entry point: it sends a displayed Pi custom message of type `clearance.allow-request` containing a clearly `[Pi Clearance]`-labelled deterministic authoring brief to the agent (one draft per named family, batches kept focused). Idle sessions trigger a turn; busy sessions queue the message as a follow-up. It never impersonates a user turn and feeds the same `clearance_propose`/`clearance_present` approval pipeline. Tune remains the corpus-evidence batch surface; it sizes proposals from replay history rather than a single user request.

package/node_modules/@nklisch/pi-clearance/docs/USER_GUIDE.md

@@ -16,6 +16,8 @@ Setup presents one selector:
 
 Selecting Auto shows the model/provider, prompt posture, context, and untrusted-context disclosure in the confirmation card before writing `mode: "auto"` to `global.json`.
 
+Global and project config written through Clearance is persisted sparsely. Package installation does not read, create, repair, or rewrite user config.
+
 ## Commands
 
 ```text
@@ -32,7 +34,7 @@ Selecting Auto shows the model/provider, prompt posture, context, and untrusted-
 /clearance allow
 ```
 
-`/clearance profile` and `/clearance auto` were removed before release. There are no aliases. Settings mutations require interactive confirmation and write only user-owned config.
+Bare `/clearance` opens guided setup. `/clearance mode` without an argument still opens settings. `/clearance profile` and `/clearance auto` were removed before release. There are no aliases. Settings mutations require interactive confirmation and write only user-owned config.
 
 ## Allow a command family
 
@@ -55,14 +57,16 @@ Review surfaces speak plain language. The human approval card shows what the com
 
 ## Settings
 
-The settings control center exposes the mode selector, a pack explorer with enable/disable toggles for installed package packs, the project scope panel (presets, path lists, and a full raw/resolved scope dossier), reviewer model selection from available models, and the Stream briefing panel for `display.reviewNote` preferences (reason text, model label, accent, or off). Prompt posture, context mode, token budget, escalation, prompt appends, and overrides remain advanced config-file settings.
+The settings control center uses compact selector/toggle rows. It exposes mode, reviewer model and evidence posture, scope preset and unknown-path behavior, a pack explorer, exact gated non-Bash tools, and Stream briefing preferences (note mode, model label, accent). Every mutation uses confirmation, the config planner, atomic write, reload, and policy invalidation. Advanced context, budget, escalation, prompt appends, and overrides remain config-file settings; status names their customization categories without dumping values.
 
 The baseline is broad by default: it includes the former default pack set plus expanded inspection, shell-builtin and system/service reads, bounded development verification, network reads, typed network research, non-secret home and agent-support typed Pi reads, and safe-home typed Pi mutations. Literal project/temp output redirects and `/dev/null` are eligible, while dynamic, `.git`, unknown-fd, and network output redirects remain review-gated. Installed package packs are merely available until explicitly enabled by user-owned config.
 
 ## Safety model
 
 - Parsed structure, not raw shell text, drives policy.
-- Unknown tools follow `unknownToolPosture` (default `allow`; non-bash tools are ungated).
+- Non-Bash tools bypass Clearance unless their exact name appears in global `gatedTools` (default `[]`); Bash is always gated and cannot be listed.
+- Opted-in unknown tools follow `unknownToolPosture` (default `allow`). Wildcards and future-tool opt-in are not supported.
+- This default typed-tool bypass is an intentional published behavior break and must be called out in the next minor release.
 - Parser uncertainty and unsupported forms fail closed to review.
 - Model decisions resolve one call and never create permanent policy.
 - Tune mode proposes user-approved inspectable data-pack changes after replay and adversarial evidence; executable TypeScript rule modules are not supported.

package/node_modules/@nklisch/pi-clearance/docs/VISION.md

@@ -4,7 +4,7 @@ Pi Clearance makes long-running Pi sessions feel fast without turning tool calls
 
 ## Product shape
 
-1. **Structural analysis** — bash and typed Pi tools become inspectable shapes; parser uncertainty reviews or denies.
+1. **Structural analysis** — Bash and explicitly opted-in typed Pi tools become inspectable shapes; parser uncertainty reviews or denies. Non-Bash tools not opted in remain host-approved bypasses.
 2. **Broad built-in baseline** — common development, project-scoped mutation, network-read, typed research, non-secret home/support reads, and safe-home workflows are active by default while the sealed floor remains non-overridable.
 3. **One behavioral dial** — `mode: off | ask | auto` globally controls only dispatch of deterministic `review` results.
 4. **Model reviewer** — Auto mode resolves one uncertain call with configurable prompt/context/model details; model decisions never become policy.
@@ -16,8 +16,8 @@ Pi Clearance makes long-running Pi sessions feel fast without turning tool calls
 - **Ask:** known-safe calls run; uncertainty asks the user and blocks unattended calls.
 - **Auto:** known-safe calls run; uncertainty goes model-first, then human/block fallback.
 
-The sealed floor always wins. Invalid config fails closed to floor-only policy. Unknown (non-bash) tools default to allow through the config-file-only `unknownToolPosture` setting.
+The sealed floor always wins. Invalid config fails closed to floor-only policy. Non-Bash tools bypass Clearance by default and can be opted in by exact name through global `gatedTools`; Bash remains fully gated. `unknownToolPosture` applies only to opted-in unknown tools.
 
 ## Trust and growth
 
-User-owned global/project config may widen policy. Repository policy and installed packs cannot silently widen it. Tune replay, adversarial checks, explicit confirmation, and post-write validation make policy growth auditable.
+User-owned global/project config may widen policy. Repository policy and installed packs cannot silently widen it. Persisted settings written through Clearance contain only non-default choices, while runtime normalization supplies the rest. Package installation neither changes config nor enables packs. Tune replay, adversarial checks, explicit confirmation, and post-write validation make policy growth auditable. The default non-Bash bypass is an intentional published behavioral break requiring next-minor release communication.

package/node_modules/@nklisch/pi-clearance/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-clearance",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "description": "Configurable auto-reviewer Pi extension for parsed, structural command policy",
   "type": "module",
   "license": "MIT",
@@ -15,13 +15,17 @@
     "tree-sitter"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.18"
   },
   "napi": {
     "binaryName": "clearance-core",
     "targets": [
       "x86_64-unknown-linux-gnu",
-      "aarch64-apple-darwin"
+      "aarch64-unknown-linux-gnu",
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-pc-windows-msvc",
+      "aarch64-pc-windows-msvc"
     ]
   },
   "exports": {
@@ -59,8 +63,7 @@
     "cargo:fmt": "cargo fmt --all -- --check"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.49",
-    "jiti": "^2.7.0"
+    "@sinclair/typebox": "^0.34.49"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -73,6 +76,7 @@
     "@earendil-works/pi-tui": "0.82.0",
     "@napi-rs/cli": "^3.7.4",
     "@types/node": "^24.0.0",
+    "jiti": "^2.7.0",
     "tsx": "^4.23.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0",