@argszero/cordis-plugin-sandbox-grant-advisor 0.1.0 → 0.2.0

package/lib/state.js

@@ -6,21 +6,52 @@
  * failing call carries `exec.agent`, one agent owns one session, and a WeakMap
  * keyed by the agent object lets a finished session's state be collected.
  *
- * Two counters, two meanings — keeping them apart is what stops the plugin from
- * feeding on itself:
+ * ## One record per family
  *
- * - `observations` counts *provisioning failures of this environment*, i.e.
+ * This plugin now recognizes two unrelated environment failures — a workspace
+ * that cannot be provisioned (`acl-provisioning`) and a persistent shell that
+ * cannot start (`pty-startup`). They are different diagnoses with different
+ * remedies, so their bookkeeping is kept apart under one agent
+ * ({@link AgentState.families}): an agent that hits both is told about both,
+ * and an agent that has already been told about one is still told about the
+ * other. Sharing one "already advised" flag would silently swallow the second
+ * diagnosis, which is the failure mode this split exists to prevent.
+ *
+ * Three counters, three meanings — keeping them apart is what stops the plugin
+ * from feeding on itself:
+ *
+ * - `observations` counts *failures of this environment in this family*, i.e.
  *   tool results the environment itself produced. A call this plugin denied is
- *   not one of them, even though its denial text quotes the Win32 line.
+ *   not one of them, even though its denial text quotes the producer's line.
  * - `failingKeys` holds the call identities (tool + canonical arguments) that
  *   have already failed this way. The fail-fast half may only refuse a call it
  *   has *watched fail* — never a call it merely recognizes as similar.
- *
- * `denials` is spent per *episode*: it is re-armed when a watched call finally
- * succeeds (see `observeSuccess`), not carried for the whole session.
+ * - `denials` is spent per *episode*: it is re-armed when a watched call finally
+ *   succeeds (see `observeSuccess`), not carried for the whole session.
  *
  * @module
  */
+/** The state of an agent this plugin has never observed. */
+export function emptyState() {
+    return { families: {}, withheld: false };
+}
+/** The record for one family, if this agent has one. */
+function familyOf(state, family) {
+    return state?.families[family];
+}
+/**
+ * Replace one family's record, leaving the others (and the withheld flag) alone.
+ * @param state - the agent's current state, or undefined on first sight.
+ * @param family - the family being updated.
+ * @param record - the family's new record.
+ * @returns the updated state.
+ */
+function withFamily(state, family, record) {
+    return {
+        families: { ...state?.families, [family]: record },
+        withheld: state?.withheld ?? false,
+    };
+}
 /**
  * Canonicalize a parsed argument value into a stable string.
  *
@@ -63,46 +94,91 @@ export function callKey(name, args) {
     return `${name}(${canonicalize(args)})`;
 }
 /**
- * Record one observed provisioning failure.
+ * Record one observed failure in one family.
  * @param state - the agent's current state, or undefined on first sight.
+ * @param family - the family the failure belongs to.
  * @param failure - the recognized failure.
  * @param key - the identity of the call that failed.
  * @returns the updated state.
  */
-export function observe(state, failure, key) {
-    const failingKeys = new Set(state?.failingKeys ?? []);
+export function observe(state, family, failure, key) {
+    const previous = familyOf(state, family);
+    const failingKeys = new Set(previous?.failingKeys ?? []);
     failingKeys.add(key);
-    return {
-        observations: (state?.observations ?? 0) + 1,
+    return withFamily(state, family, {
+        observations: (previous?.observations ?? 0) + 1,
         last: failure,
         failingKeys,
-        denials: state?.denials ?? 0,
-        advised: state?.advised ?? false,
+        denials: previous?.denials ?? 0,
+        advised: previous?.advised ?? false,
+    });
+}
+/**
+ * Whether this family's durable advisory has already been delivered.
+ * @param state - the agent's current state, or undefined.
+ * @param family - the family in question.
+ * @returns true when the advice is already in the session.
+ */
+export function advisedOf(state, family) {
+    return familyOf(state, family)?.advised ?? false;
+}
+/**
+ * Mark one family's durable advisory as delivered.
+ * @param state - the agent's current state.
+ * @param family - the family that was advised.
+ * @returns the updated state.
+ */
+export function recordAdvice(state, family) {
+    const previous = familyOf(state, family);
+    if (previous === undefined)
+        return state;
+    return withFamily(state, family, { ...previous, advised: true });
+}
+/**
+ * Record that a recognized failure was withheld from the model.
+ * @param state - the agent's current state, or undefined on first sight.
+ * @returns the updated state.
+ */
+export function recordWithheld(state) {
+    return {
+        families: { ...state?.families },
+        withheld: true,
     };
 }
 /**
  * Record that a call carrying the same identity as a previously failing one
- * succeeded. The environment worked at least once for that call, so the entry
- * stops justifying a denial — and is dropped rather than kept, so a later
- * failure re-earns it.
+ * succeeded — in **every** family that was watching that identity.
+ *
+ * The environment worked at least once for that call, so the entry stops
+ * justifying a denial — and is dropped rather than kept, so a later failure
+ * re-earns it. A success is evidence about the environment, not about one
+ * diagnosis: the same call cannot have started working for one family's reason
+ * and not the other's.
  *
- * The denial budget is re-armed at the same moment, and only then. Measured
- * consequence: without it the budget is per agent for the whole session, which
- * makes the entry above unobservable — past `maxDenials` this plugin refuses
- * nothing ever again, so clearing the key would change no decision. With it the
- * bound reads as "at most `maxDenials` refusals per episode of brokenness": an
- * environment that breaks, is repaired and breaks again may be refused again,
- * while a session can always make progress by spending the budget.
+ * Each affected family's denial budget is re-armed at the same moment, and only
+ * then. Measured consequence: without it the budget is per agent for the whole
+ * session, which makes the entry above unobservable — past `maxDenials` this
+ * plugin refuses nothing ever again, so clearing the key would change no
+ * decision. With it, the bound reads as "at most `maxDenials` refusals per
+ * episode of brokenness": an environment that breaks, is repaired and breaks
+ * again may be refused again, while a session can always make progress by
+ * spending the budget.
  * @param state - the agent's current state.
  * @param key - the identity of the call that just succeeded.
- * @returns the updated state, unchanged when the key was not failing.
+ * @returns the updated state, unchanged when no family was watching the key.
  */
 export function observeSuccess(state, key) {
-    if (!state.failingKeys.has(key))
+    const watched = Object.entries(state.families)
+        .filter(([, record]) => record.failingKeys.has(key));
+    if (watched.length === 0)
         return state;
-    const failingKeys = new Set(state.failingKeys);
-    failingKeys.delete(key);
-    return { ...state, failingKeys, denials: 0 };
+    let next = state;
+    for (const [family, record] of watched) {
+        const failingKeys = new Set(record.failingKeys);
+        failingKeys.delete(key);
+        next = withFamily(next, family, { ...record, failingKeys, denials: 0 });
+    }
+    return next;
 }
 /**
  * Whether a call may be refused before dispatch.
@@ -112,34 +188,35 @@ export function observeSuccess(state, key) {
  * fail. The second condition is what keeps the fail-fast half from blocking a
  * workaround: a different command, or the same command under a different policy
  * after the user changed configuration, has no key here.
+ *
+ * Only the `acl-provisioning` family ever reaches this question; see the
+ * `denialText` doc for why the blocking half does not extend to `pty-startup`.
  * @param state - the agent's current state, or undefined.
+ * @param family - the family whose threshold is being asked about.
  * @param key - the identity of the call about to dispatch.
  * @param enforceAfter - the configured threshold; 0 disables the half entirely.
  * @param maxDenials - the configured denial budget.
  * @returns whether to deny.
  */
-export function shouldDeny(state, key, enforceAfter, maxDenials) {
-    if (enforceAfter === 0 || state === undefined)
+export function shouldDeny(state, family, key, enforceAfter, maxDenials) {
+    const record = familyOf(state, family);
+    if (enforceAfter === 0 || record === undefined)
         return false;
-    if (state.observations < enforceAfter)
+    if (record.observations < enforceAfter)
         return false;
-    if (state.denials >= maxDenials)
+    if (record.denials >= maxDenials)
         return false;
-    return state.failingKeys.has(key);
+    return record.failingKeys.has(key);
 }
 /**
  * Spend one denial.
  * @param state - the agent's current state.
+ * @param family - the family being denied.
  * @returns the updated state.
  */
-export function recordDenial(state) {
-    return { ...state, denials: state.denials + 1 };
-}
-/**
- * Mark the durable advisory as delivered.
- * @param state - the agent's current state.
- * @returns the updated state.
- */
-export function recordAdvice(state) {
-    return { ...state, advised: true };
+export function recordDenial(state, family) {
+    const previous = familyOf(state, family);
+    if (previous === undefined)
+        return state;
+    return withFamily(state, family, { ...previous, denials: previous.denials + 1 });
 }

package/lib/types/advice.d.ts

@@ -1,38 +1,100 @@
 /**
- * What the model — and through it the user — is told about a provisioning
- * failure, and what is deliberately withheld.
+ * What the model — and through it the user — is told about a recognized
+ * environment failure, and what is deliberately withheld.
  *
  * The text is assembled here as pure functions so every sentence can be pinned
- * by a test. Two properties matter more than the wording:
+ * by a test, one family at a time. The two families are shaped by the same two
+ * questions, and they answer them differently:
  *
- * - **It names the right the caller is missing.** The reported failures are
- *   `ERROR_ACCESS_DENIED` from a *merged* DACL + SACL write. The missing right
- *   is `WRITE_OWNER` on the directory — an object right the caller can grant
- *   itself with `icacls`, unelevated. It is **not** `SeSecurityPrivilege`, the
- *   token privilege the reports naturally reach for; `whoami /priv` cannot show
- *   the difference, and elevation is the wrong lever.
- * - **It gives a discriminator, not just a remedy.** Applying a fix without
- *   confirming the cause teaches nothing when the fix does not work. The
- *   one-line check (`icacls <dir>`, looking for an ACE that names the caller's
- *   own SID and grants `(F)`) separates "Modify-only directory" from "the
- *   documented prerequisite is wrong", which is the open question upstream.
+ * - **The ACL failure** (`acl-provisioning`) *is* fixable by the caller, so its
+ *   advice names the right the caller is missing and gives the command.
+ *   The reported failures are `ERROR_ACCESS_DENIED` from a *merged* DACL + SACL
+ *   write; the missing right is `WRITE_OWNER` on the directory — an object right
+ *   the caller can grant itself with `icacls`, unelevated. It is **not**
+ *   `SeSecurityPrivilege`, the token privilege the reports naturally reach for;
+ *   `whoami /priv` cannot show the difference, and elevation is the wrong lever.
+ * - **The persistent-shell failure** (`pty-startup`) is *not* fixable by the
+ *   caller — least of all by the model, which has no shell to run anything in.
+ *   So its advice says so and stops: the remedy is a user-side preset choice,
+ *   and the model's instruction is to stop retrying and use its file tools.
+ *   Handing the model a command here would be advice to run something that
+ *   cannot run, and naming a one-shot shell tool would be advice to call a tool
+ *   the failing composition does not mount.
+ *
+ * Both give a **discriminator, not just a remedy**: applying a fix without
+ * confirming the cause teaches nothing when the fix does not work. For the ACL
+ * family that is `icacls <dir>`, looking for an ACE that names the caller's own
+ * SID and grants `(F)` — which separates "Modify-only directory" from "the
+ * documented prerequisite is wrong", the open question upstream. For the PTY
+ * family it is the **effective sandbox mode**, which is why that advisory is
+ * only ever built with the mode the call actually ran under.
  *
  * @module
  */
-import type { ProvisioningFailure } from './signature.js';
-/** The upstream threads this advisory is a stopgap for. */
-export declare const DISCUSSIONS = "#7538 / #7622 / #7646";
+import type { ProvisioningFailure, RecognizedFailure } from './signature.js';
+import type { SandboxModeName } from './mode.js';
+/** The upstream threads the ACL advisory is a stopgap for. */
+export declare const ACL_DISCUSSIONS = "#7538 / #7622 / #7646";
+/** The upstream thread the persistent-shell advisory is a stopgap for. */
+export declare const PTY_DISCUSSIONS = "#7638";
 /** The documented prerequisite, quoted from the backend's README. */
 export declare const PREREQUISITE = "granted directories must be caller-owned and grant `WRITE_OWNER`";
+/**
+ * Where a user's own preset changes actually live.
+ *
+ * This is deliberately **not** the legacy `$DSH_HOME/.agent-presets/<id>/`
+ * directory: that shape predates declarative presets and **nothing reads it any
+ * more** (the registry "neither scans directories nor accepts preset paths").
+ * A preset is a `@deepseek-ai/dsh-agent-preset` row, and changing one means
+ * overriding or inserting that row in a patch layer, which is what this path
+ * names. Advising a folder the harness stopped reading would be the same defect
+ * this plugin exists to answer — a remedy that does not work, delivered
+ * confidently.
+ */
+export declare const PROFILE_PATCH = "$DSH_HOME/profiles/<profile>/cordis.patch.yml";
+/** The machine-wide patch layer, for a change that should hold in every profile. */
+export declare const GLOBAL_PATCH = "$DSH_HOME/cordis.patch.yml";
+/** The row id the shipped `minimal` preset is declared under. */
+export declare const MINIMAL_PRESET_ROW = "preset-minimal";
+/** The one-shot shell tool the `standard` preset mounts on Windows. */
+export declare const ONE_SHOT_SHELL = "@deepseek-ai/dsh-tool-pwsh";
+/** What the caller knows about the failing call, beyond the failure text. */
+export interface AdvisoryContext {
+    /** URL quoted in place of the discussions list; optional. */
+    readonly href?: string;
+    /** The tool whose call failed, quoted back so the advice is about that call. */
+    readonly tool?: string;
+    /**
+     * The sandbox mode the failing call ran under. Required by the
+     * `pty-startup` family — the whole diagnosis is the mode — and unused by the
+     * ACL family.
+     */
+    readonly mode?: SandboxModeName;
+}
 /**
  * Build the advisory attached to the failing tool result.
+ *
+ * The family decides everything: one function so a caller does not have to
+ * remember which family needs which fact, and so the mode requirement of the
+ * PTY family is enforced by construction rather than by convention.
  * @param failure - the recognized failure.
- * @param href - optional URL shown for the upstream thread.
- * @returns the user-role notice text, with the fix commands ready to paste.
+ * @param context - what the caller knows about the failing call.
+ * @returns the user-role notice text, with any remedy ready to paste.
+ * @throws when a PTY failure is advised without its resolved sandbox mode.
  */
-export declare function advisoryText(failure: ProvisioningFailure, href?: string): string;
+export declare function advisoryText(failure: RecognizedFailure, context?: AdvisoryContext): string;
 /**
  * Build the pre-dispatch denial for the optional fail-fast half.
+ *
+ * The blocking half is deliberately **ACL-only**, and this function's parameter
+ * type is where that is enforced. The PTY family gets an advisory and nothing
+ * else, for a reason that is about the remedy rather than about the failure:
+ * the ACL remedy is a command the user can run *while the session continues*,
+ * so refusing further identical calls cannot make the session unfinishable —
+ * spending the budget always lets the call through, and a repaired environment
+ * is discovered by exactly that. The PTY remedy is a preset swap, which happens
+ * between sessions; refusing calls could only pad a session that is already
+ * unable to do the thing being refused.
  * @param failure - the recognized failure.
  * @param observed - how many provisioning failures this agent has produced.
  * @param denial - this denial's 1-based ordinal.

package/lib/types/index.d.ts

@@ -1,23 +1,38 @@
 /**
- * `sandbox-grant-advisor`: turn a Windows ACL provisioning failure that has no
- * path forward into a diagnosis the model — and the user reading the
- * transcript — can act on.
+ * `sandbox-grant-advisor`: turn an environment failure that has no path forward
+ * into a diagnosis the model — and the user reading the transcript — can act on.
  *
- * Three reports of one signature (`#7538`, `#7622`, `#7646`) describe the same
- * shape: the host-side write grant for a sandboxed workspace cannot be applied,
- * every sandboxed command then fails identically **before it runs**, and the
- * error text is a bare Win32 line:
+ * ## The two failures it recognizes
+ *
+ * **Workspace provisioning (Windows ACL).** Three reports of one signature
+ * (`#7538`, `#7622`, `#7646`) describe the same shape: the host-side write grant
+ * for a sandboxed workspace cannot be applied, every sandboxed command then
+ * fails identically **before it runs**, and the error text is a bare Win32 line:
  *
  *   SetNamedSecurityInfoW failed (Win32 5): grantWrite(D:\ws)
  *
  * The grant is materialized lazily on the first confined call and nothing is
  * cached when it throws, so the failure repeats per command rather than once
  * (850 calls / 39 sessions in `#7622`; 52,588 output tokens with no output in
- * `#7538`). The `workspace-write` policy is simply unusable in such a
- * workspace, and the remedy the backend documents — the directory must grant
- * the caller `WRITE_OWNER` — never reaches the user, so sessions escape into
+ * `#7538`). The remedy the backend documents — the directory must grant the
+ * caller `WRITE_OWNER` — never reaches the user, so sessions escape into
  * `danger-full-access` or die on the model's output cap.
  *
+ * **Persistent shell startup (#7638).** With the `minimal` preset on Windows the
+ * only shell tool is a persistent PTY (`dsh-terminal-bash` +
+ * `dsh-tool-pwsh-persistent`), and under a *confining* sandbox mode every call
+ * fails instantly with
+ *
+ *   PTY shell exited during startup
+ *
+ * — the backend cannot create the pseudo-console inside the sandbox, so the
+ * child exits before its first prompt. Retrying never helps, the message points
+ * at no cause, and because `minimal` mounts no fallback shell tool the session
+ * has no command execution left at all. The reporter's own three-arm control
+ * makes the sandbox mode the discriminator: minimal × confining fails, minimal ×
+ * `danger-full-access` succeeds, `standard` (one-shot shell) × confining
+ * succeeds.
+ *
  * ## Where it acts, and why there
  *
  * One listener on the public `tools/post-execute` waterfall
@@ -28,44 +43,65 @@
  * to the model in the same step (`PostToolDecision`'s `additionalContexts`,
  * a durable user-role message).
  *
- * `ctx.sandbox.confine(argv, policy, signal)` sees the failure too, and cannot
- * do this: its signature carries no agent, so a wrapper could detect the
- * condition and never deliver a word about it to the session that is stuck.
+ * `ctx.sandbox.confine(argv, policy, signal)` sees the confinement failure too,
+ * and cannot do this: its signature carries no agent, so a wrapper could detect
+ * the condition and never deliver a word about it to the session that is stuck.
+ *
+ * The PTY family needs one fact the failure text does not carry — the effective
+ * sandbox mode — and takes it from `ctx.sandboxPolicy.resolve({ session })`:
+ * the same resolver the terminal layer calls before spawning, with the same
+ * session. See `src/mode.ts` for why that lookup is guarded rather than
+ * imported, and what happens when it cannot answer.
  *
  * ## What it does
  *
- * 1. **One durable advisory per agent.** On the first recognized provisioning
- *    failure, the failing tool result is enriched with a user-role notice that
- *    names the missing right (`WRITE_OWNER` on the directory, not
- *    `SeSecurityPrivilege`), gives the unelevated one-line `icacls` remedy, and
- *    gives the discriminator that separates a Modify-only directory from a
- *    wrong prerequisite. Attached through `additionalContexts`, so the model
- *    sees it beside the failure rather than only in a log the model never reads.
- * 2. **An optional bounded fail-fast.** With `enforceAfter` set, a call this
- *    plugin has *watched fail* this way is refused at `tools/pre-execute` once
- *    the environment has failed at least that many times. It is off by default:
- *    the useful signal here is the diagnosis, and a plugin that blocks command
- *    execution for a reason it merely recognizes is a risk, not a feature. See
- *    the README for why the blocking half is deliberately narrow.
+ * 1. **One durable advisory per agent, per family.** On the first recognized
+ *    failure of a family, the failing tool result is enriched with a user-role
+ *    notice. For the ACL family it names the missing right (`WRITE_OWNER` on the
+ *    directory, not `SeSecurityPrivilege`), gives the unelevated one-line
+ *    `icacls` remedy, and gives the discriminator that separates a Modify-only
+ *    directory from a wrong prerequisite. For the PTY family it names the
+ *    combination that fails (persistent PTY × a confining mode), states the
+ *    resolved mode, says plainly that no command can fix it, and hands the
+ *    user-side preset choice over. Both ride `additionalContexts`, so the model
+ *    sees the diagnosis beside the failure rather than only in a log it never
+ *    reads.
+ * 2. **A bounded fail-fast, ACL family only.** With `enforceAfter` set, a call
+ *    this plugin has *watched fail* this way is refused at `tools/pre-execute`
+ *    once the environment has failed at least that many times. It is off by
+ *    default: the useful signal here is the diagnosis, and a plugin that blocks
+ *    command execution for a reason it merely recognizes is a risk, not a
+ *    feature. See the README for why the blocking half is deliberately narrow
+ *    and why it does not cover the PTY family.
+ * 3. **A disclosure when it withholds.** The PTY advisory is only sent when the
+ *    resolved mode actually confines; if the mode is not confining, or cannot be
+ *    resolved at all, the failure is left exactly as it was **and the host log
+ *    says so once**. Silence alone would make "the sandbox is not the cause" and
+ *    "this plugin could not tell" indistinguishable from the outside.
  *
  * ## Honest boundaries
  *
  * - **The Windows path cannot be witnessed on macOS**, where this plugin was
  *   built and tested. What is tested is the decision layer: classification,
- *   once-per-agent delivery, the fail-fast budget, and the wiring to the real
- *   `ToolRuntime` — against synthetic results carrying the producer's exact
- *   error shape, with the format taken from
- *   `packages/subprocess/win32-process/src/errors.ts`.
+ *   once-per-agent-per-family delivery, the sandbox-mode gate and its
+ *   fail-closed behaviour, the fail-fast budget, and the wiring to the real
+ *   `ToolRuntime` — against synthetic results carrying the producers' exact
+ *   error shapes, with the formats taken from
+ *   `packages/subprocess/win32-process/src/errors.ts` and
+ *   `packages/terminal/terminal-bash/src/{index,session}.ts`.
  * - **It does not repair anything.** No ACL is written, no privilege is
- *   requested, nothing is elevated: the `icacls` line is the user's to run.
+ *   requested, nothing is elevated, no preset is installed and no mode is
+ *   changed: both remedies are the user's to apply.
  * - **It complements, rather than replaces, `repeat-guard-escalation`.** That
  *   guard keys on *call identity* (identical arguments retried); this one keys
  *   on the *environment signature*, which is how several different commands can
  *   share one cause. They can be mounted together.
- * - **The real fix is upstream**: the failure should name the outstanding
- *   condition at the site that knows it (`grantWrite` computes
+ * - **The real fix is upstream**, in both families: the ACL failure should name
+ *   the outstanding condition at the site that knows it (`grantWrite` computes
  *   `hasExactGrant`/`hasExactDeny`/`hasExactLabel` and discards which was
- *   false). This plugin is the stopgap.
+ *   false), and the PTY startup path should either report "this sandbox mode is
+ *   incompatible with the PTY backend" or fall back to a one-shot shell. This
+ *   plugin is the stopgap.
  *
  * @module @argszero/cordis-plugin-sandbox-grant-advisor
  */
@@ -87,12 +123,21 @@ export declare const SOURCE_KIND = "sandbox-grant-advisor";
 export declare const DEFAULT_ENFORCE_AFTER = 0;
 /** Default denial budget once the blocking half is enabled. */
 export declare const DEFAULT_MAX_DENIALS = 2;
+/**
+ * The family the optional blocking half applies to.
+ *
+ * The ACL remedy is a command the user can run while the session continues; the
+ * PTY remedy is a preset swap between sessions. Refusing calls is only useful
+ * in the first case — see `denialText` in `src/advice.ts`.
+ */
+export declare const ENFORCED_FAMILY = "acl-provisioning";
 /** Configures what is watched and whether the blocking half runs. */
 export interface Config {
     /**
-     * Provisioning failures after which an identical, already-failing call is
+     * ACL provisioning failures after which an identical, already-failing call is
      * denied before dispatch. `0` (the default) disables the half entirely; the
-     * advisory half is unaffected and always on.
+     * advisory half is unaffected and always on. The blocking half does not apply
+     * to the persistent-shell family.
      */
     enforceAfter?: number;
     /**

package/lib/types/mode.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Which sandbox mode a call ran under, and whether that mode confines.
+ *
+ * The persistent-shell diagnosis is only true under a **confining** mode. The
+ * terminal backend hands the shell argv straight through when the resolved mode
+ * is `danger-full-access` and confines it otherwise
+ * (`packages/terminal/terminal-bash/src/index.ts`:
+ * `if (policy.mode === 'danger-full-access') return argv`), so the same
+ * `PTY shell exited during startup` under `danger-full-access` is a different
+ * story — a broken or missing shell — and this plugin must stay silent about it
+ * rather than assert a sandbox cause it cannot support. The report that frames
+ * this family (#7638) says the same thing from the other side: its author's
+ * three-arm control shows the mode is the discriminator (minimal × confining
+ * fails, minimal × `danger-full-access` succeeds, standard × confining
+ * succeeds).
+ *
+ * The answer is taken from `ctx.sandboxPolicy.resolve({ session })` — the same
+ * resolver the terminal layer itself calls before spawning, with the same
+ * session — so what is quoted in the advisory is the policy that actually
+ * governed the failing call, not a guess reconstructed from configuration.
+ *
+ * ## Why this is a guarded lookup instead of an import
+ *
+ * `@deepseek-ai/dsh-sandbox-policy` is **optional** in this plugin's world: a
+ * composition may simply not mount the service, and this plugin must degrade to
+ * silence rather than fail to load. Two consequences shape this module:
+ *
+ * - A declared peer dependency is a claim about versions, and this package's
+ *   packaging guard refuses both an import that is not declared and a
+ *   declaration that is not imported. A *type-only* import would therefore turn
+ *   an optional integration into a mandatory claim on every line the peer range
+ *   admits — and a range that admits a line nobody ran is exactly the defect
+ *   that guard exists to prevent.
+ * - What is left is the consumer-side capability guard: look the service up,
+ *   check the shape of the answer instead of trusting it, and **fail closed**
+ *   (`{ ok: false }`): an unresolvable mode withholds the advisory, and the
+ *   caller discloses that withholding on the host side. An unresolvable mode is
+ *   emphatically *not* an invitation to fall back to the deployment default —
+ *   a session that overrode its mode to `danger-full-access` would then be
+ *   diagnosed as if it were confined.
+ *
+ * The call site this module depends on is stable across every line the peer
+ * range claims: `resolve(request?: SandboxPolicyRequest): SandboxExecutionPolicy`
+ * is declared at the same position of `lib/types/index.d.ts` in every published
+ * build from `0.1.2-rc.1` to `0.1.7-rc.1`, and `Agent.session` is present on
+ * the same span of `@deepseek-ai/dsh-agent`.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/** The three modes the harness resolves. */
+export type SandboxModeName = 'read-only' | 'workspace-write' | 'danger-full-access';
+/**
+ * Whether a mode confines the process it is asked to spawn.
+ * @param mode - the resolved mode.
+ * @returns true for every mode except `danger-full-access`.
+ */
+export declare function confines(mode: SandboxModeName): boolean;
+/** The outcome of resolving one agent's effective sandbox mode. */
+export type ModeResolution = 
+/**
+ * The mode the failing call ran under. `danger-full-access` is reported too:
+ * it is a real answer, and the caller's job (not this module's) is to decide
+ * that a non-confining mode is not this plugin's story.
+ */
+{
+    readonly ok: true;
+    readonly mode: SandboxModeName;
+}
+/** No answer was available, and why — the host side says so out loud. */
+ | {
+    readonly ok: false;
+    readonly withheld: string;
+};
+/**
+ * Resolve the effective sandbox mode for one agent's call.
+ *
+ * The service is looked up through `ctx.get` — the documented optional lookup —
+ * and the resolver is invoked with the agent's own session, so a session that
+ * logged a `sandbox/mode` override is answered with that override rather than
+ * with the deployment default.
+ * @param ctx - the plugin's context.
+ * @param agent - the agent whose call failed.
+ * @returns the mode, or the reason it could not be resolved.
+ */
+export declare function resolveSandboxMode(ctx: Context, agent: Agent): ModeResolution;