dsh-perm-gate 0.2.1-beta.3 → 0.2.1-beta.4

package/lib/config.d.ts

@@ -109,6 +109,22 @@ export interface PermissiveStrategies {
     readonly alwaysConfirm: boolean;
     /** LLM-assist classify first, human fallback on uncertainty or classifier failure. */
     readonly llmAssist: boolean;
+    /**
+     * Answer a sandbox-escalation approval for a call the gate already cleared.
+     *
+     * The escalation ask is raised from inside the tool body (`ctx.approval.request`)
+     * after `tools/pre-execute` has finished, so the gate's own allow never reaches
+     * it: without this strategy, a call the gate auto-allowed still prompts the human
+     * for the privilege widening. With it on, an `approval/request` whose reason is
+     * `escalate sandbox to <mode>: …` and whose `callId` the gate positively cleared
+     * is answered `allowed-once` here instead of being forwarded to the answerers.
+     *
+     * Only a call the gate *allowed* qualifies, the target must be a known sandbox
+     * mode, and any unrecognized request still delegates to the human — fail-closed.
+     * Turn it off to keep sandbox widening human-gated while other allows stay
+     * automatic.
+     */
+    readonly trustEscalation: boolean;
 }
 export declare const DEFAULT_PERMISSIVE_STRATEGIES: Readonly<PermissiveStrategies>;
 /**

package/lib/config.js

@@ -37,6 +37,10 @@ export const DEFAULT_PERMISSIVE_STRATEGIES = {
     trustAutoAllow: true,
     alwaysConfirm: false,
     llmAssist: false,
+    // On inside the tier: the tier already owns the allow decision for the call, and
+    // the classifier's hard categories (deletion / credential / remote / system /
+    // bulk) — the escalation-worthy ones — auto-deny rather than allow.
+    trustEscalation: true,
 };
 /**
  * Presets in which the gate is active. It owns the `permissive` tier; `'*'`
@@ -55,6 +59,7 @@ export function resolvePermissiveStrategies(bag = {}) {
         trustAutoAllow: bag.trustAutoAllow ?? DEFAULT_PERMISSIVE_STRATEGIES.trustAutoAllow,
         alwaysConfirm: bag.alwaysConfirm ?? DEFAULT_PERMISSIVE_STRATEGIES.alwaysConfirm,
         llmAssist: bag.llmAssist ?? DEFAULT_PERMISSIVE_STRATEGIES.llmAssist,
+        trustEscalation: bag.trustEscalation ?? DEFAULT_PERMISSIVE_STRATEGIES.trustEscalation,
     };
 }
 export const Config = z.object({
@@ -82,6 +87,7 @@ export const Config = z.object({
         trustAutoAllow: z.boolean().default(true),
         alwaysConfirm: z.boolean().default(false),
         llmAssist: z.boolean().default(false),
+        trustEscalation: z.boolean().default(true),
     }),
     allowlist: z.array(z.string()),
     denyKeywords: z.array(z.string()),

package/lib/index.d.ts

@@ -21,13 +21,24 @@ export { Config };
 /** Runtime settings namespace: `permissive` + `permissiveStrategies` (editable in the UI). */
 export declare const PERMISSIVE_NAMESPACE = "dsh-perm-gate";
 /**
- * Build the passive `approval/request` observer (exported for tests).
+ * Build the `approval/request` listener (exported for tests).
  *
- * It forwards the waterfall untouched and records the closed outcome for a
- * tracked ask. Recording is best-effort: a throw here would be normalized by
- * the approval service to `unavailable` — a rejection on the human's behalf.
+ * Two jobs, in this order:
+ *
+ * 1. **Answer an escalation the gate already decided.** A sandbox escalation is
+ *    raised by `approveEscalation` from *inside* a shell/filesystem tool body —
+ *    after `tools/pre-execute` settled — so the gate's own allow never reaches it
+ *    and a call it auto-allowed would still prompt the human for the privilege
+ *    widening. {@link PermGateRuntime.answerEscalation} returns `allowed-once` for
+ *    exactly that case (the Permissive tier on, `trustEscalation` on, a positively
+ *    cleared `callId` with a matching tool, a recognized escalation reason and
+ *    target mode) and `undefined` for every other request, which then delegates
+ *    unchanged.
+ * 2. **Record the terminal outcome** of an ask the gate did raise. This is
+ *    best-effort: a throw here would be normalized by the approval service to
+ *    `unavailable` — a rejection on the human's behalf.
  */
-export declare function makeApprovalObserver(runtime: Pick<PermGateRuntime, 'settleAskOutcome'>): (req: unknown, next: () => Promise<unknown>) => Promise<unknown>;
+export declare function makeApprovalAnswerer(runtime: Pick<PermGateRuntime, 'settleAskOutcome' | 'answerEscalation'>): (req: unknown, next: () => Promise<unknown>) => Promise<unknown>;
 /**
  * Build the `tools/pre-execute` waterfall listener (exported for tests).
  *

package/lib/index.js

@@ -78,14 +78,36 @@ function buildSessionSender(get) {
     };
 }
 /**
- * Build the passive `approval/request` observer (exported for tests).
+ * Build the `approval/request` listener (exported for tests).
  *
- * It forwards the waterfall untouched and records the closed outcome for a
- * tracked ask. Recording is best-effort: a throw here would be normalized by
- * the approval service to `unavailable` — a rejection on the human's behalf.
+ * Two jobs, in this order:
+ *
+ * 1. **Answer an escalation the gate already decided.** A sandbox escalation is
+ *    raised by `approveEscalation` from *inside* a shell/filesystem tool body —
+ *    after `tools/pre-execute` settled — so the gate's own allow never reaches it
+ *    and a call it auto-allowed would still prompt the human for the privilege
+ *    widening. {@link PermGateRuntime.answerEscalation} returns `allowed-once` for
+ *    exactly that case (the Permissive tier on, `trustEscalation` on, a positively
+ *    cleared `callId` with a matching tool, a recognized escalation reason and
+ *    target mode) and `undefined` for every other request, which then delegates
+ *    unchanged.
+ * 2. **Record the terminal outcome** of an ask the gate did raise. This is
+ *    best-effort: a throw here would be normalized by the approval service to
+ *    `unavailable` — a rejection on the human's behalf.
  */
-export function makeApprovalObserver(runtime) {
+export function makeApprovalAnswerer(runtime) {
     return async (req, next) => {
+        let answered;
+        try {
+            answered = runtime.answerEscalation(req);
+        }
+        catch {
+            // A gate failure must never reject on the human's behalf: fall through to
+            // the ordinary answerers.
+            answered = undefined;
+        }
+        if (answered !== undefined)
+            return answered;
         const outcome = await next();
         try {
             const callId = req?.callId;
@@ -280,7 +302,7 @@ export function apply(ctx, config = {}) {
             if (surface !== undefined && !Array.isArray(surface.allowlist)) {
                 const patterns = runtime.allowlist();
                 if (patterns.length > 0)
-                    void scope.set('allowlist', patterns.slice());
+                    void scope.update({ allowlist: patterns.slice() });
             }
             // Card edits -> namespace -> rulesFile (mirror + reload).
             scope.watch(() => {
@@ -377,22 +399,28 @@ export function apply(ctx, config = {}) {
     // and settle a pending learning candidate (a result for one means the human
     // approved it and it executed — one confirmation).
     host.on('tools/result', ((exec, result) => { runtime.settleExecution(exec, result); }));
-    // Primary terminal-answer channel: passively observe the approval waterfall.
-    // The ask we vetoed is forwarded by dsh-tools to `approval.request(...)`, so
-    // the closed outcome is observable here. This listener MUST return `next()`'s
-    // value unchanged — a throw is normalized to `unavailable`, i.e. a rejection
-    // on the human's behalf. Requests we never tracked (other agents, other
-    // sources) are ignored.
+    // Approval channel: answer an escalation the gate already cleared, and settle
+    // the outcome of an ask the gate did raise. Registered `prepend` so it sits at
+    // the head of the `approval/request` waterfall, ahead of the remote bridge that
+    // renders the browser prompt (`packages/api/remotes` registers a plain `ctx.on`).
+    // A listener behind that bridge could only ever record a prompt that was already
+    // shown. The `'never'` policy is unaffected: `ApprovalService.decide` resolves it
+    // before dispatching, so this gate is never consulted, and a rogue return value is
+    // normalized to `'unavailable'` by the service.
+    //
+    // This listener MUST return `next()`'s value unchanged when it does not answer —
+    // a throw is normalized to `unavailable`, i.e. a rejection on the human's behalf.
+    // Requests we never tracked (other agents, other sources) are ignored.
     const approvalAware = ctx;
     approvalAware.inject(['approval'], (actx) => {
         // Capture the live service: the gate reads `effectivePolicy` per call to
         // learn whether an ask can reach a human (`approval: never` cannot).
         approvalService = actx.approval;
-        const off = actx.on('approval/request', makeApprovalObserver(runtime));
+        const off = actx.on('approval/request', makeApprovalAnswerer(runtime), { prepend: true });
         actx.effect(() => () => {
             off();
             approvalService = undefined;
-        }, 'dsh-perm-gate: approval observer');
+        }, 'dsh-perm-gate: approval answerer');
     });
     return runtime;
 }

package/lib/runtime.d.ts

@@ -136,6 +136,14 @@ export interface RiskLearningState {
     readonly enabled: boolean;
     readonly threshold: number;
 }
+/** The minimal approval-request face the answering gate inspects. */
+export interface ApprovalRequestLike {
+    readonly toolName?: string;
+    readonly callId?: string;
+    readonly reason?: string;
+}
+/** A closed approval outcome, structurally the DSH seam's `ApprovalOutcome`. */
+export type ApprovalOutcomeLike = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
 export declare class PermGateRuntime {
     private readonly options;
     private ruleset;
@@ -162,6 +170,12 @@ export declare class PermGateRuntime {
      * missing `callId` or an untriggered observer can never lose a record.
      */
     private readonly pendingAsks;
+    /**
+     * Calls the gate positively allowed, keyed by the host execution id. An approval
+     * raised from *inside* such a call (the sandbox escalation) is answered here
+     * instead of prompting the human — see {@link answerEscalation}.
+     */
+    private readonly cleared;
     constructor(options?: PermGateRuntimeOptions);
     private compileInline;
     /** Reload rules from disk (HMR); on failure keeps the previous rules. */
@@ -246,6 +260,35 @@ export declare class PermGateRuntime {
     private untrackAsk;
     /** Asks currently awaiting a terminal answer (diagnostics/tests). */
     pendingAskCount(): number;
+    /**
+     * Remember that the gate positively allowed one call, so an approval raised from
+     * inside that same call can be answered from this verdict.
+     *
+     * Only real allow decisions reach here: a `gateActive` stand-down returns before
+     * any decision, and the `approval: never` passthrough is a degradation rather
+     * than an approval, so neither may widen the call's privilege.
+     */
+    private clearCall;
+    /** Drop one clearance (the call settled; nothing more can be asked from it). */
+    private forgetCleared;
+    /** Clearances retained right now (diagnostics/tests). */
+    clearedCallCount(): number;
+    /**
+     * Answer an in-call approval from the verdict that already cleared the call.
+     *
+     * The sandbox escalation is raised by `approveEscalation` from *inside* a shell
+     * or filesystem tool body — after `tools/pre-execute` settled — so the gate's
+     * allow never reaches it and a call the gate auto-allowed would still prompt the
+     * human for the privilege widening. Answering it here keeps the tier's contract:
+     * one decision per call.
+     *
+     * Returns `undefined` for every request that is not an escalation of a call this
+     * gate positively cleared, which delegates to the human unchanged (fail-closed).
+     *
+     * @param req - the `approval/request` payload (tool name, call id, reason).
+     * @returns `allowed-once` when the gate owns the answer, else `undefined`.
+     */
+    answerEscalation(req: ApprovalRequestLike | null | undefined): ApprovalOutcomeLike | undefined;
     /** Get one pending ask by its key (diagnostics/tests only). */
     getPendingAsk(key: string): PendingAsk | undefined;
     /**

package/lib/runtime.js

@@ -41,6 +41,25 @@ function cwdOf(exec) {
 }
 /** Upper bound on in-flight learning candidates awaiting `tools/result`. */
 const PENDING_CAP = 100;
+/**
+ * Bound on retained call clearances. An in-call approval is raised microseconds
+ * after the gate's decision, so the store only ever holds the calls currently
+ * executing; the cap keeps a pathological producer from growing it.
+ */
+const CLEARED_CALL_CAP = 256;
+/**
+ * How long a clearance may answer an in-call approval. Generous next to one tool
+ * call's lifetime, short enough that a stale entry cannot outlive its call.
+ */
+const CLEARED_CALL_TTL_MS = 5 * 60_000;
+/**
+ * The sandbox-escalation ask marker. `@deepseek-ai/dsh-sandbox`'s
+ * `approveEscalation` builds `escalate sandbox to <mode>: <justification>` for the
+ * approval request it raises from inside a shell/fs tool body. The request carries
+ * no structural kind field, so this reason text is the only discriminator; an
+ * unrecognized wording fails closed (the request is forwarded to the human).
+ */
+const SANDBOX_ESCALATION_REASON = /^escalate sandbox to (workspace-write|danger-full-access): /;
 export class PermGateRuntime {
     options;
     ruleset;
@@ -67,6 +86,12 @@ export class PermGateRuntime {
      * missing `callId` or an untriggered observer can never lose a record.
      */
     pendingAsks = new Map();
+    /**
+     * Calls the gate positively allowed, keyed by the host execution id. An approval
+     * raised from *inside* such a call (the sandbox escalation) is answered here
+     * instead of prompting the human — see {@link answerEscalation}.
+     */
+    cleared = new Map();
     constructor(options = {}) {
         this.options = options;
         this.grants = new GrantRegistry('__session__', options.now);
@@ -339,6 +364,94 @@ export class PermGateRuntime {
     pendingAskCount() {
         return this.pendingAsks.size;
     }
+    /**
+     * Remember that the gate positively allowed one call, so an approval raised from
+     * inside that same call can be answered from this verdict.
+     *
+     * Only real allow decisions reach here: a `gateActive` stand-down returns before
+     * any decision, and the `approval: never` passthrough is a degradation rather
+     * than an approval, so neither may widen the call's privilege.
+     */
+    clearCall(exec, reason, verdict, source) {
+        const callId = typeof exec.callId === 'string' ? exec.callId : '';
+        if (callId === '')
+            return;
+        if (this.cleared.size >= CLEARED_CALL_CAP) {
+            const oldest = this.cleared.keys().next();
+            if (!oldest.done)
+                this.cleared.delete(oldest.value);
+        }
+        const now = typeof this.options.now === 'function' ? this.options.now : Date.now;
+        this.cleared.set(callId, {
+            tool: exec.name,
+            reason,
+            verdict,
+            source,
+            sessionId: sessionIdOf(exec),
+            files: eventFiles(exec),
+            baseDir: cwdOf(exec),
+            at: now(),
+        });
+    }
+    /** Drop one clearance (the call settled; nothing more can be asked from it). */
+    forgetCleared(callId) {
+        if (callId !== '')
+            this.cleared.delete(callId);
+    }
+    /** Clearances retained right now (diagnostics/tests). */
+    clearedCallCount() {
+        return this.cleared.size;
+    }
+    /**
+     * Answer an in-call approval from the verdict that already cleared the call.
+     *
+     * The sandbox escalation is raised by `approveEscalation` from *inside* a shell
+     * or filesystem tool body — after `tools/pre-execute` settled — so the gate's
+     * allow never reaches it and a call the gate auto-allowed would still prompt the
+     * human for the privilege widening. Answering it here keeps the tier's contract:
+     * one decision per call.
+     *
+     * Returns `undefined` for every request that is not an escalation of a call this
+     * gate positively cleared, which delegates to the human unchanged (fail-closed).
+     *
+     * @param req - the `approval/request` payload (tool name, call id, reason).
+     * @returns `allowed-once` when the gate owns the answer, else `undefined`.
+     */
+    answerEscalation(req) {
+        const permissive = this.livePermissive();
+        if (!permissive.enabled || !permissive.strategies.trustEscalation)
+            return undefined;
+        const callId = typeof req?.callId === 'string' ? req.callId : '';
+        if (callId === '')
+            return undefined;
+        const target = SANDBOX_ESCALATION_REASON.exec(typeof req?.reason === 'string' ? req.reason : '')?.[1];
+        if (target === undefined)
+            return undefined;
+        const cleared = this.cleared.get(callId);
+        if (cleared === undefined)
+            return undefined;
+        if (typeof req?.toolName === 'string' && req.toolName !== '' && req.toolName !== cleared.tool)
+            return undefined;
+        const now = typeof this.options.now === 'function' ? this.options.now : Date.now;
+        if (now() - cleared.at > CLEARED_CALL_TTL_MS) {
+            this.cleared.delete(callId);
+            return undefined;
+        }
+        const reason = `sandbox escalation to ${target} auto-allowed: the gate cleared this call (${cleared.verdict})`;
+        this.audit.append(makeEntry({ callId: randomId(), tool: cleared.tool, outcome: 'allow', source: cleared.source, reason, at: now() }));
+        this.events?.append({
+            sessionId: cleared.sessionId,
+            tool: cleared.tool,
+            kind: 'auto',
+            reason,
+            verdict: 'escalation-auto',
+            justification: cleared.reason,
+            mode: target,
+            files: cleared.files,
+            baseDir: cleared.baseDir,
+        });
+        return 'allowed-once';
+    }
     /** Get one pending ask by its key (diagnostics/tests only). */
     getPendingAsk(key) {
         return this.pendingAsks.get(key);
@@ -425,6 +538,10 @@ export class PermGateRuntime {
             this.trackAsk(exec, decision.reason);
             return { kind: 'ask', reason: decision.reason };
         }
+        // A genuine allow (grant / rule / classifier / permissive default): remember it
+        // so a sandbox escalation raised from inside this same call is answered here
+        // rather than prompted. Reached only after the two passthrough early-returns.
+        this.clearCall(exec, decision.reason, source, source);
         return undefined;
     }
     /**
@@ -474,6 +591,7 @@ export class PermGateRuntime {
                 this.audit.append(makeEntry({ callId: randomId(), tool: exec.name, outcome: 'allow', source: 'classifier', reason, at: Date.now() }));
                 this.recordEvent(exec, 'learned', reason, { risk: 'neutral', verdict: 'learned-sediment', category: 'neutral' });
                 this.untrackAsk(exec); // auto-allowed: no human answer is coming
+                this.clearCall(exec, reason, 'learned-sediment', 'classifier');
                 return undefined;
             }
         }
@@ -506,6 +624,7 @@ export class PermGateRuntime {
             this.audit.append(makeEntry({ callId: randomId(), tool: exec.name, outcome: 'allow', source: 'classifier', reason, at: Date.now() }));
             this.recordEvent(exec, 'auto', reason, { risk: 'safe', verdict: 'llm-safe' });
             this.untrackAsk(exec); // auto-allowed: no human answer is coming
+            this.clearCall(exec, reason, 'llm-safe', 'classifier');
             return undefined;
         }
         if (risk.kind === 'risky') {
@@ -527,6 +646,7 @@ export class PermGateRuntime {
                 this.audit.append(makeEntry({ callId: randomId(), tool: exec.name, outcome: 'allow', source: 'classifier', reason, at: Date.now() }));
                 this.recordEvent(exec, 'auto', reason, { risk: risk.category, verdict: 'llm-learned', category: risk.category });
                 this.untrackAsk(exec); // auto-allowed: no human answer is coming
+                this.clearCall(exec, reason, 'llm-learned', 'classifier');
                 return undefined;
             }
             if (learning.enabled) {
@@ -575,6 +695,9 @@ export class PermGateRuntime {
      * approved it and it actually executed — one confirmation.
      */
     settleExecution(exec, result) {
+        // The call is over: no further in-call approval can arrive for it, so the
+        // clearance must not linger.
+        this.forgetCleared(typeof exec.callId === 'string' ? exec.callId : '');
         this.settleAskFromResult(exec, result);
         const callKey = canonicalizeCall(exec.name, exec.arguments ?? {});
         const candidate = this.pending.get(callKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-perm-gate",
-  "version": "0.2.1-beta.3",
+  "version": "0.2.1-beta.4",
   "description": "DSH permission-gate: 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": [
@@ -58,7 +58,7 @@
   },
   "engines": {
     "node": ">=20",
-    "dsh": ">=0.1.0-rc.7 <0.2.0-0"
+    "dsh": ">=0.1.2-alpha.1 <0.2.0-0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"
@@ -69,10 +69,10 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.2",
     "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
     "@types/react": "~18.3.1",
@@ -87,10 +87,19 @@
     "build": "tsc -p tsconfig.build.json && tsdown",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.client.json --noEmit",
-    "lint": "eslint src test tsdown.config.ts eslint.config.mjs",
-    "test": "vitest run"
+    "lint": "eslint src test scripts tsdown.config.ts eslint.config.mjs",
+    "test": "vitest run",
+    "verify:line": "node scripts/verify-line.mjs new",
+    "verify:lines": "node scripts/verify-line.mjs both",
+    "release:latest": "npm publish --tag latest",
+    "release:legacy": "npm publish --tag legacy"
   },
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drscrewdriver/dsh-perm-gate.git"
+  },
+  "homepage": "https://github.com/drscrewdriver/dsh-perm-gate#readme",
   "keywords": [
     "dsh",
     "dsh-plugin",