dsh-perm-gate 2.1.2 → 3.0.1

package/lib/runtime.js

@@ -11,7 +11,7 @@
 import { readFileSync } from 'node:fs';
 import { makeEntry, MemoryAuditMirror } from './audit.js';
 import { resolvePermissiveStrategies } from './config.js';
-import { appendAllowCommand, listAllowCommands, replaceAllowCommands } from './allowlist.js';
+import { appendAllowCommand, listAllowCommands, listAllowFromRulesDoc, replaceAllowCommands } from './allowlist.js';
 import { decide, CONTENT_ARG_KEYS } from './engine.js';
 import { EventLog, saveEventSnapshots } from './events.js';
 import { decideRules } from './evaluate.js';
@@ -21,13 +21,34 @@ import { ArtifactRegistry } from './path.js';
 import { classifyRisk, classifyRiskWith } from './risk.js';
 import { completeViaHost, DEFAULT_HOST_MODEL } from './host-llm.js';
 import { chatCompletion } from './classifier.js';
-import { compileDocument, documentHash, extractPathCandidates, parsePermissionsDocument } from './rule.js';
+import { compileDocument, compileRulesObject, documentHash, extractPathCandidates, parsePermissionsDocument, } from './rule.js';
 import { decomposeShellCommand } from './shell.js';
 import { extractAgentCandidates } from './agent-identity.js';
 import { resolveRuleChain } from './rule-chain.js';
 import { DEFAULT_DENY_KEYWORDS } from './deny-defaults.js';
 import { permissionPresetOf, presetInScope } from './preset.js';
 import { resolveGatePresets } from './config.js';
+/** Locate a rule by its chain-wide index (deny entries first, then allow, then ask). */
+function findRuleByIndex(ruleset, index) {
+    return (ruleset.deny.find((entry) => entry.index === index) ??
+        ruleset.allow.find((entry) => entry.index === index) ??
+        ruleset.ask.find((entry) => entry.index === index));
+}
+/** Which layer of the chain produced a decision, from its stage. */
+function sourceOfStage(stage, reason) {
+    switch (stage) {
+        case 'hard-deny':
+            return 'hard-deny';
+        case 'grant':
+            return 'grant';
+        case 'rule':
+            return 'rule';
+        case 'classifier':
+            return 'classifier';
+        default:
+            return reason.startsWith('permissive') ? 'permissive' : 'default';
+    }
+}
 /**
  * One execution's session event log, or `undefined` when the host exposes none.
  *
@@ -209,6 +230,12 @@ export class PermGateRuntime {
      * frozen events, which would otherwise re-fold on every tool call.
      */
     presetCache;
+    /**
+     * Last stand-down announced per session (sessionId → the out-of-scope preset
+     * name, `''` when the session records none). Bounded by the session count and
+     * only read on the stand-down path — the in-scope path never touches it.
+     */
+    standDownAnnounced = new Map();
     learning;
     events;
     /** Learning candidates awaiting human approval + execution (call fingerprint → candidate). */
@@ -252,6 +279,24 @@ export class PermGateRuntime {
             deny: [], allow: [], ask: [],
             caseInsensitivePaths: options.caseInsensitivePaths ?? true,
         };
+        // Settings-first (dual-source): a configured `dsh-perm-gate-rules`
+        // namespace overrides every file path — the gate then loads with zero
+        // filesystem dependency. Bare defaults (nothing configured) fall through
+        // to the file sources below. Compile errors propagate: the constructor
+        // fails loud, and `reload()` keeps the previous rules on a hot change.
+        const settingsDoc = options.readRulesDocument?.();
+        if (settingsDoc !== undefined) {
+            const hash = documentHash(JSON.stringify(settingsDoc));
+            const hit = this.cache.get(hash);
+            if (hit !== undefined)
+                return hit;
+            const compiled = compileRulesObject(settingsDoc, {
+                maxGlobStars: 2,
+                caseInsensitivePaths: options.caseInsensitivePaths ?? true,
+            });
+            this.cache.set(hash, compiled);
+            return compiled;
+        }
         // Chain mode: when searchUp is enabled, use the multi-file chain resolver.
         if (options.searchUp === true) {
             const cwd = options.cwd ?? process.cwd();
@@ -589,9 +634,38 @@ export class PermGateRuntime {
      * `danger-full-access` means "full access without approval prompts", where a
      * forwarded ask can only fail (the approval seam rejects before any answerer
      * runs) and a hard-deny would silently overrule the tier the user chose.
+     *
+     * P0 is therefore monotonic only WITHIN the gate's scope, not across every
+     * preset. {@link announceStandDown} makes that visible instead of silent.
      */
-    gateActive(exec) {
-        return presetInScope(this.presetOf(exec), this.gatePresets);
+    gateActive(preset) {
+        return presetInScope(preset, this.gatePresets);
+    }
+    /**
+     * Record one `stand-down` event the first time a session is observed with a
+     * preset outside {@link gatePresets}, and again whenever that preset changes.
+     *
+     * Per-call silence is what makes a stand-down dangerous: the tool call looks
+     * exactly like a call the gate inspected and allowed. One event per
+     * transition is enough to say otherwise, and keeps the feed (and the
+     * `events.jsonl` append) proportional to preset changes rather than to call
+     * volume.
+     *
+     * The event is a NOTICE, not a decision: it carries no allow/deny meaning,
+     * and the call it was observed on is still settled entirely by the selected
+     * tier. `verdict: 'stand-down'` labels it for the history view.
+     */
+    announceStandDown(exec, preset) {
+        const sessionId = sessionIdOf(exec);
+        const announced = preset ?? '';
+        if (this.standDownAnnounced.get(sessionId) === announced)
+            return;
+        this.standDownAnnounced.set(sessionId, announced);
+        const scope = this.gatePresets.includes('*') ? 'every preset' : this.gatePresets.join(', ');
+        const named = preset === undefined ? 'no permission/preset recorded' : `"${preset}"`;
+        this.recordEvent(exec, 'stand-down', `perm-gate is INACTIVE: the session permission preset is ${named} and the gate scope is ${scope}. `
+            + 'No P0 hard-deny, no rule, no ask and no allow is evaluated for any call in this session — '
+            + 'the selected tier\'s own policy governs. Select a preset in the gate scope to re-arm it.', { verdict: 'stand-down' });
     }
     /**
      * Whether an `ask` produced while the gate is active can actually reach a
@@ -808,10 +882,16 @@ export class PermGateRuntime {
      */
     decideExecution(exec) {
         // The gate is scoped to its own tier(s): anywhere else it stands down
-        // entirely and records nothing (the session's selected tier owns the call).
-        if (!this.gateActive(exec))
+        // entirely and decides nothing (the session's selected tier owns the call).
+        // The stand-down is announced ONCE per (session, preset) transition — the
+        // call's outcome is unchanged, but the user must be able to see that the
+        // gate — including P0 hard-deny — is inactive; a silent stand-down reads as
+        // "the gate looked at this and allowed it".
+        const preset = this.presetOf(exec);
+        if (!this.gateActive(preset)) {
+            this.announceStandDown(exec, preset);
             return undefined;
-        const ctx = this.ctxFor(exec);
+        }
         const callId = randomId();
         // Preset deny-keyword layer (deny wins over allow): a dangerous-keyword hit
         // vetoes before grants / rules / LLM. Additive deny only — P0 semantics are
@@ -823,13 +903,9 @@ export class PermGateRuntime {
             this.recordEvent(exec, 'deny', reason, { verdict: 'deny-keyword' });
             return { kind: 'deny', reason };
         }
-        const grantResolver = (tool, args) => {
-            if (exec.parentAuthorized === false)
-                return 'no-match';
-            return this.grants.decide(tool, args);
-        };
-        const raw = decide(ctx, { decide: (c) => decideRules(this.ruleset, c) }, grantResolver, this.autoAllowExtra);
-        const decision = this.applyPermissive(raw);
+        // The same chain `explainCall` reports, evaluated once here so the two views
+        // cannot drift; this caller adds the side effects and the session layers.
+        const decision = this.applyPermissive(this.rawPolicy(exec));
         // Deterministic cleanup pre-screen: if a deletion command targets a
         // regenerable/temporary artifact inside the workspace, allow it directly.
         // This runs BEFORE the ask/passthrough logic so it works even under
@@ -898,6 +974,83 @@ export class PermGateRuntime {
         this.clearCall(exec, decision.reason, source, source);
         return undefined;
     }
+    /**
+     * The **pure policy** outcome for one call: the same chain
+     * {@link decideExecution} runs, with every side effect and every session-state
+     * layer removed.
+     *
+     * Side effects removed — no audit entry, no event, no ask tracking, no call
+     * clearance, no learning. A rule-test panel must be able to run on every
+     * keystroke without writing to the live decision feed.
+     *
+     * Session-state layers removed — the preset stand-down and the
+     * `approval: never` ask degradation both describe a session a session-less
+     * caller does not have. Including them is not harmless: the degradation turns
+     * every "the rules would ask a human" into a reported **allow**, which is the
+     * opposite of the truth for exactly the rules someone opens the panel to
+     * review (measured on the live host: `shell ls -la` reported `allow` while the
+     * rule layer said `ask`).
+     *
+     * `reason` is never collapsed: "allow" has causes worth naming (a rule, a
+     * grant, cleanup-safety, the permissive default).
+     */
+    explainCall(exec) {
+        const keyword = this.denyKeywordHit(exec);
+        if (keyword !== undefined) {
+            return {
+                action: 'deny',
+                reason: `deny-keyword: matches preset blacklist entry "${keyword}"`,
+                source: 'deny-keyword',
+            };
+        }
+        const decision = this.applyPermissive(this.rawPolicy(exec));
+        if (decision.action === 'ask') {
+            const cleanupSafe = isCleanupSafe(exec);
+            if (cleanupSafe !== undefined) {
+                return { action: 'allow', reason: `cleanup-safe: ${cleanupSafe}`, source: 'cleanup-safe' };
+            }
+        }
+        return {
+            action: decision.action,
+            reason: decision.reason,
+            source: sourceOfStage(decision.stage, decision.reason),
+            ...(decision.ruleIndex !== undefined ? { ruleIndex: decision.ruleIndex } : {}),
+        };
+    }
+    /**
+     * P0 hard-deny → P1 session grant → P2 rules → P4 ask, as a value. Shared by
+     * the host-facing decision and {@link explainCall} so the two cannot drift.
+     */
+    rawPolicy(exec) {
+        const grantResolver = (tool, args) => {
+            if (exec.parentAuthorized === false)
+                return 'no-match';
+            return this.grants.decide(tool, args);
+        };
+        return decide(this.ctxFor(exec), { decide: (c) => decideRules(this.ruleset, c) }, grantResolver, this.autoAllowExtra);
+    }
+    /**
+     * Rule-layer explanation for one would-be call: what the `permissions` chain
+     * decides on its own, before P0 hard-deny, P1 session grants, the P3
+     * classifier and the P4 ask ever get a say.
+     *
+     * This is the read-only half of a dry-run. It appends nothing to the audit
+     * mirror, records no event, mints no grant and touches no learning store, so a
+     * "rule test" panel may call it on every keystroke without leaving a trace in
+     * the decision feed. It answers a narrower question than
+     * {@link decideExecution} and says so: `ruleIndex` identifies a rule in the
+     * chain, which only this layer can attribute.
+     */
+    explainRules(exec) {
+        const decision = decideRules(this.ruleset, this.ctxFor(exec));
+        return {
+            action: decision.action,
+            reason: decision.reason,
+            ruleIndex: decision.ruleIndex,
+            rule: decision.ruleIndex === undefined ? undefined : findRuleByIndex(this.ruleset, decision.ruleIndex),
+            defaultAction: this.ruleset.defaultAction,
+        };
+    }
     /**
      * Apply the Permissive tier to a raw decision. Hard-deny and minted-grant
      * outcomes are never touched (fail-closed). `alwaysConfirm` escalates a
@@ -1004,13 +1157,22 @@ export class PermGateRuntime {
         if (risk.kind === 'risky') {
             if (risk.category !== 'neutral') {
                 // Hard category (deletion / credential / remote / system / bulk) or an
-                // off-protocol output graded hard: auto-deny. The operation is clearly
-                // dangerous or sensitive — no popup, no learning, just block.
-                const reason = `${decision.reason} [llm-assist risky:${risk.category} → auto-deny]`;
-                this.audit.append(makeEntry({ callId: randomId(), tool: exec.name, outcome: 'deny', source: 'classifier', reason, at: Date.now() }));
-                this.recordEvent(exec, 'deny', reason, { risk: risk.category, verdict: 'llm-deny', category: risk.category });
-                this.untrackAsk(exec);
-                return { kind: 'deny', reason };
+                // off-protocol output graded hard: KEEP THE ASK.
+                //
+                // Denying here would make a probabilistic verdict the source of an
+                // unappealable block: the gate would be "sure enough" to refuse on the
+                // model's word alone, with no popup to appeal to and no grant to retry
+                // with — measured live on a benign `git commit -F …` the grader called
+                // `remote`. Deny stays with the deterministic layers (P0 hard-deny, the
+                // deny-keyword blacklist, explicit `deny:` rules); everything the
+                // classifier merely *suspects* is negotiated with the human instead.
+                //
+                // Hard categories stay distinct from `neutral` in one way that matters:
+                // they are NEVER learnable, so repeated confirmations cannot sediment
+                // them into an auto-allow.
+                const hardReason = `${decision.reason} [llm-assist risky:${risk.category} → ask]`;
+                this.trackAsk(exec, hardReason, undefined);
+                return { kind: 'ask', reason: hardReason };
             }
             const learning = this.liveRiskLearning();
             const fp = operationFingerprint(exec.name, exec.arguments ?? {}, exec.commandText);
@@ -1249,27 +1411,44 @@ export class PermGateRuntime {
     }
     /**
      * Grant "allow every occurrence of this command" (the always-confirm panel's
-     * second extended allow button): persist the command into the rules file's
-     * `allow` whitelist and reload. Returns the reload result.
+     * second extended allow button): persist the command into the rules' `allow`
+     * whitelist and reload. Prefers the settings-backed writer (the namespace's
+     * watch triggers the reload once the write lands); falls back to the rules
+     * file when no settings scope is wired. Returns the write verdict.
      */
     approveAllowEverywhere(commandWord, reason = 'permissive allow-everywhere') {
+        const writer = this.options.allowlistWriter;
+        if (writer !== undefined && writer.append(commandWord, reason))
+            return true;
         if (!this.options.rulesFile)
             return false;
         if (!appendAllowCommand(this.options.rulesFile, commandWord, reason))
             return false;
         return this.reload();
     }
-    /** Read-only view of the current allow-list command patterns (whitelist). */
+    /**
+     * Read-only view of the current allow-list command patterns (whitelist).
+     * Reads the settings document when the namespace is configured, else the
+     * rules file.
+     */
     allowlist() {
+        const doc = this.options.readRulesDocument?.();
+        if (doc !== undefined)
+            return listAllowFromRulesDoc(doc);
         if (!this.options.rulesFile)
             return [];
         return listAllowCommands(this.options.rulesFile);
     }
     /**
      * Replace the whitelist with exactly the given command patterns and reload.
-     * Returns the reload result (false when no rulesFile or the write failed).
+     * Prefers the settings-backed writer; falls back to the rules file when no
+     * settings scope is wired. Returns the write verdict (false when neither
+     * sink is available or the write failed).
      */
     setAllowlist(patterns) {
+        const writer = this.options.allowlistWriter;
+        if (writer !== undefined && writer.replace(patterns, 'permissive allowlist'))
+            return true;
         if (!this.options.rulesFile)
             return false;
         if (!replaceAllowCommands(this.options.rulesFile, patterns))

package/lib/shell.d.ts

@@ -19,6 +19,20 @@ export interface SimpleCommand {
     readonly redirects: readonly string[];
 }
 export type CmdFlag = 'recursive' | 'force';
+/**
+ * Reconstruct a simple command's full argv as one string.
+ *
+ * `SimpleCommand` splits the command into `command` + `args`, so any consumer
+ * that matches on a *whole command line* (the `argv.pipeline` dimension, the
+ * `branch` dimension's git parser) needs the parts joined back together —
+ * feeding only `command` loses every subcommand and flag (`git push --force
+ * origin main` degrades to `git`, which parses as "not a git command").
+ *
+ * Redirect targets are appended so a pattern naming the redirect target can
+ * match, and tokens containing whitespace are quoted so the reconstruction
+ * stays tokenizable.
+ */
+export declare function commandArgv(cmd: SimpleCommand): string;
 /**
  * Tokenize a shell string into tokens, honoring single/double quotes and a few
  * common escapes. Missing/EOF quotes throw so the caller can route an

package/lib/shell.js

@@ -1,3 +1,20 @@
+/**
+ * Reconstruct a simple command's full argv as one string.
+ *
+ * `SimpleCommand` splits the command into `command` + `args`, so any consumer
+ * that matches on a *whole command line* (the `argv.pipeline` dimension, the
+ * `branch` dimension's git parser) needs the parts joined back together —
+ * feeding only `command` loses every subcommand and flag (`git push --force
+ * origin main` degrades to `git`, which parses as "not a git command").
+ *
+ * Redirect targets are appended so a pattern naming the redirect target can
+ * match, and tokens containing whitespace are quoted so the reconstruction
+ * stays tokenizable.
+ */
+export function commandArgv(cmd) {
+    const quote = (token) => (/\s/.test(token) ? JSON.stringify(token) : token);
+    return [cmd.command, ...cmd.args, ...cmd.redirects].map(quote).join(' ');
+}
 const WRAPPER_WORDS = new Set(['env', 'sudo', 'command', 'nohup', 'xargs']);
 const COMMAND_WORDS = new Set(['sh', 'bash', 'zsh', 'dash', 'busybox', 'pwsh', 'powershell', 'cmd']);
 /**

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "dsh-perm-gate",
-  "version": "2.1.2",
+  "version": "3.0.1",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "tag": "dsh-0.1.2"
+  },
   "description": "DSH permission-gate for the DeepSeek Harness 0.1.2+ line: a single self-sufficient, deterministic-first, fail-closed gate covering P0 hard-deny -> P1 session grant -> P2 static rule (allow/deny) chain -> P3 optional LLM semantic classifier -> P4 ask, with command whitelist/blacklist.",
   "type": "module",
   "files": [
@@ -9,6 +14,7 @@
     "cordis.patch.yml",
     "dsh.plugin.json",
     "assets",
+    "docs",
     "examples",
     "README.md",
     "README.zh.md",
@@ -64,7 +70,17 @@
     "dsh": ">=0.1.2-alpha.1 <0.2.0-0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.2-alpha.1 <0.2.0-0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.2-alpha.1 <0.2.0-0",
+    "@deepseek-ai/dsh-client-ui-renderer": ">=0.1.2-alpha.1 <0.2.0-0",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.2-alpha.1 <0.2.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-locale": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-settings": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-renderer": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-conversation": { "optional": true }
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.0",
@@ -97,6 +113,7 @@
     "patch:glyph:check": "node scripts/patch-permission-glyph.mjs --check",
     "verify:line": "node scripts/verify-line.mjs new",
     "verify:lines": "node scripts/verify-line.mjs both",
+    "check:line": "node scripts/sync-0.1.5-line.mjs check",
     "release:latest": "npm publish --tag latest",
     "release:2x": "npm publish --tag 2.x",
     "release:legacy": "npm publish --tag legacy"