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

package/lib/redact.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Redaction primitives for dsh-perm-gate.
+ *
+ * Before this module existed, the grader payload (`risk.ts riskUserText`)
+ * serialized the *whole* `args` object — including file bodies and inline
+ * credentials — and POSTed it to a user-configured third-party endpoint, while
+ * `classifier.ts` claimed secrets had already been stripped upstream. They had
+ * not. This module is the single place that makes that claim true.
+ *
+ * Three properties are load-bearing, and each has a test:
+ *
+ * 1. **Judgment-preserving.** Only secret *values* are masked; verbs, path
+ *    segments, flags and remote hosts survive, because the deterministic layers
+ *    (deny-keywords, `isCleanupSafe`, the parsers) and the reversibility tier
+ *    all read those. A redaction that hides `rm -rf /` would be a security
+ *    regression, so `adv_040/043/046/047` must still read as credential/remote.
+ * 2. **Idempotent.** Every replacement is a `[redacted:<kind>:<len>]` marker
+ *    that the patterns themselves refuse to re-match. Without this, piping an
+ *    already-redacted value through a second layer (grader payload + event
+ *    digest) silently rewrites lengths and breaks fingerprint stability.
+ * 3. **Bounded.** Long bodies collapse to a byte count plus a cheap hash, so
+ *    redaction also caps prompt size — grading latency is prefill-dominated.
+ *
+ * The hash here is FNV-1a, deliberately **not** a cryptographic digest: it only
+ * needs to identify "the same big body" across events. Security-sensitive
+ * digests (event `inputDigest`) use sha256 on the node half.
+ */
+/** Default ceiling for a redacted command string. */
+export declare const DEFAULT_MAX_COMMAND_CHARS = 800;
+/** Default ceiling for a single argument string before it collapses to a hash. */
+export declare const DEFAULT_MAX_ARG_CHARS = 200;
+/** Options for {@link redactCommandText}. */
+export interface RedactOptions {
+    /** Hard ceiling on the returned string; overflow is cut with a `…[+N]` tail. */
+    readonly maxChars?: number;
+}
+/**
+ * Redact one command/text string, preserving the structure the deterministic
+ * layers and the grader depend on. Idempotent by construction.
+ */
+export declare function redactCommandText(text: string, options?: RedactOptions): string;
+/** Options for {@link redactArgs}. */
+export interface RedactArgsOptions {
+    readonly maxStringChars?: number;
+    /** Cap on array length and object keys, so a huge payload cannot bloat the prompt. */
+    readonly maxItems?: number;
+    readonly maxDepth?: number;
+}
+/**
+ * Redact a tool-call argument bag for egress (grader payload, event digest,
+ * approval card). Keys are preserved — several are authority-bearing (host,
+ * path, command) — and values go through {@link redactCommandText}, with long
+ * bodies collapsed to a byte count plus a cheap identity hash.
+ */
+export declare function redactArgs(args: unknown, options?: RedactArgsOptions): unknown;

package/lib/redact.js

@@ -0,0 +1,183 @@
+/**
+ * Redaction primitives for dsh-perm-gate.
+ *
+ * Before this module existed, the grader payload (`risk.ts riskUserText`)
+ * serialized the *whole* `args` object — including file bodies and inline
+ * credentials — and POSTed it to a user-configured third-party endpoint, while
+ * `classifier.ts` claimed secrets had already been stripped upstream. They had
+ * not. This module is the single place that makes that claim true.
+ *
+ * Three properties are load-bearing, and each has a test:
+ *
+ * 1. **Judgment-preserving.** Only secret *values* are masked; verbs, path
+ *    segments, flags and remote hosts survive, because the deterministic layers
+ *    (deny-keywords, `isCleanupSafe`, the parsers) and the reversibility tier
+ *    all read those. A redaction that hides `rm -rf /` would be a security
+ *    regression, so `adv_040/043/046/047` must still read as credential/remote.
+ * 2. **Idempotent.** Every replacement is a `[redacted:<kind>:<len>]` marker
+ *    that the patterns themselves refuse to re-match. Without this, piping an
+ *    already-redacted value through a second layer (grader payload + event
+ *    digest) silently rewrites lengths and breaks fingerprint stability.
+ * 3. **Bounded.** Long bodies collapse to a byte count plus a cheap hash, so
+ *    redaction also caps prompt size — grading latency is prefill-dominated.
+ *
+ * The hash here is FNV-1a, deliberately **not** a cryptographic digest: it only
+ * needs to identify "the same big body" across events. Security-sensitive
+ * digests (event `inputDigest`) use sha256 on the node half.
+ */
+/** Marker prefix; a value that already starts with it is left untouched. */
+const MARK_PREFIX = '[redacted:';
+/**
+ * One marker, as `[redacted:<len>:<kind>]`.
+ *
+ * Length comes BEFORE the kind name on purpose: a marker written as
+ * `[redacted:token:24]` contains the literal `token:` + payload, which the
+ * generic key=value rule happily matches again on the second pass - breaking
+ * the idempotency this module promises. Putting the kind last (followed only by
+ * `]`) means no rule can find a `key`+separator pair inside a marker.
+ */
+function mark(kind, len) {
+    return `${MARK_PREFIX}${len}:${kind}]`;
+}
+/** Whether a captured payload is already one of our markers. */
+function alreadyRedacted(payload) {
+    return payload.trimStart().startsWith(MARK_PREFIX);
+}
+/** Default ceiling for a redacted command string. */
+export const DEFAULT_MAX_COMMAND_CHARS = 800;
+/** Default ceiling for a single argument string before it collapses to a hash. */
+export const DEFAULT_MAX_ARG_CHARS = 200;
+const rules = [
+    {
+        // PEM / OpenSSH / PGP private key blocks: mask the whole blob.
+        kind: 'pem',
+        re: /-----BEGIN(?:\s+[A-Z0-9]+)*\s+PRIVATE KEY-----[\s\S]*?-----END(?:\s+[A-Z0-9]+)*\s+PRIVATE KEY-----/gi,
+        pick: (m) => ({ before: '', secret: m, after: '' }),
+    },
+    {
+        // Auth headers: keep the header name (a remote-write signal) + the scheme.
+        kind: 'token',
+        re: /\b(authorization|proxy-authorization|x-api-key|api-key|x-amz-security-token|x-goog-api-key|cookie)\b(\s*[:=]\s*)((?:(?:bearer|basic|token)\s+)?)([^\s"',;]+)/gi,
+        pick: (_m, g) => ({ before: `${g[0]}${g[1]}${g[2]}`, secret: g[3] ?? '', after: '' }),
+    },
+    {
+        // URL userinfo: keep scheme + user + host, mask only the password.
+        kind: 'pw',
+        re: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:/?#@]*):([^\s@/?#]+)@/gi,
+        pick: (_m, g) => ({ before: `${g[0]}${g[1] ?? ''}:`, secret: g[2] ?? '', after: '@' }),
+    },
+    {
+        // Generic key = value secrets, quoted or bare.
+        kind: 'token',
+        re: /\b(password|passwd|pwd|secret|secret[_-]?key|client[_-]?secret|api[_-]?key|apikey|access[_-]?token|access[_-]?key|refresh[_-]?token|security[_-]?token|id[_-]?token|private[_-]?token|token)(\s*[:=]\s*)(["']?)([^\s"',;)]+)(\3)?/gi,
+        pick: (_m, g) => ({ before: `${g[0]}${g[1]}${g[2]}`, secret: g[3] ?? '', after: g[4] ?? '' }),
+    },
+    {
+        // Bare scheme + credential as a standalone value (e.g. an `authorization`
+        // object member whose value is `Bearer ...` - no header name in the string).
+        kind: 'token',
+        re: /\b(bearer|basic|token)\s+([A-Za-z0-9._~+/=-]{12,})/gi,
+        pick: (_m, g) => ({ before: `${g[0]} `, secret: g[1] ?? '', after: '' }),
+    },
+    {
+        // Provider-shaped tokens.
+        kind: 'token',
+        re: /\b(?:sk|ghp|gho|ghu|ghs|ghr|github_pat|xox[abprs]|glpat|dckr_pat|dpo_|sqat|ya29)\b[-_.][A-Za-z0-9_~-]{8,}|\bAKIA[0-9A-Z]{12,}|\bAIza[0-9A-Za-z_-]{20,}/g,
+        pick: (m) => ({ before: '', secret: m, after: '' }),
+    },
+    {
+        // Base64 / hex blobs: masked, but the *shape* (charset + length) is kept so
+        // the grader still sees "an opaque encoded payload is being shipped here".
+        kind: 'b64',
+        re: /(?<![A-Za-z0-9+/])[A-Za-z0-9+/]{24,}={0,2}(?![A-Za-z0-9+/=])/g,
+        pick: (m) => ({ before: '', secret: m, after: '' }),
+    },
+    {
+        kind: 'hex',
+        re: /(?<![0-9a-fA-F])[0-9a-fA-F]{32,}(?![0-9a-fA-F])/g,
+        pick: (m) => ({ before: '', secret: m, after: '' }),
+    },
+];
+/** Collapse to a bounded length, keeping a visible `…[+N]` tail. */
+function clamp(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const kept = text.slice(0, maxChars);
+    return `${kept}…[+${text.length - maxChars}]`;
+}
+/**
+ * Redact one command/text string, preserving the structure the deterministic
+ * layers and the grader depend on. Idempotent by construction.
+ */
+export function redactCommandText(text, options = {}) {
+    const maxChars = options.maxChars ?? DEFAULT_MAX_COMMAND_CHARS;
+    if (text === '')
+        return text;
+    let out = text;
+    for (const rule of rules) {
+        rule.re.lastIndex = 0;
+        out = out.replace(rule.re, (whole, ...rest) => {
+            // `rest` is the capture groups, then offset and the source string.
+            const groups = rest.slice(0, Math.max(0, rest.length - 2))
+                .map((g) => (typeof g === 'string' ? g : ''));
+            const { before, secret, after } = rule.pick(whole, groups);
+            // Skip anything already carrying a marker, so re-passing is a no-op.
+            if (whole.includes(MARK_PREFIX) || secret === '' || alreadyRedacted(secret))
+                return whole;
+            return `${before}${mark(rule.kind, secret.length)}${after}`;
+        });
+    }
+    return clamp(out, maxChars);
+}
+/** FNV-1a, 32-bit, hex. Identity only — never a security digest. */
+function fnv1a(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+/** Collapse a long body to a marker that still identifies it. */
+function collapseBody(text) {
+    return `${MARK_PREFIX}${text.length}B:text#${fnv1a(text)}]`;
+}
+function redactValue(value, opts, depth) {
+    const { maxStringChars, maxItems, maxDepth } = opts;
+    if (typeof value === 'string') {
+        if (alreadyRedacted(value))
+            return value;
+        if (value.length > maxStringChars)
+            return collapseBody(value);
+        return redactCommandText(value, { maxChars: maxStringChars });
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth >= maxDepth)
+        return mark('depth', Array.isArray(value) ? value.length : Object.keys(value).length);
+    if (Array.isArray(value)) {
+        const kept = value.slice(0, maxItems).map((v) => redactValue(v, opts, depth + 1));
+        if (value.length > maxItems)
+            kept.push(mark('more', value.length - maxItems));
+        return kept;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value).slice(0, maxItems)) {
+        out[k] = redactValue(v, opts, depth + 1);
+    }
+    return out;
+}
+/**
+ * Redact a tool-call argument bag for egress (grader payload, event digest,
+ * approval card). Keys are preserved — several are authority-bearing (host,
+ * path, command) — and values go through {@link redactCommandText}, with long
+ * bodies collapsed to a byte count plus a cheap identity hash.
+ */
+export function redactArgs(args, options = {}) {
+    const opts = {
+        maxStringChars: options.maxStringChars ?? DEFAULT_MAX_ARG_CHARS,
+        maxItems: options.maxItems ?? 50,
+        maxDepth: options.maxDepth ?? 6,
+    };
+    return redactValue(args, opts, 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