@nklisch/pi-enhanced 0.1.2 → 0.1.4

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.0",
+  "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",

package/node_modules/@nklisch/pi-clearance/src/config/config-command-plans.ts

@@ -1,5 +1,7 @@
 import { createHash } from "node:crypto";
 
+import { DEFAULT_PROJECT_SCOPE_BEHAVIOR } from "./defaults.ts";
+import { isExactNonBashToolName } from "./gated-tools.ts";
 import type { JsonPatchOperation } from "../replay/proposal-schema.ts";
 import { isHighCostReviewerModel } from "../runtime/reviewer-model.ts";
 import type {
@@ -91,10 +93,12 @@ export function inferScopePreset(
     const fields = SCOPE_PRESET_FIELDS[preset];
     if (
       scope.safeHomeUseDefaults === fields.safeHomeUseDefaults &&
-      (scope.agentSupportUseDefaults ?? true) ===
+      (scope.agentSupportUseDefaults !== false) ===
         fields.agentSupportUseDefaults &&
-      (scope.homePathBehavior ?? "allow") === fields.homePathBehavior &&
-      (scope.sensitivePathBehavior ?? "review") ===
+      (scope.homePathBehavior ?? DEFAULT_PROJECT_SCOPE_BEHAVIOR.homePathBehavior) ===
+        fields.homePathBehavior &&
+      (scope.sensitivePathBehavior ??
+        DEFAULT_PROJECT_SCOPE_BEHAVIOR.sensitivePathBehavior) ===
         fields.sensitivePathBehavior &&
       scope.unknownPathBehavior === fields.unknownPathBehavior
     ) {
@@ -137,6 +141,10 @@ export type ReviewNoteDisplayCommandChange =
   | { readonly kind: "show-model-label"; readonly enabled: boolean }
   | { readonly kind: "accent"; readonly enabled: boolean };
 
+export type GatedToolCommandChange =
+  | { readonly kind: "add"; readonly toolName: string }
+  | { readonly kind: "remove"; readonly toolName: string };
+
 export type ReviewerCommandChange =
   | { readonly kind: "prompt-posture"; readonly promptPosture: string }
   | { readonly kind: "context-mode"; readonly contextMode: ReviewerContextMode }
@@ -181,6 +189,74 @@ export type PlanProjectScopeCommandChangeResult =
     }
   | { readonly ok: false; readonly reason: string };
 
+export function planGatedToolCommandChange(input: {
+  readonly change: GatedToolCommandChange;
+  readonly resolvedConfig: ResolvedConfig;
+}):
+  | { readonly ok: true; readonly plan: ConfigCommandPlan }
+  | { readonly ok: false; readonly reason: string } {
+  const toolName = input.change.toolName;
+  if (!isExactNonBashToolName(toolName)) {
+    return {
+      ok: false,
+      reason:
+        "gatedTools accepts exact non-Bash tool names only; wildcards, whitespace, and bash are not allowed",
+    };
+  }
+
+  const snapshots = input.resolvedConfig.sourceSnapshots;
+  if (snapshots === undefined) {
+    return {
+      ok: false,
+      reason:
+        "resolved config did not include source snapshots; reload config before planning a gated-tool write",
+    };
+  }
+
+  const before = cloneJsonish({
+    ...snapshots.global,
+    gatedTools: [...(snapshots.global.gatedTools ?? [])],
+  });
+  const after = cloneJsonish(before) as Mutable<GlobalConfig>;
+  const current = [...before.gatedTools];
+  const next =
+    input.change.kind === "add"
+      ? current.includes(toolName)
+        ? current
+        : [...current, toolName]
+      : current.filter((candidate) => candidate !== toolName);
+  after.gatedTools = next;
+  const patch = fieldPatch("/gatedTools", current, next);
+  const title =
+    input.change.kind === "add"
+      ? `Gate non-Bash tool ${toolName}`
+      : `Stop gating non-Bash tool ${toolName}`;
+  const planWithoutId = {
+    target: { kind: "global", path: snapshots.paths.globalConfigFile },
+    title,
+    summary:
+      patch.length === 0
+        ? `${title}; no config write is needed.`
+        : `${title}; only this exact tool name will use Clearance analysis and policy.`,
+    patch,
+    before,
+    after,
+    requiredAcknowledgementCodes: [],
+    warnings: [],
+  } satisfies Omit<ConfigCommandPlan, "id">;
+
+  return {
+    ok: true,
+    plan: {
+      id: deterministicPlanId({
+        gatedToolChange: input.change,
+        ...planWithoutId,
+      }),
+      ...planWithoutId,
+    },
+  };
+}
+
 export function planModeCommandChange(input: {
   readonly mode: ClearanceMode;
   readonly resolvedConfig: ResolvedConfig;

package/node_modules/@nklisch/pi-clearance/src/config/config-command-writer.ts

@@ -12,6 +12,10 @@ import type { TSchema } from "@sinclair/typebox";
 
 import type { JsonPatchOperation } from "../replay/proposal-schema.ts";
 import type { ResolvedConfig } from "./loader.ts";
+import {
+  type ConfigPersistenceKind,
+  serializeSparseConfigText,
+} from "./persistence.ts";
 import {
   type GlobalConfig,
   GlobalConfigSchema,
@@ -101,6 +105,7 @@ export type ConfigCommandApplyResult =
 interface AtomicConfigWriteInput {
   readonly planId: string;
   readonly targetPath: string;
+  readonly configKind: ConfigPersistenceKind;
   readonly value: GlobalConfig | ProjectOverlayConfig;
   readonly hadExistingFile: boolean;
   readonly reloadConfig: () => Promise<ResolvedConfig>;
@@ -184,6 +189,7 @@ export async function applyConfigCommandPlan(
   return await writeConfigTargetAndValidate({
     planId: plan.id,
     targetPath: plan.target.path,
+    configKind: plan.target.kind,
     value: patched.value,
     hadExistingFile: readResult.exists,
     reloadConfig: dependencies.reloadConfig,
@@ -207,7 +213,7 @@ export async function writeConfigTargetAndValidate(
     await mkdir(path.dirname(input.targetPath), { recursive: true });
     await writeFile(
       tempPath,
-      `${JSON.stringify(input.value, null, 2)}\n`,
+      serializeSparseConfigText(input.configKind, input.value),
       "utf8",
     );
     tempPresent = true;

package/node_modules/@nklisch/pi-clearance/src/config/defaults.ts

@@ -0,0 +1,42 @@
+/**
+ * User-visible defaults shared by schema normalization and status/read models.
+ * Keeping these values in one module prevents a new schema default from being
+ * mistaken for a customization by diagnostics.
+ */
+export const DEFAULT_REVIEWER_PROMPT_POSTURE = "reviewer.default" as const;
+export const DEFAULT_REVIEWER_CONTEXT_MODE = "recentContext" as const;
+
+export const DEFAULT_REVIEWER_TOKEN_BUDGET = {
+  window: "24h",
+  limit: null,
+} as const;
+
+export const DEFAULT_REVIEWER_RECENT_CONTEXT = {
+  decisionLimit: 25,
+  decisionWindow: "2h",
+  conversationTurns: 3,
+  userTurns: 5,
+  conversationCharLimit: 6000,
+} as const;
+
+export const DEFAULT_REVIEWER_ESCALATION = {
+  enabled: true,
+  denialLimit: 3,
+  window: "10m",
+} as const;
+
+export const DEFAULT_UNKNOWN_TOOL_POSTURE = "allow" as const;
+
+export const DEFAULT_PROJECT_SCOPE_BEHAVIOR = {
+  safeHomeUseDefaults: true,
+  agentSupportUseDefaults: true,
+  unknownPathBehavior: "review",
+  sensitivePathBehavior: "review",
+  homePathBehavior: "allow",
+} as const;
+
+export const DEFAULT_REVIEW_NOTE_DISPLAY = {
+  mode: "reason+accent",
+  showModelLabel: false,
+  accent: true,
+} as const;

package/node_modules/@nklisch/pi-clearance/src/config/gated-tools.ts

@@ -0,0 +1,7 @@
+/** Exact-name syntax for the global non-Bash Clearance opt-in list. */
+export const EXACT_NON_BASH_TOOL_NAME_PATTERN =
+  "^(?!bash$)[^\\s*?\\[\\]{}]+$" as const;
+
+export function isExactNonBashToolName(value: string): boolean {
+  return value.length > 0 && new RegExp(EXACT_NON_BASH_TOOL_NAME_PATTERN).test(value);
+}

package/node_modules/@nklisch/pi-clearance/src/config/loader.ts

@@ -3,6 +3,7 @@ import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import type { Static, TSchema } from "@sinclair/typebox";
 import type { DecisionEffect } from "../policy/core.ts";
+import { DEFAULT_UNKNOWN_TOOL_POSTURE } from "./defaults.ts";
 import {
   isHighCostReviewerModel,
   parseModelSpec,
@@ -69,6 +70,7 @@ export interface ResolvedReviewerConfig {
     readonly decisionLimit: number;
     readonly decisionWindow: string;
     readonly conversationTurns: number;
+    readonly userTurns?: number;
     readonly conversationCharLimit: number;
   };
   readonly escalation: {
@@ -133,6 +135,8 @@ export interface ResolvedConfig {
    */
   readonly sourceSnapshots?: ResolvedConfigSourceSnapshots;
   readonly mode: ClearanceMode;
+  /** Exact non-Bash tool names explicitly opted into Clearance gating. */
+  readonly gatedTools?: readonly string[];
   readonly unknownToolPosture: DecisionEffect;
   readonly projectScope: ResolvedProjectScope;
   readonly packEnablement: ResolvedPackEnablement;
@@ -250,7 +254,9 @@ export async function loadConfig(
       repository: repositoryPolicy,
     },
     mode,
-    unknownToolPosture: globalConfig.unknownToolPosture ?? "allow",
+    gatedTools: [...globalConfig.gatedTools],
+    unknownToolPosture:
+      globalConfig.unknownToolPosture ?? DEFAULT_UNKNOWN_TOOL_POSTURE,
     projectScope: projectScopeResolution.scope,
     packEnablement,
     globalPacks: withPackSource(globalConfig.packs, "user-global"),

package/node_modules/@nklisch/pi-clearance/src/config/pack-enablement-writer.ts

@@ -113,6 +113,7 @@ export async function applyPackEnablementPlan(
   return await writeConfigTargetAndValidate({
     planId: plan.id,
     targetPath: plan.targetPath,
+    configKind: plan.request.scope,
     value: patched.value,
     hadExistingFile: readResult.exists,
     reloadConfig: dependencies.reloadConfig,

package/node_modules/@nklisch/pi-clearance/src/config/paths.ts

@@ -12,12 +12,18 @@ export interface ConfigPaths {
 }
 
 export function resolveUserConfigRoot(): string {
-  const home = homedir();
+  // Read the environment explicitly so isolated callers honor the process
+  // environment even when os.homedir() is cached.
+  const home = firstNonEmpty(
+    process.env.HOME,
+    process.env.USERPROFILE,
+  ) ?? homedir();
 
   switch (process.platform) {
     case "win32":
       return path.join(
-        process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"),
+        firstNonEmpty(process.env.LOCALAPPDATA) ??
+          path.join(home, "AppData", "Local"),
         "pi",
         "pi-clearance",
       );
@@ -31,13 +37,18 @@ export function resolveUserConfigRoot(): string {
       );
     default:
       return path.join(
-        process.env.XDG_CONFIG_HOME ?? path.join(home, ".config"),
+        firstNonEmpty(process.env.XDG_CONFIG_HOME) ??
+          path.join(home, ".config"),
         "pi",
         "pi-clearance",
       );
   }
 }
 
+function firstNonEmpty(...values: readonly (string | undefined)[]): string | undefined {
+  return values.find((value) => value !== undefined && value.length > 0);
+}
+
 export function projectKeyFor(cwd: string): string {
   const absolute = path.resolve(cwd);
   const hash = createHash("sha256").update(absolute).digest("hex").slice(0, 8);

package/node_modules/@nklisch/pi-clearance/src/config/persistence.ts

@@ -0,0 +1,135 @@
+import {
+  CONFIG_SCHEMA_VERSION,
+  type GlobalConfig,
+  GlobalConfigSchema,
+  normalizeConfig,
+  type ProjectOverlayConfig,
+  ProjectOverlaySchema,
+} from "./schema.ts";
+
+export type ConfigPersistenceKind = "global" | "project";
+export type NormalizedConfig = GlobalConfig | ProjectOverlayConfig;
+
+/** The only JSON shape emitted for user-owned Clearance config files. */
+export type SparseConfigDocument = Readonly<Record<string, unknown>> & {
+  readonly version: typeof CONFIG_SCHEMA_VERSION;
+};
+
+const OMIT = Symbol("omit-default");
+
+/**
+ * Serialize a schema-normalized runtime config without materializing defaults.
+ *
+ * Defaults are obtained by normalizing the schema's version-only seed rather
+ * than copied here. Objects are compacted recursively; arrays are semantic
+ * values and are retained as a whole whenever they differ from their default.
+ */
+export function serializeSparseConfig(
+  kind: ConfigPersistenceKind,
+  config: NormalizedConfig,
+): SparseConfigDocument {
+  const defaults = normalizedDefaults(kind);
+  const compacted = compactValue(config, defaults);
+  const document: Record<string, unknown> = {
+    version: config.version,
+  };
+
+  if (isRecord(compacted)) {
+    for (const [key, value] of Object.entries(compacted)) {
+      if (key !== "version") {
+        document[key] = value;
+      }
+    }
+  }
+
+  return canonicalize(document) as SparseConfigDocument;
+}
+
+/** Return the canonical on-disk representation for a normalized config. */
+export function serializeSparseConfigText(
+  kind: ConfigPersistenceKind,
+  config: NormalizedConfig,
+): string {
+  return `${JSON.stringify(serializeSparseConfig(kind, config), null, 2)}\n`;
+}
+
+function normalizedDefaults(kind: ConfigPersistenceKind): NormalizedConfig {
+  const schema = kind === "global" ? GlobalConfigSchema : ProjectOverlaySchema;
+  const result = normalizeConfig(schema, { version: CONFIG_SCHEMA_VERSION });
+  if (!result.ok) {
+    throw new Error(`failed to normalize ${kind} config defaults`);
+  }
+  return result.value;
+}
+
+function compactValue(value: unknown, defaults: unknown): unknown {
+  if (jsonEqual(value, defaults)) {
+    return OMIT;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneJsonish(entry));
+  }
+
+  if (isRecord(value)) {
+    const defaultRecord = isRecord(defaults) ? defaults : undefined;
+    const compacted: Record<string, unknown> = {};
+    for (const key of orderedKeys(Object.keys(value))) {
+      const child = compactValue(value[key], defaultRecord?.[key]);
+      if (child !== OMIT) {
+        compacted[key] = child;
+      }
+    }
+    return Object.keys(compacted).length === 0 ? OMIT : compacted;
+  }
+
+  return value;
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+
+  if (isRecord(value)) {
+    const result: Record<string, unknown> = {};
+    for (const key of orderedKeys(Object.keys(value))) {
+      result[key] = canonicalize(value[key]);
+    }
+    return result;
+  }
+
+  return value;
+}
+
+function orderedKeys(keys: readonly string[]): readonly string[] {
+  return [...keys].sort((left, right) => {
+    if (left === "version") return -1;
+    if (right === "version") return 1;
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+
+function jsonEqual(left: unknown, right: unknown): boolean {
+  return (
+    JSON.stringify(canonicalize(left)) === JSON.stringify(canonicalize(right))
+  );
+}
+
+function cloneJsonish<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneJsonish(entry)) as T;
+  }
+
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, cloneJsonish(entry)]),
+    ) as T;
+  }
+
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}