dsh-perm-gate 5.1.2 → 5.3.0

package/lib/credential-paths.js

@@ -0,0 +1,119 @@
+/**
+ * User-declared credential paths — the long tail the built-in list cannot know.
+ *
+ * The built-in credential set (`.ssh`, `.aws`, `.npmrc`, `credentials.yaml`, …) ships in
+ * `path.ts` because the layer that needs it is P0: a `read`/`grep` call is auto-allowed
+ * one stage before the rule chain runs, and mutating a file tool never reaches a model
+ * that could be talked out of it. That is also why this cannot simply be "add a rule to
+ * `rules.yml`" for the read side — see the note in `runtime.ts` about why the auto-allow
+ * does not consult the ruleset (preset entries and hand-written entries live in one
+ * document with no provenance, so `.dsh/**` would start blocking legitimate memory
+ * reads).
+ *
+ * So the *list* is what a user extends, through the `credentialPaths` setting, and the
+ * *tier* stays where it has to be: a listed path gets the same treatment as the
+ * built-ins — reading it outside the workspace is refused, writing it is refused.
+ *
+ * Matching is pure string work: no filesystem access, no resolution, no execution. A
+ * pattern that cannot be understood is dropped rather than guessed at — an unreadable
+ * entry must not silently become "protects everything".
+ */
+/** Normalized, lowercase-able comparison form for a path or pattern. */
+function norm(p, caseInsensitive) {
+    const slashed = p.trim().replace(/[\\/]+/g, '/');
+    const stripped = slashed.length > 1 ? slashed.replace(/\/+$/, '') : slashed;
+    return caseInsensitive ? stripped.toLowerCase() : stripped;
+}
+/** Escape regex metacharacters that carry no meaning in a path glob. */
+function escapeRe(s) {
+    return s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Translate a path glob into a regex source.
+ *
+ * `**` is translated through a placeholder so it can be restored *after* the
+ * single-`*` rule ran — replacing them in the naive order turns `**` into `[^/]*[^/]*`,
+ * which silently stops crossing directories, i.e. `secrets/**` would match nothing.
+ */
+function globSource(glob) {
+    const CROSS = '\u0000';
+    return escapeRe(glob)
+        .replace(/\*\*/g, CROSS)
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]')
+        .split(CROSS)
+        .join('.*');
+}
+/**
+ * Compile one entry into a matcher over an already-normalized path.
+ *
+ * - contains `*` or `?` → glob: a double star crosses directories, a single star and
+ *   a question mark stay inside one. A pattern that is not absolute (no leading slash,
+ *   no drive letter) and does not already start with a crossing star is additionally
+ *   allowed to match at any depth (`secrets/STAR.env` covers `a/b/secrets/x.env`),
+ *   because that is what people mean when they write a relative glob.
+ * - no wildcard → path fragment: matches the path itself, or a whole leading/inner
+ *   segment run (`myco/token`, `.myco_token`, `vault/prod.env`).
+ */
+function compileEntry(raw, caseInsensitive) {
+    const entry = norm(raw, caseInsensitive);
+    if (entry === '' || entry === '/' || entry === '*')
+        return undefined;
+    const anchored = entry.startsWith('/') || /^[a-z]:/i.test(entry);
+    if (/[*?]/.test(entry)) {
+        const body = globSource(entry);
+        const source = anchored ? `^${body}$` : `(?:^|.*/)${body}$`;
+        let re;
+        try {
+            re = new RegExp(source, caseInsensitive ? 'i' : '');
+        }
+        catch {
+            return undefined;
+        }
+        return (path) => re.test(path);
+    }
+    // A plain entry is a path fragment, matched on segment boundaries only: `token` must
+    // not protect nothing while `.env` silently matches `ambient.txt`.
+    const withLead = entry.startsWith('.') || entry.includes('/') ? entry : `/${entry}`;
+    return (path) => path === entry || path.endsWith(withLead) || path.includes(`${withLead}/`) || (anchored && path.startsWith(entry));
+}
+/**
+ * Compile the configured credential paths into one predicate.
+ *
+ * Returns a matcher that answers `false` for an empty or unusable list, so callers can
+ * pass the raw setting straight through. `home` expands a leading `~/` the way a shell
+ * would, because the setting is written in home-relative form (`~/.myco/vault.token`)
+ * while the paths being judged are absolute. **Without `home`** the `~/` is stripped and
+ * the rest matched as a path fragment — a declared secret must not silently stop
+ * protecting because one caller did not know the user directory; the widened tail match
+ * only ever denies more, never less.
+ */
+export function compileCredentialPaths(entries, opts = {}) {
+    const caseInsensitive = opts.caseInsensitive ?? true;
+    const home = opts.home;
+    const matchers = [];
+    for (const raw of entries ?? []) {
+        if (typeof raw !== 'string')
+            continue;
+        let text = raw.trim();
+        if (text === '')
+            continue;
+        if (text === '~' || text.startsWith('~/') || text.startsWith('~\\')) {
+            const rest = text.slice(1).replace(/^[\\/]/, '');
+            text = home !== undefined && home !== ''
+                ? `${home.replace(/[\\/]+$/, '')}/${rest}`
+                // No home known: keep the tail. `~/.myco/vault.token` becomes `.myco/vault.token`,
+                // which still matches any user directory's copy of it.
+                : rest;
+        }
+        const m = compileEntry(text, caseInsensitive);
+        if (m !== undefined)
+            matchers.push(m);
+    }
+    if (matchers.length === 0)
+        return () => false;
+    return (path) => {
+        const p = norm(path, caseInsensitive);
+        return p !== '' && matchers.some((m) => m(p));
+    };
+}

package/lib/engine.d.ts

@@ -3,13 +3,11 @@ export type EngineStage = 'hard-deny' | 'grant' | 'rule' | 'default' | 'ask' | '
 /** The built-in read-only / internal classification, for diagnostics and docs. */
 export declare const AUTO_ALLOW_TOOLS: ReadonlySet<string>;
 /**
- * Argument keys that carry a document body rather than the operation itself.
- * A file's text is not the operation: writing a document that *mentions* a
- * token, a private key, or `credentials.yaml` must not hard-deny the write, and
- * the deny-keyword layer already skips these keys. The path/command arguments
- * that actually describe the operation are still scanned.
+ * The document-body keys the screens skip live in `scan-text.ts`, shared with the
+ * deny-keyword layer so the two cannot drift. Re-exported here because this was their
+ * published home.
  */
-export declare const CONTENT_ARG_KEYS: ReadonlySet<string>;
+export { CONTENT_ARG_KEYS } from './scan-text.js';
 /**
  * Deterministic P0 hard-deny reason, or undefined when the call may proceed to
  * later stages.

package/lib/engine.js

@@ -8,7 +8,8 @@
  *   P4 ask            official approval seam
  * Strictly fail-closed: P0 wins over every later stage.
  */
-import { isProtectedDestructiveTarget, isSensitivePath, isWithin } from './path.js';
+import { isProtectedCredentialPath, isProtectedDestructiveTarget, isSensitivePath, isWithin } from './path.js';
+import { compileCredentialPaths } from './credential-paths.js';
 import { commandIrreversibleReason, irreversibleReason } from './irreversible.js';
 import { executableVariants, normalizeCommandText } from './command-normalize.js';
 // 工具名名单归 `tool-names.ts` 所有（不得在此处再抄一份）。P0 **不看工具名白名单**：
@@ -23,46 +24,20 @@ const NO_EXTRA_AUTO_ALLOW = new Set();
 /** The built-in read-only / internal classification, for diagnostics and docs. */
 export const AUTO_ALLOW_TOOLS = new Set([...READ_TOOLS, ...INTERNAL_TOOLS]);
 /**
- * Argument keys that carry a document body rather than the operation itself.
- * A file's text is not the operation: writing a document that *mentions* a
- * token, a private key, or `credentials.yaml` must not hard-deny the write, and
- * the deny-keyword layer already skips these keys. The path/command arguments
- * that actually describe the operation are still scanned.
+ * The document-body keys the screens skip live in `scan-text.ts`, shared with the
+ * deny-keyword layer so the two cannot drift. Re-exported here because this was their
+ * published home.
  */
-export const CONTENT_ARG_KEYS = new Set([
-    'content', 'contents', 'text', 'body', 'message', 'prompt',
-    'new_string', 'old_string', 'newText', 'oldText', 'file_text', 'fileText',
-    'diff', 'patch', 'replacement', 'snippet',
-]);
-/** The call's non-body text: the operation, not any document it carries. */
-function operationText(args, depth = 0) {
-    if (depth > 6)
-        return '';
-    const parts = [];
-    for (const [key, value] of Object.entries(args)) {
-        if (typeof value === 'string') {
-            if (!CONTENT_ARG_KEYS.has(key))
-                parts.push(value);
-            continue;
-        }
-        if (Array.isArray(value)) {
-            for (const item of value) {
-                if (typeof item === 'string')
-                    parts.push(item);
-                else if (item !== null && typeof item === 'object')
-                    parts.push(operationText(item, depth + 1));
-            }
-            continue;
-        }
-        if (value !== null && typeof value === 'object') {
-            parts.push(operationText(value, depth + 1));
-        }
-    }
-    return parts.join(' ');
-}
+export { CONTENT_ARG_KEYS } from './scan-text.js';
+import { operationText } from './scan-text.js';
 /**
  * Credential or private-key material a call carries.
  *
+ * Read through `scan-text.operationText`, so a document tool's prose is no longer fed
+ * to this screen at all (issue #2): refusing `exit_plan_mode` because the plan *names*
+ * a step it intends to ask about is a self-contradiction — `decide()` classifies the
+ * same call as needing no approval one layer later.
+ *
  * Two clauses were removed on purpose, both because this predicate reads one flat
  * string and therefore cannot tell *using* a secret from *moving* one — and P0 is
  * the layer nobody can appeal:
@@ -78,8 +53,15 @@ function operationText(args, depth = 0) {
  * What is left is the theft shape: a secret *artifact* plus a channel out, or any
  * non-readonly verb touching one. That pairing lives in `irreversible.ts`, so both
  * layers agree.
+ *
+ * `id_` keeps its `.pub` half out: a public key is the artifact you hand *other*
+ * people, so writing `~/.ssh/id_ed25519.pub` (registering a key, restoring a pair by
+ * hand) was refused at the one layer nobody can appeal for no protective reason. The
+ * private halves stay in, as does `config` — an ssh config's `ProxyCommand` /
+ * `LocalCommand` is code that runs on the next connection, which is an execution
+ * plant, not a preference file.
  */
-const CREDENTIAL_MATERIAL = /(?:BEGIN (?:RSA |OPENSSH |EC )?PRIVATE KEY|\b(?:sk|ghp|github_pat|xox[baprs])[-_][A-Za-z0-9_-]{8,}\b|\.ssh[\\/](?:id_|config)|credentials\.yaml)/i;
+const CREDENTIAL_MATERIAL = /(?:BEGIN (?:RSA |OPENSSH |EC )?PRIVATE KEY|\b(?:sk|ghp|github_pat|xox[baprs])[-_][A-Za-z0-9_-]{8,}\b|\.ssh[\\/]id_(?![^\\/]*\.pub(?:$|[\\/]))|\.ssh[\\/]config|credentials\.yaml)/i;
 /** Verbs that only look. A call made of nothing else cannot have leaked anything. */
 const READ_ONLY_HEAD = /^(?:test-path|test|ls|dir|get-childitem|get-content|get-item|cat|type|more|head|tail|stat|file|select-string|where|which|exists)$/i;
 /** Whether every segment of this command text is a read-only look. */
@@ -92,8 +74,13 @@ function readonlyProbe(text) {
         return READ_ONLY_HEAD.test(head);
     });
 }
-function containsCredentialMaterial(args) {
-    const text = operationText(args);
+/**
+ * Credential or private-key material a call carries, read out of the *operation* text
+ * only — which is `scan-text`'s job, and why the key lists are a caller input: a document
+ * body is somebody's prose, not a theft in progress.
+ */
+function containsCredentialMaterial(ctx) {
+    const text = operationText(ctx.args, ctx.tool, ctx.scanKeys);
     return CREDENTIAL_MATERIAL.test(text) && !readonlyProbe(text);
 }
 function pathArgument(args) {
@@ -154,7 +141,7 @@ function gitRemoteRewriteReason(segments) {
  */
 export function hardDenyReason(ctx) {
     const args = ctx.args;
-    if (containsCredentialMaterial(args))
+    if (containsCredentialMaterial(ctx))
         return 'call contains credential or private-key material';
     // **Shape, not a name whitelist** (see tool-names.ts): a call that carries a
     // command string and is not a known non-executor is a command call whatever the
@@ -209,9 +196,33 @@ export function hardDenyReason(ctx) {
         if (isProtectedDestructiveTarget(path, ctx.dshHome))
             return `mutation targets protected path: ${path}`;
     }
+    // Credential-store mutation via a file tool is an access backdoor: dropping an
+    // `authorized_keys` line, `git config credential.helper store`, or rewriting
+    // `.git-credentials`/`.npmrc`/cloud creds grants or leaks authority. The shell
+    // layer already denies deletion of these stores and asks on reading them, but
+    // write/edit reached past the P0 guard because it only screened system roots, so
+    // `write ~/.ssh/authorized_keys` was auto-allowed. Scoped to file-mutation tools
+    // (not bash/pwsh, whose real target is the command string, judged above), and
+    // `.env` is excluded (project-local dev config).
+    //
+    // `credentialPaths` (a setting) is consulted here and in the read branch below: the
+    // long tail of secrets — a company vault file, a deploy key nobody shipped in a
+    // preset — has to be extendable, and this is the only layer that a *read* call cannot
+    // skip past. The tier is not configurable on purpose: a declared path gets exactly
+    // what `.ssh` gets, never a downgradable `ask`.
+    const declared = compileCredentialPaths(ctx.credentialPaths, {
+        caseInsensitive: ctx.caseInsensitive ?? false,
+        // `userHome`, not `home`: the latter is the workspace root. A caller that does not
+        // supply it gets the tail-match fallback in `compileCredentialPaths`, which is
+        // stricter, never looser.
+        ...(ctx.userHome === undefined ? {} : { home: ctx.userHome }),
+    });
+    if (path !== undefined && (ctx.tool === 'write' || ctx.tool === 'edit' || DESTRUCTIVE_TOOL.test(ctx.tool)) && isProtectedCredentialPath(path, declared)) {
+        return `mutation targets a credential store: ${path}`;
+    }
     if (READ_TOOLS.has(ctx.tool) && path !== undefined) {
         const normalized = path.startsWith('/') || /^[A-Za-z]:/.test(path) ? path : path;
-        if (!isWithin(ctx.cwd, normalized) && isSensitivePath(normalized)) {
+        if (!isWithin(ctx.cwd, normalized) && (isSensitivePath(normalized) || declared(path))) {
             return `read of sensitive path outside workspace: ${path}`;
         }
     }

package/lib/evaluate.d.ts

@@ -1,5 +1,6 @@
 import { type CompiledRuleEntry, type CompiledRuleset, type RuleAction } from './rule.js';
 import { type SimpleCommand } from './shell.js';
+import type { ScanKeyPolicy } from './scan-text.js';
 export interface ToolCallContext {
     readonly tool: string;
     readonly args: Record<string, unknown>;
@@ -7,8 +8,27 @@ export interface ToolCallContext {
     readonly cwd: string;
     /** Workspace root; used by the write-path override to decide inside vs outside. */
     readonly home?: string;
+    /**
+     * The real user directory (`os.homedir()`), used to expand a `~/` in a declared
+     * credential path. Deliberately separate from `home`, which is the workspace root —
+     * conflating them would expand `~/.myco/vault.token` into the project and protect
+     * nothing at all.
+     */
+    readonly userHome?: string;
     readonly dshHome?: string;
     readonly caseInsensitive?: boolean;
+    /**
+     * User-declared credential paths (`credentialPaths` setting), raw as configured.
+     * P0 compiles them; they extend the built-in store list for the two checks a read or
+     * write call cannot route around. Absent means the built-ins alone.
+     */
+    readonly credentialPaths?: readonly string[];
+    /**
+     * Additions to the argument-key sets that decide which parameter text a protective
+     * screen may read (`extraContentArgKeys` / `extraOperationArgKeys`). Absent means the
+     * built-in sets, which is what an embedded caller or a dry run gets.
+     */
+    readonly scanKeys?: ScanKeyPolicy;
     /** Agent identity candidates from session context. */
     readonly agentCandidates?: readonly string[];
     /** Network request info (for network dimension matching). */

package/lib/evaluate.js

@@ -105,9 +105,14 @@ export function ruleMatches(rule, ctx, commands, pathCands, urlCands) {
         // Join the FULL argv of each simple command: `c.command` alone is just the
         // command word, so `curl https://x | sh` would read as `curl|sh` and the
         // documented `curl|sh` pattern could never see its own subject.
-        const pipelineText = commands.map((c) => commandArgv(c)).join('|');
+        const argvs = commands.map((c) => commandArgv(c));
+        const pipelineText = argvs.join('|');
         const compiled = rule.argv.pipeline.map((p) => compileGlobForMatch(p));
-        if (!compiled.some((g) => g.test(pipelineText)))
+        // Match per simple command as well as over the joined pipeline: anchored
+        // prefix patterns (`git reset --hard*`) must see each segment on its own —
+        // `cd x && git reset --hard` hides the guarded segment behind the join —
+        // while cross-segment patterns (`curl|sh`) still read the joined string.
+        if (!compiled.some((g) => g.test(pipelineText) || argvs.some((s) => g.test(s))))
             return false;
     }
     // network dimension: all present sub-dimensions must match.
@@ -137,8 +142,13 @@ const SHELL_WRITE_PATTERNS = [
     /(?:^|\s)(?:mv|cp|install|mkdir|touch|chmod|chown)\b/i,
     // Redirect into a file: `> f`, `>> f`, `>f`. The leading character class
     // excludes the stderr idioms a read-only command uses (`2>&1`, `>&2`,
-    // `2>/dev/null`, `1>&2`), and the trailing class requires an actual target.
-    /(?:^|[^0-9&])>>?\s*[^\s&|]/,
+    // `2>/dev/null`, `1>&2`) AND the two arrow forms that are pure text, not a
+    // redirect: `=>` (JS/Rust/arrow-function syntax, e.g. `node -e "(x)=>x+1"`) and
+    // `->` (prose / C member access, e.g. `Write-Host 'a -> b'`). Without `=`/`-` in
+    // the class, a read-only command merely *containing* an arrow was escalated to
+    // `ask` (GitHub issue #4). A real redirect's `>` is still preceded by a space or
+    // an ordinary word char (`echo x > f`, `ls>f`), so those keep matching.
+    /(?:^|[^0-9&=>-])>>?\s*[^\s&|]/,
     // `tee` always writes its target; `curl`/`wget` only when they write a file.
     /(?:^|\s)tee\b/i,
     /(?:^|\s)(?:curl|wget)\b.*?(?:\s-[oO]\b|>)/i,
@@ -162,26 +172,33 @@ function isWriteCommand(commandText) {
  * - `shell` / `pwsh` / `terminal`: read-only commands (git status, python -c
  *   fetch, curl without redirect, etc.) follow `defaultAction`; commands that
  *   contain a write/execution pattern escalate to `ask` for review.
+ *
+ * The escalation names its own cause (GitHub issue #3). Reporting these as
+ * `no rule matched; default action` tells a reader the ruleset was silent, when in fact
+ * a safety screen just refused to let the default through — and it makes the popup say
+ * "no rule covers this" about a call a rule *did* cover in spirit.
  */
 function pathAndCommandDefault(ctx, pathCandidates, defaultAction) {
     if (defaultAction !== 'allow')
-        return defaultAction;
+        return undefined;
     // write/edit: path-aware (outside workspace → ask)
     if (WRITE_TOOLS.has(ctx.tool)) {
         const home = ctx.home;
         if (home !== undefined && home !== '') {
             for (const candidate of pathCandidates) {
-                if (normalizeWorkspacePath(home, candidate, ctx.caseInsensitive) === '')
-                    return 'ask';
+                if (normalizeWorkspacePath(home, candidate, ctx.caseInsensitive) === '') {
+                    return { action: 'ask', why: `write target outside the workspace (${candidate})` };
+                }
             }
         }
-        return defaultAction;
+        return undefined;
     }
     // shell/pwsh/terminal: command-content-aware (write pattern → ask)
     const commandText = commandTextOf(ctx);
-    if (commandText !== undefined && isWriteCommand(commandText))
-        return 'ask';
-    return defaultAction;
+    if (commandText !== undefined && isWriteCommand(commandText)) {
+        return { action: 'ask', why: 'command carries a file-write or redirect pattern' };
+    }
+    return undefined;
 }
 /**
  * Command text of a shell call: the explicit `commandText` field when set,
@@ -219,8 +236,15 @@ export function decideRules(ruleset, ctx) {
     // shell/pwsh/terminal tools check the command for write patterns.
     // Outside safety checks → ask; inside or read-only → defaultAction.
     let action = ruleset.defaultAction;
+    // Why this layer decided, when it is the one that decided (issue #3): kept separate
+    // from `no rule matched` so an audit line cannot impersonate a ruleset gap.
+    let screenWhy;
     if (WRITE_TOOLS.has(ctx.tool) || shellText !== undefined) {
-        action = pathAndCommandDefault(ctx, pathCands, action);
+        const escalated = pathAndCommandDefault(ctx, pathCands, action);
+        if (escalated !== undefined) {
+            action = escalated.action;
+            screenWhy = escalated.why;
+        }
     }
     if (action === 'allow' || action === 'ask') {
         const allow = scan(ruleset.allow, 'allow');
@@ -230,7 +254,11 @@ export function decideRules(ruleset, ctx) {
         if (ask !== undefined)
             return ask;
     }
-    return { action, reason: `no rule matched; default action`, ruleIndex: undefined };
+    return {
+        action,
+        reason: screenWhy === undefined ? 'no rule matched; default action' : `${screenWhy}; escalated by the default safety screen`,
+        ruleIndex: undefined,
+    };
 }
 function decomposeSafe(text) {
     try {

package/lib/feedback.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Deterministic review opinion for a blocked tool call — no LLM.
+ *
+ * Modeled on cc-safety-net's block message (`BLOCKED + Reason + Rule + intent
+ * instruction`): when the gate refuses a call, the main LLM should get a structured
+ * note telling it *why*, *which rule/layer* fired, and *what to do instead*, so it
+ * stays on task instead of retrying a variant. perm-gate already has the raw
+ * material — every preset entry tags its reason `[deny-rule:<id>]` and states a
+ * safer alternative in prose, and the deterministic layers emit `[hard-deny]`/
+ * `no rule matched` reasons — this module folds that into one classified opinion.
+ *
+ * Kept dependency-free and pure so it can be unit-tested and reused by both the
+ * node decision path and any UI.
+ */
+/** The five dispositions, mirroring cc-safety-net's intent taxonomy. */
+export type ReviewIntent = 'hard_stop' | 'use_alternative' | 'scope_down' | 'manual_only' | 'stop_and_explain';
+/** Per-intent guidance to the agent, zh + en (the opinion is fed to the main LLM). */
+export declare const INTENT_ADVICE: Readonly<Record<ReviewIntent, {
+    readonly zh: string;
+    readonly en: string;
+}>>;
+/** Extract the `[deny-rule:<id>]` tag, a gate-danger tag (YOLO / degraded review /
+ * mechanical passthrough), or P0. */
+export declare function ruleIdOf(reason: string): string | undefined;
+/**
+ * Classify a block reason into an intent. Ordered from the most specific signal to
+ * a conservative default; the phrasing of preset-rule reasons drives the match.
+ */
+export declare function intentForDeny(reason: string): ReviewIntent;
+/**
+ * The structured opinion for one blocked call. `command` must already be redacted by
+ * the caller. Returns the classified intent plus a single line suitable for the
+ * `工具审核意见: "<text>"` wrapper the listener delivers to the session.
+ */
+export declare function composeReviewOpinion(input: {
+    readonly command: string;
+    readonly reason: string;
+    readonly locale?: 'zh' | 'en';
+}): {
+    readonly intent: ReviewIntent;
+    readonly text: string;
+};

package/lib/feedback.js

@@ -0,0 +1,85 @@
+/**
+ * Deterministic review opinion for a blocked tool call — no LLM.
+ *
+ * Modeled on cc-safety-net's block message (`BLOCKED + Reason + Rule + intent
+ * instruction`): when the gate refuses a call, the main LLM should get a structured
+ * note telling it *why*, *which rule/layer* fired, and *what to do instead*, so it
+ * stays on task instead of retrying a variant. perm-gate already has the raw
+ * material — every preset entry tags its reason `[deny-rule:<id>]` and states a
+ * safer alternative in prose, and the deterministic layers emit `[hard-deny]`/
+ * `no rule matched` reasons — this module folds that into one classified opinion.
+ *
+ * Kept dependency-free and pure so it can be unit-tested and reused by both the
+ * node decision path and any UI.
+ */
+/** Per-intent guidance to the agent, zh + en (the opinion is fed to the main LLM). */
+export const INTENT_ADVICE = {
+    hard_stop: {
+        zh: '不得重试或绕过此操作；跳过它，继续任务的其余部分。',
+        en: 'Do not retry or bypass this operation; skip it and continue the rest of the task.',
+    },
+    use_alternative: {
+        zh: '不要重试被拦的形式；按上面给出的更安全替代继续。',
+        en: 'Do not retry the blocked form; continue with the safer alternative named above.',
+    },
+    scope_down: {
+        zh: '请把目标收窄到明确必需的路径再重试；确需大范围操作则上报用户。',
+        en: 'Retry with a narrower, explicitly-needed target; escalate to the user if a broad operation is truly required.',
+    },
+    manual_only: {
+        zh: '此命令无法静态核验，请交由用户手动执行。',
+        en: 'This command cannot be verified statically; ask the user to run it manually.',
+    },
+    stop_and_explain: {
+        zh: '不要暴力尝试变体；简化或重组命令后再试，或上报此拦截。',
+        en: 'Do not brute-force variants; simplify or restate the command, or report this block.',
+    },
+};
+/** Extract the `[deny-rule:<id>]` tag, a gate-danger tag (YOLO / degraded review /
+ * mechanical passthrough), or P0. */
+export function ruleIdOf(reason) {
+    const tag = /\[(deny-rule:[a-z0-9._-]+|(?:yolo|rules-fallback|safety-net)-danger:[a-z0-9._-]+)\]/.exec(reason);
+    if (tag?.[1] !== undefined)
+        return tag[1];
+    if (/\[hard-deny\]|hard-deny/i.test(reason))
+        return 'hard-deny';
+    return undefined;
+}
+/**
+ * Classify a block reason into an intent. Ordered from the most specific signal to
+ * a conservative default; the phrasing of preset-rule reasons drives the match.
+ */
+export function intentForDeny(reason) {
+    const r = reason.toLowerCase();
+    // unverifiable / opaque target, or an act that needs the user's own consent → a human runs it
+    if (/opaque|cannot be (read|verified|analyzed)|unanalyz|encoded|unread|unresolv|non-literal|dynamic|substitution-assembled|verify the variable|explicit consent|needs? (the )?user/.test(r))
+        return 'manual_only';
+    // explicit safer alternative offered → use it
+    if (/\buse\b|\bprefer\b|\bsafer\b|\binstead\b|\bstash\b|dry-?run|\bfirst\b|\bedit specific\b|narrower/.test(r))
+        return 'use_alternative';
+    // broad/target-set concerns → narrow it. A P0 `[hard-deny]` or an unattended block is
+    // never merely "too broad": those carry an irreversibility the agent may not trade
+    // away, so the scope signal must not downgrade them into a retry-with-narrower note.
+    if (/targets? (a )?(directory|many|mass|whole|entire)|broad|everything|scope|wildcard|\.\*|recurse/.test(r) && !/never|unrecoverable|irreversib|hard-deny|yolo: block|rules-fallback: block/.test(r))
+        return 'scope_down';
+    // truly irreversible / protected stores / credential / a graded risk → hard stop
+    if (/\bhard-deny\b|-danger:|irreversib|unrecoverable|cannot be (recovered|regenerated|undone)|wipe|destroy|credential|protected path|credential store|shadow|format|risk|delete shadows|force-overwrite|protected branch/.test(r))
+        return 'hard_stop';
+    return 'stop_and_explain';
+}
+/**
+ * The structured opinion for one blocked call. `command` must already be redacted by
+ * the caller. Returns the classified intent plus a single line suitable for the
+ * `工具审核意见: "<text>"` wrapper the listener delivers to the session.
+ */
+export function composeReviewOpinion(input) {
+    const intent = intentForDeny(input.reason);
+    const rule = ruleIdOf(input.reason);
+    const advice = INTENT_ADVICE[intent];
+    const locale = input.locale ?? 'zh';
+    const cleanReason = input.reason.replace(/\[(?:deny-rule:[a-z0-9._-]+|(?:yolo|rules-fallback|safety-net)-danger:[a-z0-9._-]+|hard-deny)\]\s*/gi, '').replace(/\s*·.*$/, '').trim();
+    const text = locale === 'zh'
+        ? `已拦截。依据：${rule ?? '默认策略'}。原因：${cleanReason}。处置(${intent})：${advice.zh}`
+        : `Blocked. Rule: ${rule ?? 'default policy'}. Reason: ${cleanReason}. Disposition(${intent}): ${advice.en}`;
+    return { intent, text };
+}

package/lib/index.d.ts

@@ -7,7 +7,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { Config } from './config.js';
-import { PermGateRuntime, type ToolExecutionLike } from './runtime.js';
+import { PermGateRuntime, type PreToolDecisionLike, type ToolExecutionLike } from './runtime.js';
 export declare const name = "dsh-perm-gate";
 /**
  * The `tools` service drives `tools/pre-execute`/`tools/result` (dsh-tools).
@@ -53,5 +53,5 @@ export declare function makeApprovalAnswerer(runtime: Pick<PermGateRuntime, 'set
  * `riskTimeoutMs` (default 20 s), and a grader failure keeps the original ask
  * (fail-closed).
  */
-export declare function makePreExecuteListener(runtime: Pick<PermGateRuntime, 'decideExecution' | 'refineAsk' | 'beginShellExecution'> & Partial<Pick<PermGateRuntime, 'sandboxRewrite'>>): (exec: ToolExecutionLike, next: () => Promise<unknown>) => Promise<unknown>;
+export declare function makePreExecuteListener(runtime: Pick<PermGateRuntime, 'decideExecution' | 'refineAsk' | 'beginShellExecution'> & Partial<Pick<PermGateRuntime, 'sandboxRewrite' | 'unattendedModeOf' | 'resolveYolo' | 'resolveSafetyNet'>>, feedback?: (exec: ToolExecutionLike, decision: PreToolDecisionLike) => void): (exec: ToolExecutionLike, next: () => Promise<unknown>) => Promise<unknown>;
 export declare function apply(ctx: Context, config?: Record<string, unknown>): PermGateRuntime;