dsh-dlp 0.6.0 → 0.7.0

package/README.md

@@ -26,7 +26,9 @@ built as an out-of-repo plugin.
    credential.
 7. **Asks before a call switches off its own confirmation** — `non_interactive: true`,
    `approval_mode: auto`, an `apply` whose approval is still pending. Both `ask` tiers are
-   prompts rather than controls: they live at `tools/pre-execute` and can be neutralised.
+   prompts rather than controls: they live at `tools/pre-execute`, they can be neutralised, and
+   they abstain wherever the approval seam prompts nobody — which includes every install under
+   `DSH_PERMISSION_MODE=danger-full-access` and a stock headless install under any mode.
 8. **Writes an audit record for every decision.** A redaction or denial names the rule, its
    version, the offsets and a keyed hash; the three kinds with no matched region to describe —
    an ask, a rewritten call, a neutralised image — carry a rule id, the changed field names or

package/lib/approval-reach.js

@@ -0,0 +1,144 @@
+/**
+ * Whether an `ask` this plugin returns can still reach a human.
+ *
+ * The `ask` tier is documented as a prompt and never a block: its rules have a
+ * real false-positive rate, so a developer who is asked about `CLAUDE.md` or
+ * `.github/workflows/**` says yes and carries on. The tool registry resolves an
+ * `ask` through `ctx.get('approval')`, and three states of that seam turn the
+ * prompt into a denial nobody ever saw:
+ *
+ * 1. **No service composed.** `ToolRegistry.serviceAsk` keeps the historical
+ *    degrade to `deny` when `ctx.get('approval')` is `undefined`.
+ * 2. **The policy in force is `'never'`.** `ApprovalService.decide` resolves
+ *    `'rejected'` before any dispatch — its own JSDoc calls this "never prompt
+ *    anyone". The shipped `dsh-base` bundle selects it for every install under
+ *    `DSH_PERMISSION_MODE=danger-full-access`, which is the unattended posture.
+ * 3. **Nothing composed on `approval/request`.** The waterfall falls through to
+ *    the fail-closed `'unavailable'`, which the registry maps to `deny`. The
+ *    shipped `dsh-headless` bundle composes no answerer, so this is the state
+ *    of a stock headless install under every other permission mode.
+ *
+ * In all three the call is stopped with no human involved, which is exactly
+ * what this tier was designed not to do. Each is decided here so the caller can
+ * abstain instead — the same thing it already did for (1) alone.
+ *
+ * **Every check reports "reachable" when it cannot tell.** Abstaining removes a
+ * prompt, so an unreadable service, a missing session, or a `ctx.get` that
+ * returned something other than the service read here all keep the ask. Only a
+ * positive reading of one of the three states above abstains.
+ * @module dsh-dlp/approval-reach
+ */
+/** The event `ApprovalService.decide` dispatches its answerer waterfall on. */
+const APPROVAL_REQUEST = 'approval/request';
+/**
+ * Whether every ask for this session resolves without prompting anyone.
+ *
+ * `'never'` is the only policy whose outcome is knowable without asking, and
+ * the service decides it before dispatch, so no composed answerer can change
+ * it. Anything else — including a value this build does not recognise — leaves
+ * the answerers to decide and is therefore not a positive reading.
+ * @param approval - whatever `ctx.get('approval')` returned.
+ * @param session - the calling agent's session, or `undefined` when the call has no agent.
+ * @returns `true` only when the policy in force was read and is `'never'`.
+ */
+function policyIsNever(approval, session) {
+    // Without a session there is no override to fold, and the configured default
+    // alone cannot tell a session that never switched from one that switched to
+    // 'ask' — so an agent-less call keeps its prompt.
+    if (session === undefined)
+        return false;
+    const service = approval;
+    let policy;
+    try {
+        policy = service.overrideOf === undefined ? undefined : service.overrideOf(session) ?? service.config?.policy;
+    }
+    catch {
+        // Only a service without the members ApprovalSurface describes reaches
+        // here. It answers nothing about whether a human can be asked, and
+        // this runs inside a live tool call: a diagnostic read must not fail it.
+        return false;
+    }
+    return policy === 'never';
+}
+/**
+ * How many listeners are composed on the answerer waterfall.
+ *
+ * The count is read across the whole context tree, before the scope filter
+ * `ApprovalService.decide` applies. That over-counts — an agent-scoped answerer
+ * belonging to a different agent is included — and over-counting is the safe
+ * direction here, because only a count of zero abstains and zero listeners
+ * cannot be filtered into some.
+ *
+ * `EventsService._hooks` is a declared public field of the exported class, so a
+ * Cordis that stops carrying it fails `typecheck` and `build` in this package
+ * rather than being misread at a user's install; `@deepseek-ai/cordis` is
+ * pinned to one exact version (ADR §19) for the same reason.
+ * @param ctx - the plugin's context; every context in one tree shares the bus.
+ * @returns the number of composed answerers.
+ */
+function composedAnswerers(ctx) {
+    return ctx.events._hooks[APPROVAL_REQUEST]?.length ?? 0;
+}
+/**
+ * Decide whether an ask would reach a human, at the moment of the decision.
+ *
+ * Evaluated per call rather than at mount: a session switches policy mid-run
+ * through `approval/policy`, the override is per session, and an answerer can
+ * be composed or disposed while the harness runs. A mount-time answer would be
+ * a cached guess at all three.
+ * @param ctx - the plugin's context, for the service and the event bus.
+ * @param session - the calling agent's session, or `undefined` when the call has no agent.
+ * @returns whether to ask, or which state stopped the ask from reaching anyone.
+ */
+export function askReach(ctx, session) {
+    const approval = ctx.get('approval');
+    if (approval === undefined)
+        return { kind: 'unreachable', cause: 'no-service' };
+    // Policy first, matching the service's own order: it decides 'never' before
+    // dispatching, so that is the state an operator sees reported.
+    if (policyIsNever(approval, session))
+        return { kind: 'unreachable', cause: 'policy-never' };
+    if (composedAnswerers(ctx) === 0)
+        return { kind: 'unreachable', cause: 'no-answerer' };
+    return { kind: 'reachable' };
+}
+/** What abstaining does, said once and identically for all three states. */
+const CONSEQUENCE = 'This tier abstains rather than becoming the silent hard deny it was designed not to be: a'
+    + ' write to a behaviour-changing config path, and a call that switches its own confirmation off, are allowed'
+    + ' through with no prompt, and each one is recorded in the audit sink as "pre-execute-ask-abstained". The'
+    + ' guard floor is unaffected. Set configWriteAsk: false and approvalSuppressionAsk: false to turn this tier'
+    + ' off entirely.';
+/**
+ * What to tell the operator when the ask tier has nowhere to ask.
+ *
+ * Each line names the state, what to change to get the prompt back, and the
+ * consequence. Reported on `process.stderr` as well as `ctx.logger` for the
+ * reason ADR §7 records: the logger's default exporter is an in-memory ring
+ * buffer and no shipped bundle mounts a console exporter.
+ * @param cause - the state {@link askReach} read.
+ * @returns the whole line to report.
+ */
+export function approvalSeamNotice(cause) {
+    const prefix = 'dsh-dlp: the ask tier (configWriteAsk, approvalSuppressionAsk) is enabled, but';
+    switch (cause) {
+        case 'no-service':
+            return `${prefix} no approval service is mounted, so the tool registry would resolve an ask as a denial`
+                + ' with nothing shown to anyone. Composing an approval service and an answerer puts the prompt back.'
+                + ` ${CONSEQUENCE}`;
+        case 'policy-never':
+            return `${prefix} the approval policy in force is "never", which resolves every ask as rejected without`
+                + ' prompting anyone. DSH_PERMISSION_MODE=danger-full-access selects that policy in the shipped dsh-base'
+                + ' bundle; run under another permission mode, or set the approval row\'s policy to "ask", for these'
+                + ` calls to be asked about. ${CONSEQUENCE}`;
+        case 'no-answerer':
+            return `${prefix} nothing is composed on the approval/request waterfall, which fails every ask closed as`
+                + ' unavailable and denies the call with nothing shown to anyone. The shipped dsh-headless bundle'
+                + ' composes no answerer; a surface that answers approvals, such as the Host API proxy or the ACP'
+                + ` bridge, puts the prompt back. ${CONSEQUENCE}`;
+        /* v8 ignore next 4 -- unreachable while `AskUnreachable` stays closed; the arm exists so adding a variant fails the build. */
+        default: {
+            const unhandled = cause;
+            throw new TypeError(`dsh-dlp: unhandled ask-tier state ${JSON.stringify(unhandled)}`);
+        }
+    }
+}

package/lib/index.js

@@ -13,7 +13,7 @@
  *    config paths and for calls carrying an argument that switches their own
  *    confirmation off. Deliberately here rather than on the floor: its rules
  *    have a real false-positive rate and the floor cannot ask. Neutralizable,
- *    and it abstains entirely when no approval service is mounted.
+ *    and it abstains entirely wherever the approval seam cannot prompt anyone.
  * 3. `tools/post-execute` — result redaction, applied before the `tool/result`
  *    session event is appended, so the durable log records the redacted copy;
  *    a result that cannot be cleaned is withheld rather than accepted.
@@ -43,6 +43,7 @@ import { neutralizeImageStream } from "./images.js";
 import { ExecutionSnapshots, mutationReason } from "./mutation.js";
 import { evaluateConfigWrite } from "./config-writes.js";
 import { evaluateApprovalSuppression } from "./approvals.js";
+import { approvalSeamNotice, askReach } from "./approval-reach.js";
 import { breadthTierDenial, evaluateBreadthTier, redactDecision } from "./results.js";
 import { redactRecord, telemetrySeamNotice } from "./telemetry.js";
 import { AuditSink, CallCorrelator, newDecisionId, RECORD_VERSION } from "./sink.js";
@@ -238,25 +239,20 @@ export function apply(ctx, config) {
         return verdict.reason;
     }), 'dsh-dlp guard floor');
     /**
-     * Report once that the `ask` tier has nowhere to ask.
+     * Report once per state that the `ask` tier has nowhere to ask.
      *
-     * The registry resolves an `ask` through `ctx.get('approval')` and keeps the
-     * historical degrade to *deny* when no service is composed. This tier exists
-     * because its rules are too false-positive-prone for a deny, so under a
-     * deployment with no approval channel it abstains instead of becoming the
-     * silent hard deny it was designed not to be. Evaluated at decision time
-     * rather than at mount, because by then the harness is running and an absent
-     * service is conclusive rather than a load order.
+     * Latched per state rather than once overall: the three states have
+     * different fixes, a session can move between them mid-run by switching its
+     * approval policy, and a single latch would leave the first one reported
+     * standing for a different one afterwards. `approval-reach.ts` records why
+     * each is a state in which an ask reaches nobody.
      */
-    let approvalSeamReported = false;
-    const discloseApprovalSeam = () => {
-        if (approvalSeamReported)
+    const approvalSeamReported = new Set();
+    const discloseApprovalSeam = (cause) => {
+        if (approvalSeamReported.has(cause))
             return;
-        approvalSeamReported = true;
-        notice(ctx, 'dsh-dlp: the ask tier (configWriteAsk, approvalSuppressionAsk) is enabled, but no approval service'
-            + ' is mounted, so an ask would degrade to a denial. This tier abstains instead: a write to a'
-            + ' behaviour-changing config path, and a call that switches its own confirmation off, are allowed through'
-            + ' with no prompt. The guard floor is unaffected.');
+        approvalSeamReported.add(cause);
+        notice(ctx, approvalSeamNotice(cause));
     };
     if (policy.configWriteAsk || policy.approvalSuppressionAsk) {
         // Registered ahead of the breadth tier, so a call that is both a config
@@ -280,8 +276,25 @@ export function apply(ctx, config) {
             // and would file the decision as an ask rather than as a guard denial.
             if (safeEvaluateGuard(exec, policy, hasher) !== undefined)
                 return decision;
-            if (ctx.get('approval') === undefined) {
-                discloseApprovalSeam();
+            // Asked at decision time, never at mount: the session's policy is a fold
+            // over its own log and can change mid-run, and an answerer can be
+            // composed or disposed while the harness runs.
+            const reach = askReach(ctx, exec.agent?.session);
+            if (reach.kind === 'unreachable') {
+                discloseApprovalSeam(reach.cause);
+                // An abstention allowed a call this tier would have asked about, so it
+                // is recorded rather than left silent. Its own kind, not a flag on
+                // `pre-execute-ask`: `dsh-dlp report` counts by kind, and an ask that
+                // reached nobody must not be counted as a prompt that happened.
+                sink.write({
+                    v: RECORD_VERSION,
+                    time: new Date().toISOString(),
+                    kind: 'pre-execute-ask-abstained',
+                    decisionId: newDecisionId(),
+                    ...identity(exec),
+                    ruleId: finding.rule.id,
+                    askUnreachable: reach.cause,
+                });
                 return decision;
             }
             sink.write({

package/lib/types/approval-reach.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Whether an `ask` this plugin returns can still reach a human.
+ *
+ * The `ask` tier is documented as a prompt and never a block: its rules have a
+ * real false-positive rate, so a developer who is asked about `CLAUDE.md` or
+ * `.github/workflows/**` says yes and carries on. The tool registry resolves an
+ * `ask` through `ctx.get('approval')`, and three states of that seam turn the
+ * prompt into a denial nobody ever saw:
+ *
+ * 1. **No service composed.** `ToolRegistry.serviceAsk` keeps the historical
+ *    degrade to `deny` when `ctx.get('approval')` is `undefined`.
+ * 2. **The policy in force is `'never'`.** `ApprovalService.decide` resolves
+ *    `'rejected'` before any dispatch — its own JSDoc calls this "never prompt
+ *    anyone". The shipped `dsh-base` bundle selects it for every install under
+ *    `DSH_PERMISSION_MODE=danger-full-access`, which is the unattended posture.
+ * 3. **Nothing composed on `approval/request`.** The waterfall falls through to
+ *    the fail-closed `'unavailable'`, which the registry maps to `deny`. The
+ *    shipped `dsh-headless` bundle composes no answerer, so this is the state
+ *    of a stock headless install under every other permission mode.
+ *
+ * In all three the call is stopped with no human involved, which is exactly
+ * what this tier was designed not to do. Each is decided here so the caller can
+ * abstain instead — the same thing it already did for (1) alone.
+ *
+ * **Every check reports "reachable" when it cannot tell.** Abstaining removes a
+ * prompt, so an unreadable service, a missing session, or a `ctx.get` that
+ * returned something other than the service read here all keep the ask. Only a
+ * positive reading of one of the three states above abstains.
+ * @module dsh-dlp/approval-reach
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+/** Which of the three states stopped an ask from reaching a human. */
+export type AskUnreachable = 
+/** Nothing is composed on `ctx.approval`. */
+'no-service'
+/** The policy in force for this session is `'never'`. */
+ | 'policy-never'
+/** Nothing is composed on the `approval/request` waterfall. */
+ | 'no-answerer';
+/** Whether an ask can reach a human, and when it cannot, which state stopped it. */
+export type AskReach = {
+    readonly kind: 'reachable';
+} | {
+    readonly kind: 'unreachable';
+    readonly cause: AskUnreachable;
+};
+/**
+ * Decide whether an ask would reach a human, at the moment of the decision.
+ *
+ * Evaluated per call rather than at mount: a session switches policy mid-run
+ * through `approval/policy`, the override is per session, and an answerer can
+ * be composed or disposed while the harness runs. A mount-time answer would be
+ * a cached guess at all three.
+ * @param ctx - the plugin's context, for the service and the event bus.
+ * @param session - the calling agent's session, or `undefined` when the call has no agent.
+ * @returns whether to ask, or which state stopped the ask from reaching anyone.
+ */
+export declare function askReach(ctx: Context, session: Session | undefined): AskReach;
+/**
+ * What to tell the operator when the ask tier has nowhere to ask.
+ *
+ * Each line names the state, what to change to get the prompt back, and the
+ * consequence. Reported on `process.stderr` as well as `ctx.logger` for the
+ * reason ADR §7 records: the logger's default exporter is an in-memory ring
+ * buffer and no shipped bundle mounts a console exporter.
+ * @param cause - the state {@link askReach} read.
+ * @returns the whole line to report.
+ */
+export declare function approvalSeamNotice(cause: AskUnreachable): string;
+//# sourceMappingURL=approval-reach.d.ts.map

package/lib/types/index.d.ts

@@ -13,7 +13,7 @@
  *    config paths and for calls carrying an argument that switches their own
  *    confirmation off. Deliberately here rather than on the floor: its rules
  *    have a real false-positive rate and the floor cannot ask. Neutralizable,
- *    and it abstains entirely when no approval service is mounted.
+ *    and it abstains entirely wherever the approval seam cannot prompt anyone.
  * 3. `tools/post-execute` — result redaction, applied before the `tool/result`
  *    session event is appended, so the durable log records the redacted copy;
  *    a result that cannot be cleaned is withheld rather than accepted.

package/lib/types/sink.d.ts

@@ -14,6 +14,7 @@
  * `callId`, and a producer-minted `decisionId`.
  * @module dsh-dlp/sink
  */
+import type { AskUnreachable } from './approval-reach.ts';
 import type { RedactedSpan } from './redaction.ts';
 declare const decisionIdBrand: unique symbol;
 /** Producer-minted id correlating one decision across records. */
@@ -28,7 +29,7 @@ export declare function newDecisionId(): DecisionId;
 /** Payload version carried inside every record this plugin writes. */
 export declare const RECORD_VERSION = 1;
 /** What produced one audit record. */
-export type AuditKind = 'guard-deny' | 'pre-execute-deny' | 'pre-execute-ask' | 'execution-mutation' | 'result-redaction' | 'telemetry-redaction' | 'assistant-image-neutralized' | 'audit-failure';
+export type AuditKind = 'guard-deny' | 'pre-execute-deny' | 'pre-execute-ask' | 'pre-execute-ask-abstained' | 'execution-mutation' | 'result-redaction' | 'telemetry-redaction' | 'assistant-image-neutralized' | 'audit-failure';
 /** One durable record. Never carries matched secret text. */
 export interface AuditRecord {
     readonly v: number;
@@ -66,6 +67,13 @@ export interface AuditRecord {
      * behaviour-changing file, not that any part of it matched a secret.
      */
     readonly ruleId?: string;
+    /**
+     * Which state left the ask tier with nowhere to ask, for a
+     * `pre-execute-ask-abstained`. An abstention allowed a call the tier would
+     * otherwise have asked about, so the state that caused it is the field an
+     * operator needs to change to get the prompt back.
+     */
+    readonly askUnreachable?: AskUnreachable;
     /** Telemetry record channel, for `telemetry-redaction`. */
     readonly channel?: string;
     /** Fields another plugin rewrote after the call was logged, for `execution-mutation`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-dlp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Data-loss-prevention plugin for DeepSeek Harness: a non-configurable tool guard floor, tool-result redaction, and fail-closed telemetry redaction",
   "license": "MIT",
   "author": "Ivan Tyshchenko <nsof@protonmail.com>",