dsh-perm-gate 5.1.2-compat.7 → 5.2.0

package/lib/risk.d.ts

@@ -5,8 +5,9 @@
  * asks the LLM to grade ONE tool call as either safe or risky with a category:
  *
  *   safe                      → the gate may auto-allow the ask
- *   risky:<hard category>     → deletion / credential / remote / system / bulk —
- *                               the operation looks dangerous; the gate KEEPS the
+ *   risky:<hard category>     → deletion / credential / remote / system / bulk /
+ *                               unknown-target — the operation looks dangerous or
+ *                               cannot be seen; the gate KEEPS the
  *                               human ask and never learns these into an
  *                               auto-allow. It is NOT an auto-deny: denying is
  *                               reserved for the deterministic layers (P0,
@@ -26,16 +27,22 @@
  */
 import { type ClassifierConfig } from './classifier.js';
 /** Risk categories the LLM may report for a risky verdict. */
-export type RiskCategory = 'deletion' | 'credential' | 'remote' | 'system' | 'bulk' | 'neutral';
+export type RiskCategory = 'deletion' | 'credential' | 'remote' | 'system' | 'bulk' | 'unknown-target' | 'neutral';
 /**
  * Categories that always route to the human seam regardless of learning state
  * or any later LLM opinion. Order-stable for prompts and event payloads.
  *
  * "Hard" means *never auto-allowed and never learned* — the gate keeps asking.
  * It does not mean auto-denied: the deny path belongs to the deterministic
- * layers alone (P0 hard-deny, the deny-keyword blacklist, explicit `deny:`
+ * layers (P0 hard-deny, the deny-keyword blacklist, explicit `deny:`
  * rules), so a misgraded category can always be negotiated instead of becoming
  * an unappealable block.
+ *
+ * `unknown-target` is the U tier — the payload could not be read (encoded blob,
+ * script outside the workspace, empty-args tool). It is deliberately **not** in
+ * any deny wordlist: "I cannot see it" is not evidence that it is bad, and a
+ * category the model is invited to guess would hand out unappealable blocks for
+ * opacity alone. Being hard is enough — ask, forever, learn nothing.
  */
 export declare const HARD_RISK_CATEGORIES: readonly RiskCategory[];
 /**
@@ -57,13 +64,33 @@ export type RiskVerdict = {
 } | {
     kind: 'unresolved';
 };
-/** The bounded call graded by {@link classifyRisk}. */
+/**
+ * The bounded call graded by {@link classifyRisk}.
+ *
+ * `args` may be passed raw: {@link riskUserText} redacts and bounds it before it
+ * leaves the process. The two scope fields exist because the prompt's own rules
+ * ("deletion inside the workspace is SAFE") were previously unenforceable — the
+ * grader was told to use a scope it was never given.
+ */
 export interface RiskRequest {
     readonly tool: string;
     readonly args: unknown;
     /** The deterministic reason the call reached the LLM-assist seam. */
     readonly reason: string;
+    /** Workspace root, so "inside the workspace" means something to the grader. */
+    readonly workspaceRoot?: string;
+    /** False for an encoded or unreadable payload: the U tier, never grade it safe. */
+    readonly targetResolvable?: boolean;
 }
+/**
+ * Prompt identity, recorded with every verdict.
+ *
+ * Measured on the eval set: one and the same wording halved disturbance on one
+ * model while costing another four to five irreversible misses. A grading prompt
+ * is therefore a versioned, falsifiable artifact — without this line, a wording
+ * change and a model swap are indistinguishable in the event log.
+ */
+export declare const RISK_SYSTEM_PROMPT_VERSION = "v7-terse-budget";
 /** Parse one assistant message into a verdict; anything off-protocol → undefined (caller retries/fails). */
 export declare function parseRiskVerdict(content: string): RiskVerdict | undefined;
 /**

package/lib/risk.js

@@ -5,8 +5,9 @@
  * asks the LLM to grade ONE tool call as either safe or risky with a category:
  *
  *   safe                      → the gate may auto-allow the ask
- *   risky:<hard category>     → deletion / credential / remote / system / bulk —
- *                               the operation looks dangerous; the gate KEEPS the
+ *   risky:<hard category>     → deletion / credential / remote / system / bulk /
+ *                               unknown-target — the operation looks dangerous or
+ *                               cannot be seen; the gate KEEPS the
  *                               human ask and never learns these into an
  *                               auto-allow. It is NOT an auto-deny: denying is
  *                               reserved for the deterministic layers (P0,
@@ -25,17 +26,25 @@
  * demonstrated by dsh-approval-gate.
  */
 import { chatCompletion, withLlmRetry } from './classifier.js';
+import { graderRulesText } from './grader-rules.js';
+import { redactArgs } from './redact.js';
 /**
  * Categories that always route to the human seam regardless of learning state
  * or any later LLM opinion. Order-stable for prompts and event payloads.
  *
  * "Hard" means *never auto-allowed and never learned* — the gate keeps asking.
  * It does not mean auto-denied: the deny path belongs to the deterministic
- * layers alone (P0 hard-deny, the deny-keyword blacklist, explicit `deny:`
+ * layers (P0 hard-deny, the deny-keyword blacklist, explicit `deny:`
  * rules), so a misgraded category can always be negotiated instead of becoming
  * an unappealable block.
+ *
+ * `unknown-target` is the U tier — the payload could not be read (encoded blob,
+ * script outside the workspace, empty-args tool). It is deliberately **not** in
+ * any deny wordlist: "I cannot see it" is not evidence that it is bad, and a
+ * category the model is invited to guess would hand out unappealable blocks for
+ * opacity alone. Being hard is enough — ask, forever, learn nothing.
  */
-export const HARD_RISK_CATEGORIES = ['deletion', 'credential', 'remote', 'system', 'bulk'];
+export const HARD_RISK_CATEGORIES = ['deletion', 'credential', 'remote', 'system', 'bulk', 'unknown-target'];
 const RISK_CATEGORIES = [...HARD_RISK_CATEGORIES, 'neutral'];
 /**
  * Whether a category must never be auto-allowed — and never learned into one.
@@ -47,9 +56,18 @@ export function isHardRisk(category) {
     // An unknown category means the verdict is unreliable — treat it as hard.
     return !RISK_CATEGORIES.includes(category);
 }
+/**
+ * Prompt identity, recorded with every verdict.
+ *
+ * Measured on the eval set: one and the same wording halved disturbance on one
+ * model while costing another four to five irreversible misses. A grading prompt
+ * is therefore a versioned, falsifiable artifact — without this line, a wording
+ * change and a model swap are indistinguishable in the event log.
+ */
+export const RISK_SYSTEM_PROMPT_VERSION = 'v7-terse-budget';
 const RISK_SYSTEM_PROMPT = [
     'You are the risk grader inside a permission gate for a coding agent.',
-    'You receive one tool call (tool name, arguments, and the deterministic reason it needs human-grade review).',
+    'You receive one tool call (tool, arguments, and the deterministic reason it needs human review).',
     'Grade whether executing it could cause irreversible damage or touch sensitive resources.',
     '',
     'Reply with ONLY one JSON object and nothing else:',
@@ -57,28 +75,15 @@ const RISK_SYSTEM_PROMPT = [
     '  {"risk":"risky","category":"<category>","reason":"short"}',
     '',
     'category must be exactly one of:',
-    '  deletion  — deletes or overwrites data that cannot be regenerated (IMPORTANT: see exclusion rules below)',
+    '  deletion  — destroys or overwrites data that cannot be regenerated (see the exclusion rules below)',
     '  credential — creates/modifies/exposes credentials, keys, tokens, auth config',
-    '  remote    — WRITES to or MODIFIES remote systems (git push, git deploy, kubectl apply, terraform apply, production database writes, messaging, billing, publishing). Must have a write/modify/delete effect on the remote side.',
+    '  remote    — WRITES to or MODIFIES remote systems (git push, deploy, kubectl/terraform apply, production database writes, messaging, billing, publishing): the effect must land on the remote side.',
     '  system    — system-level paths or configuration (/etc, /usr, boot items), shutdown/reboot',
     '  bulk      — mass overwrite of many files, formatting, dd-style irreversible writes',
-    '  neutral   — none of the above clearly applies (ordinary edits outside the obvious scope, or you are unsure but see no hard-risk sign)',
+    '  unknown-target — the call acts on something unreadable (encoded payload, script outside the workspace, empty arguments). Ask; assume nothing.',
+    '  neutral   — none of the above clearly applies, or you are unsure but see no hard-risk sign',
     '',
-    'Rules:',
-    '- safe is only for reversible, in-scope operations that touch no sensitive resource.',
-    '- When unsure between safe and neutral, answer neutral; never guess safe.',
-    '- Judge the operation content, not merely its location.',
-    '',
-    'DELETION exclusion rules (these override the deletion category):',
-    '- Cleanup of temporary files, build outputs, or failed clone directories is SAFE — even if using rm/rmdir/Remove-Item. Look for temp paths: paths containing "temp", "tmp", "test-clone", "node_modules", ".cache", "dist", "build", or numbered/timestamped directories.',
-    '- Removal of session-local artifacts (files the session itself created) is SAFE.',
-    '- rm -rf on node_modules, .next, __pycache__, .pytest_cache, .git, dist, build is SAFE — these are always regenerable.',
-    '- Deletion inside the workspace that targets non-existent or already-empty paths is SAFE (idempotent cleanup).',
-    '- Only flag as deletion when the target is: (a) user data with no backup, (b) configuration files, (c) database records, (d) files outside the workspace that were not created by this session, or (e) a destructive rm -rf on a directory containing unique, irreplaceable content.',
-    '',
-    'READ-ONLY remote operations are safe: git fetch, git pull, git clone, git log, git diff, git status, git show, npm install (read-only), pip install (read-only), apt-get update, curl/wget (read, no write flag).',
-    '- Operations that only READ from remote systems without modifying them are safe, even if they involve network traffic.',
-    '- Only flag as remote when the operation WRITES, DEPLOYS, PUSHES, or DELETES on the remote side.',
+    ...graderRulesText().split('\n'),
 ].join('\n');
 /** Parse one assistant message into a verdict; anything off-protocol → undefined (caller retries/fails). */
 export function parseRiskVerdict(content) {
@@ -117,23 +122,22 @@ export async function classifyRisk(cfg, req, nowFetch = fetch) {
 }
 /** The bounded user prompt for one risk grading (shared by every transport). */
 export function riskUserText(req) {
-    // Enrich the prompt with full path context so the LLM can judge
-    // whether a deletion targets a temporary/build artifact vs real data.
-    const args = (req.args ?? {});
-    const enriched = { ...args };
-    // Surface the working directory if present (helps LLM see temp paths).
-    if (typeof enriched.cwd === 'string' && enriched.cwd !== '') {
-        enriched.__cwd = enriched.cwd;
-    }
-    if (typeof enriched.workdir === 'string' && enriched.workdir !== '') {
-        enriched.__cwd = enriched.workdir;
-    }
-    return JSON.stringify({
-        tool: req.tool,
-        args: enriched,
-        reason: req.reason,
-        instruction: 'Reply strictly as one JSON object: {"risk":"safe"} or {"risk":"risky","category":"..."} plus a short "reason".',
-    });
+    // Nothing here leaves the process unredacted: `args` used to be serialized
+    // whole — file bodies and inline credentials included — to a user-configured
+    // third-party endpoint, while `classifier.ts` documented that secrets had been
+    // stripped upstream. They had not.
+    const args = redactArgs(req.args ?? {});
+    // Surface the working directory so the LLM can see temp/build paths, and give
+    // it the scope anchor its own prompt already relies on.
+    if (typeof args.cwd !== 'string' && typeof args.workdir === 'string')
+        args.__cwd = args.workdir;
+    const payload = { tool: req.tool, args, reason: req.reason };
+    if (req.workspaceRoot !== undefined && req.workspaceRoot !== '')
+        payload.workspace_root = req.workspaceRoot;
+    if (req.targetResolvable !== undefined)
+        payload.target_resolvable = req.targetResolvable;
+    payload.instruction = 'Reply strictly as one JSON object: {"risk":"safe"} or {"risk":"risky","category":"..."} plus a short "reason".';
+    return JSON.stringify(payload);
 }
 /**
  * Grade one tool call through any transport. Up to two attempts (one retry);

package/lib/runtime.d.ts

@@ -8,9 +8,22 @@ import { type HostLlmLike, type HostModelSelection } from './host-llm.js';
 import { type CompiledRuleEntry, type CompiledRuleset, type RuleAction } from './rule.js';
 import type { NetworkTarget } from './network.js';
 import { type SessionEventLike } from './preset.js';
+/**
+ * The gate's answer to the host's pre-execute waterfall.
+ *
+ * `displayReason` is part of the host's own ask contract: the registry forwards it
+ * to `approval/request` for presentation only, while `reason` remains the durable,
+ * machine-readable text that rules, audit and grants key off. Keeping the human-
+ * facing explanation in a separate field is what lets the popup say *what is about
+ * to happen* without polluting the record used for decisions.
+ */
 export interface PreToolDecisionLike {
     kind: 'deny' | 'ask';
     reason: string;
+    displayReason?: {
+        readonly en: string;
+        readonly [locale: string]: string;
+    };
 }
 /** The sandbox hook's verdict for one allowed shell call (appcontainer seam). */
 export type SandboxRewriteOutcome = {
@@ -105,6 +118,15 @@ interface PendingAsk {
     readonly snapshotId: number;
     /** Set when this ask also registered a learning candidate (drives the progress chip). */
     readonly learningKey?: string;
+    /**
+     * The card the human was shown, kept so the terminal event can carry it.
+     * Without this the approval list shows only the audit `reason` and a past
+     * decision cannot be read back — the popup's explanation existed for seconds
+     * and then vanished.
+     */
+    readonly humanBrief?: string;
+    readonly humanCommand?: string;
+    readonly doubtKinds?: readonly string[];
 }
 export interface PermGateRuntimeOptions extends PermGateConfig {
     /** Workspace root for chain resolution. Defaults to process.cwd(). */
@@ -228,6 +250,11 @@ export type ApprovalOutcomeLike = 'allowed-once' | 'rejected' | 'cancelled' | 'u
  * One approval ask the gate raises on behalf of a subprocess network
  * connection. Structurally the subset of the DSH `ApprovalRequest` the gate
  * supplies — the host service adds the borrowed session/log handling.
+ *
+ * `displayReason` is the host's own field (`ApprovalRequestEvent`), for localized
+ * presentation that is deliberately never persisted into the audit pair. It exists
+ * so a human can be shown *what is about to happen* rather than one opaque
+ * internal sentence; `reason` stays the durable, machine-readable record.
  */
 export interface NetworkApprovalRequest {
     /** The host agent the question is asked on behalf of (routes the prompt). */
@@ -237,6 +264,11 @@ export interface NetworkApprovalRequest {
     /** The exact tool call, when the host gave one — lets the UI attach the prompt. */
     readonly callId?: string;
     readonly reason: string;
+    /** Presentation-only text, keyed by locale (`en` required). */
+    readonly displayReason?: {
+        readonly en: string;
+        readonly [locale: string]: string;
+    };
     readonly signal?: AbortSignal;
 }
 /** The attribution the proxy layer receives for one connection. */
@@ -437,6 +469,13 @@ export declare class PermGateRuntime {
      * allow path (deny wins over allow). Purely additive to P0 — it can only ever
      * deny, never widen. Matching is boundary-aware and skips document bodies, so
      * a keyword can no longer veto an unrelated identifier or a file's text.
+     *
+     * Decoded layers are scanned too (B6 wiring). An `-EncodedCommand` blob is
+     * invisible to every keyword below, and this layer — unlike P0 — is a blacklist
+     * the user edits, so "the text you told me to refuse is in there" is exactly
+     * what it should be able to say. Only variants the visible command really hands
+     * to an execution primitive qualify, and no decoded text is written back to the
+     * call, the reason, or the event: the reason names the keyword, never the blob.
      */
     private denyKeywordHit;
     /**
@@ -451,8 +490,32 @@ export declare class PermGateRuntime {
     private trackAsk;
     /** Drop one tracked ask without recording it (the call never needed a human). */
     private untrackAsk;
+    /**
+     * Record that a pending ask was evicted by capacity, so "the popup never came
+     * back" is diagnosable instead of silent. Audited rather than fed to the event
+     * feed: no new event `kind` is introduced, so nothing can be mis-rendered as an
+     * allow by `presentation()`'s default branch.
+     */
+    private recordAskEviction;
     /** Asks currently awaiting a terminal answer (diagnostics/tests). */
     pendingAskCount(): number;
+    /**
+     * Pending-ask capacity health: how many asks are in flight, the cap, and how
+     * many have been evicted. Surfaces the case where the gate asks more than it can
+     * track, which otherwise looks identical to a lost approval.
+     */
+    pendingAskStats(): {
+        size: number;
+        cap: number;
+        evictions: number;
+        lastEviction?: {
+            key: string;
+            tool: string;
+            reason: string;
+        };
+    };
+    private askEvictions;
+    private lastAskEviction;
     /**
      * Remember that the gate positively allowed one call, so an approval raised from
      * inside that same call can be answered from this verdict.
@@ -552,6 +615,25 @@ export declare class PermGateRuntime {
      * settled by {@link settleExecution} when the call actually executes.
      */
     refineAsk(exec: ToolExecutionLike, decision: PreToolDecisionLike): Promise<PreToolDecisionLike | undefined>;
+    /**
+     * One frozen view of a call, built the same way for every ask path so the
+     * popup cannot disagree with what the grader was shown.
+     */
+    private contextFor;
+    /**
+     * An ask plus the card the human actually needs, in the host's presentation-only field.
+     *
+     * The plan's B4 clause lists five things for the popup — the redacted command,
+     * the files with their true total, the category, the reversibility and the tier
+     * knobs. `reason` alone cannot carry them: it is the audited string, and `REASON_MAX`
+     * truncates at 200 characters. `displayReason` is the host's own channel for
+     * presentation that never enters the audit pair, so the card goes there — starting
+     * with the audited reason (why the gate is asking at all), then the redacted
+     * command, the file list, the language-neutral tokens and the sentence about what
+     * each button costs. Without the command line a person is asked to approve an
+     * operation they cannot read, which is the complaint this task exists to fix.
+     */
+    private askDecision;
     /**
      * Record the human's terminal answer for one tracked ask. This is the primary
      * channel, driven by the `approval/request` observer, which sees the closed