@argszero/cordis-plugin-sandbox-grant-advisor 0.10.0 → 0.12.0

package/lib/advice.js

@@ -3,7 +3,7 @@
  * environment failure, and what is deliberately withheld.
  *
  * The text is assembled here as pure functions so every sentence can be pinned
- * by a test, one family at a time. The three families are shaped by the same
+ * by a test, one family at a time. The four families are shaped by the same
  * question — is this the sandbox's doing, and what can the reader do about it —
  * and they answer it differently:
  *
@@ -112,6 +112,31 @@
  *   want of that variable. A withdrawn cause earns its sentence because this
  *   advisory shipped it twice; a confidently wrong cause is worse than two named
  *   ones with one shared remedy.
+ * - **The workspace-internal denial** (`workspace-denial`, #423) is the fourth,
+ *   and it is the first whose remedy is **withheld on purpose**. The failure is
+ *   not that a command failed but that the workspace's own grant does not cover
+ *   part of the workspace: the grant is written once on the root and depends on
+ *   ACE inheritance, so an already-existing object whose DACL the caller could
+ *   not write kept its older DACL, and the backend's root-only `hasExactGrant`
+ *   check means it is never revisited. Retrying is therefore provably useless,
+ *   which is what the text leads with. What it does **not** do is print a repair
+ *   command: the obvious one (`icacls` recursing the capability SID) is refused
+ *   by Windows itself with `ERROR_NONE_MAPPED` (1332), because that SID has no
+ *   name to map, and the line that would work needs the right that is missing —
+ *   so the advisory states the mechanism, names the ceiling, and says out loud
+ *   that it prints no command because this project has no Windows host to verify
+ *   one on. That is the same standard the standing-grant section is held to, and
+ *   it is the reason this family can be useful without being prescriptive.
+ *   Its discriminator is the **two-sided** one, which is not obvious and which a
+ *   reader checking only the ACE would get wrong: reading and listing use the
+ *   normal token while writing and deleting use the restricted one, so an object
+ *   whose DACL names only `Administrators`/`SYSTEM` plus the capability SID is
+ *   refused on the read side too and looks granted to a grep for the SID
+ *   (#423 measured it). The variant that would otherwise be missed gets its own
+ *   sentence as well — the same shape with the missing coverage on the mandatory
+ *   label instead of the DACL (reported 2026-09-29 in the same thread), which is
+ *   indistinguishable from inside a session and separable by the repository's own
+ *   diagnosis skill.
  *
  * 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
@@ -126,6 +151,12 @@
  * wrong remedy. Inside that Electron answer there is a third thing the code
  * cannot separate, and the advisory deliberately does not try: it names both
  * measurements and says the remedy does not depend on choosing between them.
+ * For the workspace-denial family the discriminator is the **path**, which is
+ * why the advisory prints the path it keyed on beside the root it tested it
+ * against: the reader can audit the plugin's own reasoning instead of taking a
+ * claim about two strings on faith. That family's check is also the one place
+ * where a single fact is not enough — reachability has two sides, and the text
+ * says which one a check on the ACE alone would miss.
  *
  * @module
  */
@@ -158,7 +189,34 @@ export const PTY_DISCUSSIONS = '#7638 / #8322';
  * launched from a terminal does not, which is the same variable the PTY family
  * now names.
  */
-export const NATIVE_INIT_DISCUSSIONS = '#7876 / #7877 / #8193 / #8208 / #8313';
+export const NATIVE_INIT_DISCUSSIONS = '#7876 / #7877 / #8193 / #8208 / #8313 / #8336 / #8334';
+/**
+ * The upstream thread the workspace-denial advisory is a stopgap for.
+ *
+ * One thread, because this family is one report and its own follow-up: `#423`
+ * is the failure and its measurements (170 of 729 objects missing the grant,
+ * root-level files among them, and the two-sided reachability rule), and the
+ * second comment in that thread is the mandatory-label variant of the same
+ * shape.
+ */
+export const WORKSPACE_DENIAL_DISCUSSIONS = '#423';
+/**
+ * The thread list each family's withholding note cites.
+ *
+ * A withheld recognition is a decision the host log has to account for, and the
+ * note a maintainer reads is only useful if it points at *that* family's
+ * report — a withheld native-init death and a withheld workspace denial are
+ * different reports, and a note that cites the wrong one is its own small
+ * misdiagnosis. Kept beside the constants it assembles rather than at the
+ * withholding site, so a family added without a thread is a type error instead
+ * of a note that quietly cites another family's.
+ */
+export const DISCUSSIONS_OF = {
+    'acl-provisioning': ACL_DISCUSSIONS,
+    'pty-startup': PTY_DISCUSSIONS,
+    'native-init': NATIVE_INIT_DISCUSSIONS,
+    'workspace-denial': WORKSPACE_DENIAL_DISCUSSIONS,
+};
 /** The documented prerequisite, quoted from the backend's README. */
 export const PREREQUISITE = 'granted directories must be caller-owned and grant `WRITE_OWNER`';
 /**
@@ -448,6 +506,8 @@ export function advisoryText(failure, context = {}) {
         }
         return nativeInitAdvisory(failure, context.mode, context.electronHost ?? electronHost(), context.href);
     }
+    if (failure.family === 'workspace-denial')
+        return workspaceDenialAdvisory(failure, context.tool, context.href);
     return aclAdvisory(failure, context.href);
 }
 /**
@@ -622,12 +682,31 @@ function nativeInitAdvisory(failure, mode, onElectron, href) {
         'Honest boundary — 0xC0000142 has producers this list does not have: a program that cannot load one of',
         'its own DLLs dies this way too, and the backend\'s own source records the console case as an inherent',
         'limit of the backend (`CREATE_NO_WINDOW` / `CREATE_NEW_CONSOLE` children die with `STATUS_DLL_INIT_FAILED`',
-        'under the restriction). #8208 explains that limit instead of repeating it, and the explanation is what the',
-        'two shapes above share: in a restricted token a console can be INHERITED but not CREATED. The creation',
-        'flags actually passed are three sets and none of them is `CREATE_NO_WINDOW` — `0` on the piped path,',
-        '`CREATE_SUSPENDED` on the inherited-job path, and `CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT` on the',
-        'ordinary path. Those same flags are fatal under a console-less runner and harmless under one that owns a',
-        'console, so it is the console and not the flag list that decides.',
+        'under the restriction). #8208 explains that limit instead of repeating it, and the explanation is a single',
+        'rule: in a restricted token a console can be INHERITED but not CREATED. Both shapes above follow from it —',
+        'the child needs a console it did not create, and anything that forces it to CREATE one is fatal on its own.',
+        '#8336 measured that side directly, on one machine, with a console-owning host, a restricted token and the',
+        'Low integrity level, varying only the creation flags: `0`, `DETACHED_PROCESS` and `CREATE_NEW_PROCESS_GROUP`',
+        'all reached the program, while `CREATE_NO_WINDOW` and `CREATE_NEW_CONSOLE` both died with the code above.',
+        '`STARTF_USESHOWWINDOW` with `SW_HIDE` — how a window is hidden without isolating a console — was harmless,',
+        'and so was `CREATE_NO_WINDOW` on an UNRESTRICTED token, which is what makes the two a pair rather than a',
+        'list of forbidden flags.',
+        'The creation flags this harness actually passes are three sets and none of them is `CREATE_NO_WINDOW` —',
+        '`0` on the piped path, `CREATE_SUSPENDED` on the inherited-job path, and',
+        '`CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT` on the ordinary path (that constant is not defined anywhere',
+        'in the process source). Those three are fatal under a console-less host and harmless under a host that owns',
+        'a console, so there the console decides. A flag that forces creation is a different animal: it decides even',
+        'when a console is there to be inherited.',
+        '',
+        'One thing that gets suspected and is not the cause: `windowsHide`. It is named here because it is the',
+        'first thing a search turns up, and it points at the wrong component — the flag is not set anywhere on the',
+        'confined path above. It appears on the ORDINARY subprocess path (`dsh-subprocess-local`: `windowsHide:`',
+        '`platform === \'win32\'`), which starts the runner rather than the confined child, and the restricted spawn',
+        'in `dsh-win32-process` passes the three flag sets just listed and defines no `CREATE_NO_WINDOW` constant at',
+        'all. Where it IS set — on the host — #8208 measured it both ways on a host that works: with and without',
+        '`windowsHide`, the confined `pwsh` reached exit 0 with its own stdout intact. The reason is the rule again:',
+        'a windowless console is still a console, and that is what the child inherits. What decides is whether the',
+        'host owns a console OBJECT, not whether it owns a window.',
         '',
         'One arm of this family was applied, measured, and rejected — named so a reader does not reach for it:',
         'putting `DETACHED_PROCESS` on the RESTRICTED CHILD removes its console request and does stop the crash,',
@@ -713,6 +792,117 @@ function ptyAdvisory(failure, mode, tool, href) {
         'shell can fail to start for other reasons and a confident wrong cause is worse than no answer.',
     ].join('\n');
 }
+/**
+ * Build the advisory for a confined command that was denied a path inside its
+ * own workspace.
+ *
+ * Four things this text must do, and one it must not. It must lead with the
+ * fact that **retrying is provably useless** (the backend's provisioning check
+ * short-circuits on the root, so the object that missed the propagation is never
+ * revisited) — that is the whole reason the model needs telling rather than
+ * discovering. It must show the **path it keyed on and the root it tested it
+ * against**, because the family's claim is a statement about two strings and the
+ * reader is entitled to audit it. It must give the **two-sided** reachability
+ * rule, since a check that only looks for the capability ACE reports an object
+ * as granted when the read side is refused as well. And it must name the
+ * **label variant** of the same shape, because from inside a session the two are
+ * indistinguishable and a reader who repairs the wrong half has learned
+ * nothing.
+ *
+ * What it must not do is print a repair command. The obvious one is refused by
+ * Windows with `ERROR_NONE_MAPPED` (1332) — a capability SID has no name for
+ * `icacls` to map — and the one that would work needs `WRITE_DAC` on the object,
+ * which is the right in question. This project has no Windows host to verify a
+ * line on, and the standing-grant section of the ACL advisory is held to the
+ * same standard for the same reason: an unverified remedy delivered confidently
+ * is the defect this plugin exists to answer. The mechanism is stated instead,
+ * and the reader is told why the command is absent.
+ * @param failure - the recognized failure.
+ * @param tool - the tool whose call was denied, when the caller knows it.
+ * @param href - optional URL shown for the upstream thread.
+ * @returns the user-role notice text.
+ */
+function workspaceDenialAdvisory(failure, tool, href) {
+    const where = href === undefined
+        ? `tracked upstream (discussion ${WORKSPACE_DENIAL_DISCUSSIONS})`
+        : `tracked upstream: ${href}`;
+    const call = tool === undefined ? 'This command' : `The \`${tool}\` command`;
+    const subject = failure.paths[0] ?? '<the path from the error line above>';
+    return [
+        'Denied inside your own workspace — the workspace grant does not reach that part of the tree, and retrying cannot repair it.',
+        '',
+        'What was reported:',
+        `  ${failureLine(failure)}`,
+        `${call} ran under sandbox mode \`${failure.mode}\`, where a write INSIDE the workspace is supposed to succeed, and every`,
+        'path it named is inside this session\'s workspace:',
+        ...failure.paths.map(path => `  ${path}`),
+        `  (workspace root: ${failure.workspaceRoot})`,
+        'So this is not the sandbox declining work that belongs outside the workspace. It is the workspace\'s own grant',
+        'failing to cover an object inside it, which is why every command touching that object fails the same way.',
+        '',
+        'Why — and why retrying cannot fix it:',
+        '  The host-side grant is written ONCE, on the workspace ROOT, and relies on Windows ACE inheritance to reach',
+        '  everything beneath it. Writing an inherited ACE into an ALREADY-EXISTING child needs WRITE_DAC on that child;',
+        '  where the caller does not hold it, Windows skips the child silently — no error, no return value, no log line.',
+        '  The backend then checks only the root (`hasExactGrant(workspaceRoot)`) and returns early when the grant is',
+        '  already there, which it is from the first call onwards. The descendants that missed the propagation are',
+        '  therefore never revisited — not later in this session, not in any later one — so the identical command keeps',
+        '  failing and there is no number of attempts that changes that',
+        '  (`packages/sandbox/sandbox-windows-acl/src/acl.ts`).',
+        '  WHICH objects miss it is a fact about who created them: objects the harness itself creates inherit the ACE,',
+        '  while objects that already existed or that another account or tool created (an installer, an editor, another',
+        '  agent harness running under its own account) are the ones the propagation skipped. #423 measured 170 of 729',
+        '  objects missing it, INCLUDING root-level files — so it is not only subdirectories, and "write it at the',
+        '  workspace root instead" is not a safe move either.',
+        '',
+        'Confirm it — this is the discriminator, and the second half is the part a single check gets wrong:',
+        `  icacls "${subject}"`,
+        'compared with the same command against the workspace root. The root carries an inheritable ACE for the workspace',
+        'capability SID — a `S-1-4-…` that `icacls` prints as an unresolved SID rather than a name — with Modify or Full',
+        'control; the failing object does not have it. Check each path listed above the same way; the first is shown here.',
+        '  THE TRAP: reading and listing go through the NORMAL token, writing and deleting through the RESTRICTED',
+        '  (low-integrity) one, and both sides must pass. An object whose DACL names only Administrators/SYSTEM plus the',
+        '  capability SID is refused on the read side as well, so it looks granted to a check that only searches for the',
+        '  capability SID — #423 measured exactly that on a `.cache` directory. A check that asks only "is the SID there?"',
+        '  reports those objects as fine while LIST and WRITE are both denied.',
+        '  A SECOND measured variant has the same shape and a different object: the coverage that is missing can be the',
+        '  mandatory-integrity LABEL rather than a DACL entry. It was reported in this same thread on 2026-09-29 against a',
+        '  `0.2.0-rc.1` install, under the same root-only short-circuit. Inside a session the two are indistinguishable;',
+        '  from outside, the repository\'s own diagnosis skill separates them — `diagnose-windows-sandbox-acl` (0.2.0 and',
+        '  later) reports `hasExactDeny()` for the DACL half and `LOW_LABEL` (`S-1-16-4096`) for the label half.',
+        '',
+        'Why the natural repair is closed — this is a Windows ceiling, not a mistake in the command:',
+        '  The grant the root carries is written for a capability SID, and a recursive `icacls /grant "*S-1-4-…:…" /T /C`',
+        '  is refused with ERROR_NONE_MAPPED (1332): the tool cannot map that SID to a name, so a grant that needs to name',
+        '  it never reaches the child. Widening the grant to a nameable account is a different grant with different',
+        '  consequences, not this one restored.',
+        '',
+        'What helps:',
+        '  - The move that is yours, and the only one available inside the session: write new files under a directory the',
+        '    harness itself created in this workspace. Those carry the grant, because their inheritance did apply — the',
+        '    reporter\'s own measurement, that objects DSH created are complete here and externally created ones are not.',
+        '  - The user\'s move: repair the specific object from an account that already holds WRITE_DAC on it, by writing',
+        '    the ACE the root carries into the child\'s own DACL. That needs the very right that is missing, so it is not',
+        '    something an unelevated prompt can do.',
+        '  No repair command is printed here on purpose. This project has no Windows host to verify one on, and shipping',
+        '  an unverified line would be the same defect this plugin exists to answer. The mechanism above is what is known;',
+        '  the line is yours to choose.',
+        '',
+        'The retry you are about to be offered: the denial surface offers one retry of this exact command under a wider',
+        'mode. That retry can only succeed by removing the confinement itself — it repairs nothing in the workspace, and',
+        'the next session meets the same gap. Take it only if that is what you mean to buy.',
+        '',
+        'Do NOT retry this call unchanged: the provisioning path short-circuits on the root grant, so the object that was',
+        'skipped is never revisited.',
+        '',
+        'How to read this: the denial names no cause and points at no repair, so the diagnosis is delivered here instead.',
+        'This is a stopgap, ' + where + '. This plugin speaks only when the mode is `workspace-write`, the host is',
+        'Windows, and every path the command names lies inside the workspace — a denial anywhere else is the sandbox',
+        'working as designed, and a confident wrong cause is worse than no answer.',
+        'What it is NOT: this plugin does not edit an ACL, does not elevate, and does not offer `danger-full-access` as a',
+        'fix.',
+    ].join('\n');
+}
 /**
  * Build the pre-dispatch denial for the optional fail-fast half.
  *

package/lib/index.js

@@ -2,7 +2,7 @@
  * `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.
  *
- * ## The three failures it recognizes
+ * ## The four failures it recognizes
  *
  * **Workspace provisioning (Windows ACL).** Four reports of one signature
  * (`#7538`, `#7622`, `#7646`, `#7720`) describe the same shape: the host-side write grant
@@ -68,6 +68,26 @@
  * tool's own canonical output, never a line of rendered text — and which three
  * narrowings keep the recognition from firing on something else.
  *
+ * **Denied inside the workspace (Windows ACL, `#423`).** The fourth family is
+ * the other half of the backend the first one explains, and it is the first
+ * whose remedy is withheld on purpose. There the grant could not be applied at
+ * all; here it *was* applied — on the workspace root, once — and Windows ACE
+ * inheritance silently skipped objects whose DACL the caller could not write.
+ * The backend's provisioning check short-circuits on the root (`hasExactGrant`
+ * returns early once the root carries the ACE, `sandbox-windows-acl/src/acl.ts`),
+ * so those descendants are never revisited and the same command fails forever,
+ * while a directory the harness itself created works. It arrives at the same
+ * seam as the native-init family and for the same structural reason: a denied
+ * command exits nonzero and the shipped shell tools report that as a finished
+ * run, so the fact is in `ToolExecutionSuccess.value` rather than in an error.
+ * Unlike that family it needs no bespoke code — the executors stamp the denial
+ * onto the value as a structured triple (`sandbox: { mode, denied, enforcement? }`,
+ * produced by matching the backend's own refusal dialect in the captured
+ * stderr), so this plugin reads the harness's own reading of its own sandbox.
+ * See `src/signature.ts` for the facts that narrow it, and in particular for
+ * why a denial is the *designed* outcome in three other situations (outside the
+ * workspace, under `read-only`, a runner failure) and must never be advised.
+ *
  * ## Where it acts, and why there
  *
  * One listener on the public `tools/post-execute` waterfall
@@ -107,9 +127,15 @@
  *    packaged desktop binary, which the plugin **measures and reports** rather
  *    than assumes), and carries the one conversion a model can actually make —
  *    rewrite the work as PowerShell or `cmd` when the program that could not
- *    start was an MSYS2 one. All three ride `additionalContexts`, so the model
- *    sees the diagnosis beside the failure rather than only in a log it never
- *    reads.
+ *    start was an MSYS2 one. For the workspace-denial family it prints the path
+ *    it keyed on beside the root it tested it against, says that retrying is
+ *    provably useless (the root-only provisioning check never revisits the
+ *    object), gives the two-sided reachability rule, names the label variant of
+ *    the same shape, and prints **no** repair command — the obvious one is
+ *    refused by Windows with `ERROR_NONE_MAPPED (1332)`, and this project has no
+ *    Windows host to verify a line on. All four 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
@@ -121,8 +147,13 @@
  *    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.
+ *    says so once**. The workspace-denial advisory is withheld the same way when
+ *    the workspace root — the fact the containment claim is tested against —
+ *    cannot be resolved. Silence alone would make "the sandbox is not the cause" and
+ *    "this plugin could not tell" indistinguishable from the outside. A denial
+ *    the classifier *can* place outside the workspace is a different case and is
+ *    left silent on purpose: that is the sanctioned escalation path, not a
+ *    puzzle, and a note about it would be noise.
  *
  * ## Honest boundaries
  *
@@ -139,7 +170,10 @@
  *   tools' own foreground projection with the reported codes, including the
  *   signed form the reporter saw (`-1073741502`) and the real MSYS2 stderr, so the
  *   recognition runs against the producer's data rather than against a message
- *   this plugin invented.
+ *   this plugin invented. The workspace-denial family is exercised the same way:
+ *   the test builds the executors' own `sandbox` stamp and the shipped foreground
+ *   projection, supplies `win32` as the platform fact, and covers both the
+ *   recognized case and each of the narrowings that must stay silent.
  * - **It does not repair anything.** No ACL is written, no privilege is
  *   requested, nothing is elevated, no environment variable is set for another
  *   process, no preset is installed and no mode is changed: the remedies are the
@@ -148,7 +182,7 @@
  *   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**, in all three families: the ACL failure should
+ * - **The real fix is upstream**, in all four families: the ACL failure should
  *   name
  *   the outstanding condition at the site that knows it (`grantWrite` computes
  *   `hasExactGrant`/`hasExactDeny`/`hasExactLabel` and discards which was
@@ -156,14 +190,19 @@
  *   incompatible with the PTY backend" or fall back to a one-shot shell, and the
  *   sandbox runner should be launched with the environment its own execution
  *   needs (`ELECTRON_RUN_AS_NODE` when argv[0] is an Electron binary) or with a
- *   documented, checkable refusal for MSYS2 programs. This plugin is the stopgap.
+ *   documented, checkable refusal for MSYS2 programs. The workspace-denial family
+ *   is the same shape once more: `grantWrite` returns early when the *root*
+ *   already carries the ACE, so the descendants that missed the propagation are
+ *   never repaired — the check would have to look past the root, or the denial
+ *   surface would have to say *which* path was refused instead of only that one
+ *   was. This plugin is the stopgap.
  *
  * @module @argszero/cordis-plugin-sandbox-grant-advisor
  */
 import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
-import { advisoryText, ACL_DISCUSSIONS, denialText, NATIVE_INIT_DISCUSSIONS, PTY_DISCUSSIONS } from './advice.js';
-import { classifyNativeInitDeath, classifyProvisioningFailure, classifyPtyStartupFailure } from './signature.js';
-import { confines, resolveSandboxMode } from './mode.js';
+import { advisoryText, ACL_DISCUSSIONS, denialText, DISCUSSIONS_OF, NATIVE_INIT_DISCUSSIONS, PTY_DISCUSSIONS, WORKSPACE_DENIAL_DISCUSSIONS } from './advice.js';
+import { classifyNativeInitDeath, classifyProvisioningFailure, classifyPtyStartupFailure, classifyWorkspaceDenial, hasWorkspaceDenialStamp, } from './signature.js';
+import { confines, resolveSandboxMode, resolveWorkspaceRoot } from './mode.js';
 import { advisedOf, callKey, observe, observeSuccess, recordAdvice, recordDenial, recordWithheld, shouldDeny, } from './state.js';
 export const name = 'sandbox-grant-advisor';
 /** The tool pipeline this plugin observes and (optionally) gates. */
@@ -303,6 +342,10 @@ function summaryOf(failure, mode) {
         return `sandboxed command never started (exit ${String(failure.rawExitCode)}, STATUS_DLL_INIT_FAILED) `
             + `under sandbox mode "${String(mode)}"`;
     }
+    if (failure.family === 'workspace-denial') {
+        const subject = failure.paths[0] ?? 'a path in the workspace';
+        return `denied inside the workspace (${subject}) under sandbox mode "${failure.mode}"`;
+    }
     return `workspace ACL provisioning failed (Win32 ${String(failure.win32Code)})`;
 }
 /**
@@ -346,16 +389,16 @@ export function apply(ctx, config = {}) {
      * @param agent - the agent whose failure was withheld.
      * @param state - the agent's state, to keep the note to one.
      * @param why - what stopped the advisory.
-     * @param failure - the recognized failure that was withheld; only the two
-     *   mode-gated families reach this function, so the thread it cites is exact.
+     * @param family - the recognized family that was withheld. Only families whose
+     *   gate can fail closed reach this function, so the thread it cites is exact.
      * @returns undefined, so callers can `return withhold(...)`.
      */
-    function withhold(agent, state, why, failure) {
+    function withhold(agent, state, why, family) {
         if (state?.withheld === true)
             return undefined;
         states.set(agent, recordWithheld(state));
-        const discussions = failure.family === 'pty-startup' ? PTY_DISCUSSIONS : NATIVE_INIT_DISCUSSIONS;
-        ctx.logger.warn(`sandbox-grant-advisor: ${failure.family} failure recognized but no advisory sent — ${why}; the raw `
+        const discussions = DISCUSSIONS_OF[family];
+        ctx.logger.warn(`sandbox-grant-advisor: ${family} failure recognized but no advisory sent — ${why}; the raw `
             + `error is left exactly as it is, so this is NOT a claim that the sandbox is unrelated (discussions ${discussions})`);
         return undefined;
     }
@@ -383,12 +426,20 @@ export function apply(ctx, config = {}) {
             // read from `result.value` and never from the rendered text, so a command
             // whose own output mentions the code cannot be mistaken for it.
             const death = classifyNativeInitDeath(result.value);
-            if (death === undefined) {
-                if (previous !== undefined)
-                    states.set(agent, observeSuccess(previous, key));
-                return undefined;
+            if (death !== undefined)
+                return adviseGated(agent, previous, death, key, exec.name);
+            // The workspace-denial family is the other value-read one, and it is read
+            // only when the host is Windows: the mechanism it explains is ACE
+            // inheritance, which no other backend has, so on macOS/Linux the same
+            // stamp is a different story and is left alone with no note at all (that
+            // is the designed denial path there, not a puzzle). The platform test
+            // comes first so a non-Windows host never pays for the policy lookup.
+            if (process.platform === 'win32' && hasWorkspaceDenialStamp(result.value)) {
+                return adviseWorkspaceDenial(agent, previous, result.value, exec.arguments, key, exec.name);
             }
-            return adviseGated(agent, previous, death, key, exec.name);
+            if (previous !== undefined)
+                states.set(agent, observeSuccess(previous, key));
+            return undefined;
         }
         // The two text families read different fields, on purpose. The ACL signature
         // carries an API name plus a Win32 code, which a command's own output does
@@ -441,12 +492,12 @@ export function apply(ctx, config = {}) {
     function adviseGated(agent, previous, failure, key, tool) {
         const resolution = resolveSandboxMode(ctx, agent);
         if (!resolution.ok)
-            return withhold(agent, previous, resolution.withheld, failure);
+            return withhold(agent, previous, resolution.withheld, failure.family);
         const mode = resolution.mode;
         if (!confines(mode)) {
             const what = failure.family === 'pty-startup' ? 'the shell' : 'the command';
             return withhold(agent, previous, `the failing call ran under \`${mode}\`, where ${what} is not spawned `
-                + 'through the sandbox', failure);
+                + 'through the sandbox', failure.family);
         }
         if (!claimAdvice(agent, previous, failure, key))
             return undefined;
@@ -468,6 +519,59 @@ export function apply(ctx, config = {}) {
         states.set(agent, first ? recordAdvice(advanced, failure.family) : advanced);
         return first;
     }
+    /**
+     * Diagnose one denial whose target lies **inside** the agent's own workspace.
+     *
+     * The fourth family reads the executor's structured stamp rather than a
+     * message, so what is left here is the one fact the stamp cannot carry: the
+     * workspace root, which the containment claim has to be tested against. It is
+     * resolved from the agent's own session (the same resolver the enforcing
+     * providers are handed), and a root that cannot be resolved withholds the
+     * advisory rather than guessing — but only after the stamp has been seen, so
+     * an ordinary successful call costs no note. Once the root is known the
+     * classifier decides; a value that is a denial but names no in-workspace path
+     * is the designed escalation path and is left silent on purpose, which is why
+     * the `undefined` from the classifier is *not* routed through `withhold`.
+     * @param agent - the agent whose call was denied.
+     * @param previous - the agent's state before this call, if any.
+     * @param value - the settled call's canonical value.
+     * @param args - the settled call's parsed arguments.
+     * @param key - the identity of the denied call.
+     * @param tool - the denied tool's name, for the advisory context.
+     * @returns the notice to attach, or undefined.
+     */
+    function adviseWorkspaceDenial(agent, previous, value, args, key, tool) {
+        const resolution = resolveWorkspaceRoot(ctx, agent);
+        if (!resolution.ok)
+            return withhold(agent, previous, resolution.withheld, 'workspace-denial');
+        const failure = classifyWorkspaceDenial(value, args, {
+            platform: process.platform,
+            workspaceRoot: resolution.workspaceRoot,
+        });
+        if (failure === undefined)
+            return undefined;
+        if (!claimAdvice(agent, previous, failure, key))
+            return undefined;
+        ctx.logger.warn(workspaceDenialHostLine(failure));
+        return notice(advisoryText(failure, advisoryContext(tool)), summaryOf(failure));
+    }
+    /**
+     * The one-line host-side account of a recognized workspace-internal denial.
+     *
+     * It carries the path the plugin keyed on, because this family's whole claim
+     * is that one named path lies inside one named root — a maintainer reading the
+     * log is entitled to see both halves of the string comparison rather than a
+     * verdict about it.
+     * @param failure - the recognized failure.
+     * @returns a single log line.
+     */
+    function workspaceDenialHostLine(failure) {
+        const subject = failure.paths[0] ?? '<no path recovered>';
+        const more = failure.paths.length > 1 ? ` (+${String(failure.paths.length - 1)} more inside the same root)` : '';
+        return `sandbox-grant-advisor: confined command denied ${subject}${more}, which is INSIDE the workspace `
+            + `${failure.workspaceRoot}, under sandbox mode "${failure.mode}" — the root-only grant skipped this object and `
+            + `is never revisited, so retrying cannot help; advisory delivered to the model (discussion ${WORKSPACE_DENIAL_DISCUSSIONS})`;
+    }
     /**
      * The advisory context for one failing call.
      *

package/lib/mode.js

@@ -19,6 +19,13 @@
  * session — so what is quoted in the advisory is the policy that actually
  * governed the failing call, not a guess reconstructed from configuration.
  *
+ * The same lookup answers the **workspace root** for the fourth family
+ * (`workspace-denial`, #423), whose claim is that the path a denied command
+ * named lies inside the session's own workspace. Same request, same fail-closed
+ * posture, separate function ({@link resolveWorkspaceRoot}), so that neither
+ * family can fail on a field it never reads and each can name the failure in its
+ * own words.
+ *
  * ## Why this is a guarded lookup instead of an import
  *
  * `@deepseek-ai/dsh-sandbox-policy` is **optional** in this plugin's world: a
@@ -106,10 +113,60 @@ function recognizedMode(resolved) {
  * @returns the mode, or the reason it could not be resolved.
  */
 export function resolveSandboxMode(ctx, agent) {
+    const lookup = policyOf(ctx, agent);
+    if (!lookup.ok)
+        return { ok: false, withheld: lookup.withheld };
+    const mode = recognizedMode(lookup.resolved);
+    if (mode === undefined) {
+        return { ok: false, withheld: '`sandboxPolicy.resolve` returned a value without a recognizable mode' };
+    }
+    return { ok: true, mode };
+}
+/**
+ * The workspace root the policy resolver reports for one agent's call.
+ *
+ * The same lookup, the same request and the same fail-closed posture as
+ * {@link resolveSandboxMode}, and for the same reason: the root is what the
+ * enforcing providers were handed, so it is the value the workspace-denial
+ * family must test containment against rather than one reconstructed from
+ * configuration. The two are separate functions rather than one that returns
+ * both because each family needs one of them, and a family that needs only the
+ * mode must not be able to fail on a missing root (nor the other way round).
+ * @param ctx - the plugin's context.
+ * @param agent - the agent whose call failed.
+ * @returns the root, or the reason it could not be resolved.
+ */
+export function resolveWorkspaceRoot(ctx, agent) {
+    const lookup = policyOf(ctx, agent);
+    if (!lookup.ok) {
+        return {
+            ok: false,
+            withheld: lookup.why === 'unmounted'
+                ? 'no `sandboxPolicy` service is mounted in this composition, so the workspace root is unknown'
+                : lookup.withheld,
+        };
+    }
+    const resolved = lookup.resolved;
+    const root = resolved === null || typeof resolved !== 'object'
+        ? undefined
+        : resolved.workspaceRoot;
+    if (typeof root !== 'string' || root.length === 0) {
+        return { ok: false, withheld: '`sandboxPolicy.resolve` returned a value without a usable workspace root' };
+    }
+    return { ok: true, workspaceRoot: root };
+}
+/**
+ * Ask the mounted policy service for one agent's resolved policy.
+ * @param ctx - the plugin's context.
+ * @param agent - the agent whose call is being placed.
+ * @returns the resolver's answer, or the reason there is none.
+ */
+function policyOf(ctx, agent) {
     const policy = asPolicy(ctx.get('sandboxPolicy'));
     if (policy === undefined) {
         return {
             ok: false,
+            why: 'unmounted',
             withheld: 'no `sandboxPolicy` service is mounted in this composition, so the effective mode is unknown',
         };
     }
@@ -117,19 +174,14 @@ export function resolveSandboxMode(ctx, agent) {
     if (session === undefined) {
         return {
             ok: false,
+            why: 'no-session',
             withheld: 'the agent exposes no session, and the policy must be resolved from it rather than from the deployment default',
         };
     }
-    let resolved;
     try {
-        resolved = policy.resolve({ session });
+        return { ok: true, resolved: policy.resolve({ session }) };
     }
     catch (error) {
-        return { ok: false, withheld: `\`sandboxPolicy.resolve\` threw (${String(error)})` };
-    }
-    const mode = recognizedMode(resolved);
-    if (mode === undefined) {
-        return { ok: false, withheld: '`sandboxPolicy.resolve` returned a value without a recognizable mode' };
+        return { ok: false, why: 'threw', withheld: `\`sandboxPolicy.resolve\` threw (${String(error)})` };
     }
-    return { ok: true, mode };
 }