@nklisch/pi-enhanced 0.1.0

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

@@ -0,0 +1,70 @@
+# User guide
+
+Pi Clearance evaluates tool calls deterministically, then dispatches only the `review` bucket according to one global mode.
+
+## First run
+
+```text
+/clearance setup
+```
+
+Setup presents one selector:
+
+- **Off** — nothing is asked or reviewed; catastrophic commands and your deny rules still block.
+- **Ask** — known-safe commands run automatically; everything else asks you. No model is called.
+- **Auto** — known-safe commands run automatically; a model reviews the rest before asking you.
+
+Selecting Auto shows the model/provider, prompt posture, context, and untrusted-context disclosure in the confirmation card before writing `mode: "auto"` to `global.json`.
+
+## Commands
+
+```text
+/clearance
+/clearance setup
+/clearance mode [off|ask|auto]
+/clearance settings
+/clearance status
+/clearance packs
+/clearance scope
+/clearance tune
+/clearance why
+/clearance allow <plain language>
+/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.
+
+## Allow a command family
+
+Use `/clearance allow <plain language>` to ask the agent to translate a request into a narrow structural rule. For example:
+
+```text
+/clearance allow pnpm test and any node test runner
+/clearance allow read project files with rg
+```
+
+The agent authors one or more focused proposal drafts and presents them through the same confirmation card as Tune. Nothing is written until you approve the card. `/clearance allow` with no text uses bounded scan-back to find the latest blocked or asked command and surfaces its structural summary, so the agent can author a family rule or narrow it with guards. If no recent command is available, the agent asks what you would like to allow. A sealed-floor command is refused and cannot be widened; use `/clearance why` to inspect the decision.
+
+In `off` mode, the command can still write an approved rule for a later mode change, but the agent prepends this note to the proposal summary: “Mode is `off`: nothing is asked or reviewed, so this rule changes nothing until the mode is `ask` or `auto`.”
+
+## Runtime behavior
+
+The sealed floor and deterministic deny rules always win. In Off mode, a review result is passed through with an audit entry whose `decisionSource` is `mode-off-passthrough`; Off does not disable explicit deny rules. Ask uses the human path and blocks unattended calls. Auto uses model review first, then human review and block-and-log fallback.
+
+Review surfaces speak plain language. The human approval card shows what the command does, where it acts, and why you are being asked — never raw JSON (the parsed shape and tool input stay behind `/clearance why`). A denied call surfaces exactly once, inline with the tool call, with a next action (`/clearance why`; `/clearance allow` for reviewer-sourced denies). An allowed call rides the inline review note, which you can quiet or hide in the Stream briefing settings.
+
+## 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 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).
+- 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.
+
+See [CONFIGURATION.md](CONFIGURATION.md), [RULE_PACKS.md](RULE_PACKS.md), [REVIEWER_PROMPTS.md](REVIEWER_PROMPTS.md), and [TUNE.md](TUNE.md).

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

@@ -0,0 +1,23 @@
+# VISION — Pi Clearance
+
+Pi Clearance makes long-running Pi sessions feel fast without turning tool calls into a blind trust channel. Structural analyzers and deterministic rule packs handle routine work; uncertainty gets one predictable review path.
+
+## Product shape
+
+1. **Structural analysis** — bash and typed Pi tools become inspectable shapes; parser uncertainty reviews or denies.
+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.
+5. **Pi-native Tune** — `/clearance tune` analyzes history and proposes user-approved policy or reviewer config changes.
+
+## Mode promise
+
+- **Off:** never asks; review-bucket calls pass through and are audited. Deterministic deny rules still block.
+- **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.
+
+## 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.

package/node_modules/@nklisch/pi-clearance/native/index.d.ts

@@ -0,0 +1,66 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare function adversarialValidate(proposal: string, baselineHandle: string, candidateHandle?: string | undefined | null, options?: string | undefined | null): string
+
+/** Analyze a Pi tool input through the native registry. */
+export declare function analyzeTool(toolName: string, input: string): string
+
+export declare function buildCorpusModel(corpus: string, handle: string, options?: string | undefined | null): string
+
+export declare function classifyMutationTrustBoundary(path: string | undefined | null, context: string): string
+
+export declare function classifyOverlap(left: string, right: string): string
+
+export declare function classifyPathFact(input: string, context: string): string
+
+export declare function classifyStageEffect(stage: string): string
+
+export declare function compileMatch(matcher: string): string
+
+/**
+ * Parse a bash command and return the generated contract as JSON. Keeping the
+ * binding JSON-shaped avoids exposing tree-sitter or napi-owned object types.
+ */
+export declare function compilePack(pack: string): string
+
+export declare function compilePackMetadata(metadata: string): string
+
+export declare function compilePolicy(policy: string): string
+
+export declare function composePolicy(request: string): string
+
+export declare function createPolicy(policy: string): string
+
+export declare function decide(handle: string, shape: string): string
+
+export declare function decideBatch(handle: string, shapes: string): string
+
+export declare function effectRegistry(): string
+
+export declare function enrichPathFacts(shape: string, context: string): string
+
+export declare function freePolicy(handle: string): boolean
+
+export declare function health(): HealthInfo
+
+export interface HealthInfo {
+  version: string
+  grammarVersion: string
+  target: string
+}
+
+export declare function match(matcher: string, shape: string): boolean
+
+export declare function parseBash(command: string): string
+
+export declare function reduceForLoopIterator(stage: string, effectiveCwd: string, context: string, home?: string | undefined | null): string
+
+export declare function reduceIteratorEntry(entry: string, effectiveCwd: string, context: string, home?: string | undefined | null): string
+
+export declare function replayDelta(corpus: string, baselineHandle: string, candidateHandle: string, options?: string | undefined | null): string
+
+export declare function stageFileInputIndices(stage: string): string
+
+export declare function validateCompoundAllowCanonicality(expr: string): string
+
+export declare function validatePackAgainstFloor(request: string): string

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

@@ -0,0 +1,95 @@
+{
+  "name": "@nklisch/pi-clearance",
+  "version": "0.1.0",
+  "description": "Configurable auto-reviewer Pi extension for parsed, structural command policy",
+  "type": "module",
+  "license": "MIT",
+  "author": "Nathan Klisch",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "policy",
+    "security",
+    "bash",
+    "tree-sitter"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "napi": {
+    "binaryName": "clearance-core",
+    "targets": [
+      "x86_64-unknown-linux-gnu",
+      "aarch64-apple-darwin"
+    ]
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./pack-registration": "./src/packs/package-contract.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./src/skill/clearance-tune/SKILL.md",
+      "./src/skill/clearance-pack-authoring/SKILL.md"
+    ]
+  },
+  "files": [
+    "src",
+    "native",
+    "README.md",
+    "docs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "contracts:generate": "tsx scripts/contracts.ts generate",
+    "contracts:check": "tsx scripts/contracts.ts check",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "build:native": "napi build --release --manifest-path crates/clearance-node/Cargo.toml --output-dir native --platform --no-js",
+    "build:native:target": "napi build --release --manifest-path crates/clearance-node/Cargo.toml --output-dir native --platform --no-js --target",
+    "bench:s0": "tsx scripts/bench/s0-baseline.ts",
+    "bench:s8": "tsx scripts/bench/s8-final.ts",
+    "cargo:test": "cargo test --workspace",
+    "cargo:clippy": "cargo clippy --workspace --all-targets --all-features -- -D warnings",
+    "cargo:fmt": "cargo fmt --all -- --check"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "jiti": "^2.7.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.82.0",
+    "@earendil-works/pi-coding-agent": "0.82.0",
+    "@earendil-works/pi-tui": "0.82.0",
+    "@napi-rs/cli": "^3.7.4",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.0",
+    "@biomejs/biome": "^2.5.1"
+  },
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nklisch/pi-extensions.git",
+    "directory": "packages/pi-clearance"
+  },
+  "bugs": {
+    "url": "https://github.com/nklisch/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/nklisch/pi-extensions/tree/main/packages/pi-clearance#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/node_modules/@nklisch/pi-clearance/src/audit/entry.ts

@@ -0,0 +1,206 @@
+import type { ToolShape } from "../parse/shape.ts";
+import type { Decision } from "../policy/core.ts";
+import type { StructuredRatchetProposal } from "../replay/proposal-schema.ts";
+
+export type AuditEntryType =
+  | "policy.decision"
+  | "reviewer.decision"
+  | "trust.event"
+  | "config.event"
+  | "replay.input"
+  | "ratchet.proposal-decision";
+
+export interface AuditBaseEntry {
+  readonly version: 1;
+  readonly timestamp: string;
+  readonly entryType: AuditEntryType;
+  readonly projectPath?: string;
+  readonly sessionId?: string;
+  readonly toolCallId?: string;
+}
+
+export interface PolicyDecisionEntry extends AuditBaseEntry {
+  readonly entryType: "policy.decision";
+  readonly toolName: string;
+  readonly toolInput: unknown;
+  readonly shape?: ToolShape;
+  readonly decision: Decision;
+}
+
+export type ReviewerMode = "model" | "human" | "block-and-log" | "mode-off";
+export type ReviewerContextMode = "minimal" | "recentContext";
+
+export interface ReviewerDecisionEntry extends AuditBaseEntry {
+  readonly entryType: "reviewer.decision";
+  readonly reviewerMode: ReviewerMode;
+  readonly toolName: string;
+  readonly toolInput: unknown;
+  readonly originalDecision: Decision;
+  readonly finalDecision: Decision;
+  // Additive optional labels populated by downstream reviewer-behavior features
+  // (context-curation, temporary-escalation, model-adapter-and-token-budget).
+  // Absent means the behavior did not fire or was not applicable. This feature
+  // owns the entry shape so downstream features do not collide on audit/entry.ts.
+  readonly escalated?: boolean;
+  readonly contextMode?: ReviewerContextMode;
+  readonly recentContextAttached?: boolean;
+  readonly budgetExhausted?: boolean;
+  /**
+   * Origin of the final reviewer-decision effect.
+   *
+   * `reviewerMode` records the path shape (model/human/block-and-log), while
+   * this label records why that path produced the final decision. In
+   * particular, it distinguishes explicit `mode: "block"` from the unattended
+   * fallback reached when no human UI can answer.
+   */
+  readonly decisionSource?:
+    | "model"
+    | "human"
+    | "unattended-fallback"
+    | "mode-off-passthrough";
+  readonly reviewerModel?: { readonly provider: string; readonly id: string };
+  readonly reviewerModelSource?: "configured" | "fallback";
+  readonly reviewerModelNote?: string;
+}
+
+export type TrustEventKind = "project-trusted" | "project-untrusted";
+
+export interface TrustEventEntry extends AuditBaseEntry {
+  readonly entryType: "trust.event";
+  readonly event: TrustEventKind;
+  readonly projectPath?: string;
+  readonly reason: string;
+}
+
+export type ConfigEventKind =
+  | "mode-selected"
+  | "config-loaded"
+  | "config-load-failed";
+
+export type ConfigMode = "off" | "ask" | "auto";
+
+export interface ConfigEventEntry extends AuditBaseEntry {
+  readonly entryType: "config.event";
+  readonly event: ConfigEventKind;
+  readonly mode?: ConfigMode;
+  readonly errors?: readonly string[];
+}
+
+export interface ReplayInputEntry extends AuditBaseEntry {
+  readonly entryType: "replay.input";
+  readonly corpusId?: string;
+  readonly commandCount: number;
+}
+
+export type RatchetProposalDecision =
+  | "accept"
+  | "accept-without-replay"
+  | "reject"
+  | "revise"
+  | "skip"
+  | "aborted";
+
+export type RatchetProposalPostWriteReplayStatus =
+  | "not-applicable"
+  | "passed"
+  | "regression"
+  | "not-run"
+  | "failed";
+
+export interface RatchetProposalDecisionEntry extends AuditBaseEntry {
+  readonly entryType: "ratchet.proposal-decision";
+  readonly batchId?: string;
+  readonly proposalId: string;
+  readonly proposalKind: StructuredRatchetProposal["kind"];
+  readonly applicationMode: StructuredRatchetProposal["applicationMode"];
+  readonly decision: RatchetProposalDecision;
+  readonly targetKind: StructuredRatchetProposal["target"]["kind"];
+  readonly targetPath?: string;
+  readonly write: {
+    readonly attempted: boolean;
+    readonly ok?: boolean;
+    readonly changed?: boolean;
+    readonly planId?: string;
+    readonly backupPath?: string;
+    readonly reason?: string;
+  };
+  readonly postWriteReplay?: {
+    readonly status: RatchetProposalPostWriteReplayStatus;
+    readonly changedCalls?: number;
+    readonly regressionCount?: number;
+  };
+}
+
+export type AuditEntry =
+  | PolicyDecisionEntry
+  | ReviewerDecisionEntry
+  | TrustEventEntry
+  | ConfigEventEntry
+  | ReplayInputEntry
+  | RatchetProposalDecisionEntry;
+
+export interface EntryFactoryOptions {
+  readonly clock?: () => Date;
+}
+
+type EntryFactoryInput<T extends AuditBaseEntry> = Omit<
+  T,
+  "version" | "timestamp"
+>;
+
+function timestamp(options: EntryFactoryOptions | undefined): string {
+  return (options?.clock ?? (() => new Date()))().toISOString();
+}
+
+function stampEntry<T extends EntryFactoryInput<AuditBaseEntry>>(
+  input: T,
+  options: EntryFactoryOptions | undefined,
+): T & Pick<AuditBaseEntry, "version" | "timestamp"> {
+  return {
+    ...input,
+    version: 1,
+    timestamp: timestamp(options),
+  };
+}
+
+export function createPolicyDecisionEntry(
+  input: EntryFactoryInput<PolicyDecisionEntry>,
+  options?: EntryFactoryOptions,
+): PolicyDecisionEntry {
+  return stampEntry(input, options);
+}
+
+export function createReviewerDecisionEntry(
+  input: EntryFactoryInput<ReviewerDecisionEntry>,
+  options?: EntryFactoryOptions,
+): ReviewerDecisionEntry {
+  return stampEntry(input, options);
+}
+
+export function createTrustEventEntry(
+  input: EntryFactoryInput<TrustEventEntry>,
+  options?: EntryFactoryOptions,
+): TrustEventEntry {
+  return stampEntry(input, options);
+}
+
+export function createConfigEventEntry(
+  input: EntryFactoryInput<ConfigEventEntry>,
+  options?: EntryFactoryOptions,
+): ConfigEventEntry {
+  return stampEntry(input, options);
+}
+
+export function createReplayInputEntry(
+  input: EntryFactoryInput<ReplayInputEntry>,
+  options?: EntryFactoryOptions,
+): ReplayInputEntry {
+  return stampEntry(input, options);
+}
+
+export function createRatchetProposalDecisionEntry(
+  input: EntryFactoryInput<RatchetProposalDecisionEntry>,
+  options?: EntryFactoryOptions,
+): RatchetProposalDecisionEntry {
+  return stampEntry(input, options);
+}

package/node_modules/@nklisch/pi-clearance/src/audit/log.ts

@@ -0,0 +1,4 @@
+export * from "./entry.ts";
+export * from "./logger.ts";
+export * from "./redact.ts";
+export * from "./sink.ts";

package/node_modules/@nklisch/pi-clearance/src/audit/logger.ts

@@ -0,0 +1,39 @@
+import type { AuditEntry } from "./entry.ts";
+import { redactEntry } from "./redact.ts";
+import type { AuditLogSink } from "./sink.ts";
+
+export interface AuditLogger {
+  /** Append the entry after redaction and return a promise that never rejects. */
+  log(entry: AuditEntry): Promise<void>;
+  /** Optional flush/close of the underlying sink. */
+  flush?(): Promise<void>;
+}
+
+export interface AuditLoggerOptions {
+  readonly sink: AuditLogSink;
+}
+
+export function createAuditLogger(options: AuditLoggerOptions): AuditLogger {
+  const { sink } = options;
+  const logger: AuditLogger = {
+    async log(entry: AuditEntry): Promise<void> {
+      try {
+        sink.appendSync(redactEntry(entry));
+      } catch {
+        // Audit logging is advisory; callers must not observe sink failures.
+      }
+    },
+  };
+
+  if (sink.close !== undefined) {
+    logger.flush = async (): Promise<void> => {
+      try {
+        await sink.close?.();
+      } catch {
+        // Flush/close is best-effort for the same reason append is.
+      }
+    };
+  }
+
+  return logger;
+}