deepseek-coordination 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepseek-coordination",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "private": false,
   "type": "module",
   "description": "Cross-platform atomic OS-interaction surface for the DeepSeek Harness: one argument-stable verb set implemented natively on each OS, with byte-exact charset, BOM and line-ending handling.",
@@ -92,7 +92,9 @@
     "test": "powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File tests/golden.ps1",
     "test:encoding": "powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File tests/encoding.ps1",
     "test:conformance": "powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File tests/conformance.ps1",
+    "test:rules": "powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File tests/rules.ps1",
     "test:plugin": "node tests/plugin.test.mjs",
+    "test:activation": "node tests/activation.test.mjs",
     "test:takeover": "node tests/takeover.test.mjs",
     "test:permission": "node tests/permission.test.mjs",
     "test:workflow": "node tests/workflow.test.mjs",
@@ -102,7 +104,7 @@
     "test:load": "node tools/verify-plugin-load.mjs && node tools/verify-editions.mjs",
     "test:pipeline": "node tools/probe-pipeline.mjs",
     "measure:cache": "node tools/measure-cache.mjs",
-    "test:all": "npm run test:conformance && npm run test:encoding && npm run test && npm run test:plugin && npm run test:takeover && npm run test:permission && npm run test:workflow && npm run test:bundle && npm run test:package && npm run test:load && npm run test:desktop",
+    "test:all": "npm run test:conformance && npm run test:encoding && npm run test && npm run test:rules && npm run test:plugin && npm run test:activation && npm run test:takeover && npm run test:permission && npm run test:workflow && npm run test:bundle && npm run test:package && npm run test:load && npm run test:desktop",
     "selfcheck": "powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File src/host/bin/dsh-os.ps1 selfcheck"
   },
   "devDependencies": {

package/src/host/bin/dsh-os.ps1

@@ -498,6 +498,50 @@ function Assert-Allowed {
   if ($Positionals -ge 0 -and $Parsed.positionals.Length -gt $Positionals) {
     throw (New-OsError -Code 'E_USAGE' -Message ("unexpected extra argument <{0}>" -f $Parsed.positionals[$Positionals]))
   }
+
+  # ---------------------------------------------------------------------------
+  # The durable rules are consulted HERE, at the one gate every mutating verb passes through.
+  #
+  # Before this existed, `permission.json` was written by the consent delegate and read by
+  # `permission.list` / `permission.query` for DISPLAY only: no verb ever looked at a rule, so a
+  # `deny-always` stopped nothing and an `allow-always` bought nothing. The file recorded decisions that
+  # had no effect, which is worse than having no file at all, because it reads as enforcement.
+  #
+  # A deny is checked FIRST and wins outright, so the answer never depends on the order rules were
+  # appended in. It is checked BEFORE the `--allow` flag, deliberately: `--allow` says a caller believes
+  # it is authorized, and a rule is the user having said otherwise. A deny that `--allow` could overrule
+  # would be a rule that does not deny.
+  #
+  # An allow rule still requires `--allow`, and that is not an oversight: the flag is the per-call
+  # statement that a caller has been authorized for THIS call, while the rule is the standing permission
+  # to be authorized at all. Requiring both keeps the flag meaningful for callers that never consult the
+  # rules, and stops a durable grant from silently authorizing every future call on its own.
+  # ---------------------------------------------------------------------------
+  $state = Read-PermissionFile
+  # An UNTRUSTED file is treated as having no rules at all, which is what the consent delegate does
+  # (`readDocument` returns an empty document when `updatedBy` is not its own). Only setting a `trusted`
+  # flag and then honouring the rules anyway would let anyone who can write the file both grant and deny
+  # by hand: the delegate is supposed to be its only writer, so a file it did not write is not evidence.
+  if ($null -ne $state.document -and $state.trusted) {
+    $target = Get-PermissionTarget -Parsed $Parsed -Verb $Verb
+    # THE TWO SPELLINGS ARE NOT THE SAME STRING, and that is the whole trap here.
+    #
+    # Every call site passes the verb in its HUMAN form, with spaces ("file delete"), because that is the
+    # text the error messages show. `permission.json` stores it in its TABLE form, with dots
+    # ("file.delete"), because that is what `selfcheck` and `permission.query` report and what a user
+    # writes into a rule. Comparing the two directly made every rule fail to match - silently, and only
+    # for the enforcement path, since the display path was always given the dotted form by its caller.
+    # A rule that never matches is indistinguishable from no rule at all, so this had to be normalized
+    # rather than documented.
+    $ruleVerb = $Verb -replace ' ', '.'
+    $rule = Get-PermissionDecision -Document $state.document -Verb $ruleVerb -Target $target
+    if ($null -ne $rule -and $rule.decision -eq 'deny-always') {
+      throw (New-OsError -Code 'E_PERMISSION_DENIED_BY_RULE' `
+          -Message ("{0} on '{1}' is denied by the stored rule {2}" -f $Verb, $target, $rule.id) `
+          -Hint 'the rule was written by the consent delegate; remove it with os_permission_revoke before retrying')
+    }
+  }
+
   if (-not (Test-HasFlag -Parsed $Parsed -Name 'allow')) {
     throw (New-OsError -Code 'E_PERMISSION' `
         -Message ("{0} is a mutating operation and requires user authorization" -f $Verb) `
@@ -3198,16 +3242,7 @@ function Invoke-PermissionQuery {
   $target = Get-Positional -Parsed $Parsed -Index 1 -Name 'target' -Optional -Default '*'
   Assert-NoExtra -Parsed $Parsed -Expected 2
   $state = Read-PermissionFile
-  $matched = $null
-  if ($null -ne $state.document -and $null -ne $state.document.PSObject.Properties['rules']) {
-    foreach ($r in @($state.document.rules)) {
-      $verbMatch = ($r.verb -eq $verb) -or ($r.verb.EndsWith('.*') -and $verb.StartsWith($r.verb.Substring(0, $r.verb.Length - 1)))
-      if (-not $verbMatch) { continue }
-      $value = '*'
-      if ($null -ne $r.target -and $null -ne $r.target.PSObject.Properties['value']) { $value = [string]$r.target.value }
-      if ($value -eq '*' -or $value -eq $target) { $matched = $r; break }
-    }
-  }
+  $matched = Get-PermissionDecision -Document $state.document -Verb $verb -Target $target
   $decision = 'ask'
   if ($null -ne $matched) { $decision = [string]$matched.decision }
   elseif (-not $state.trusted) { $decision = 'ask' }
@@ -3223,6 +3258,66 @@ function Invoke-PermissionQuery {
   }
 }
 
+# ---------------------------------------------------------------------------
+# Rule evaluation for the verb layer
+# ---------------------------------------------------------------------------
+
+# DENY FIRST, then allow. This is the deliberate departure from "first match wins" that the consent
+# delegate already implements, and it is what the two readers had disagreed about: the script used to
+# take the first matching rule in array order, so a deny and an allow that both matched resolved by
+# whichever happened to be appended first. The safe answer must not depend on append order.
+#
+# Returns the DECIDING rule, or $null when no rule matches (the caller then falls back to defaults).
+function Get-PermissionDecision {
+  param($Document, [string]$Verb, [string]$Target)
+  if ($null -eq $Document) { return $null }
+  if ($null -eq $Document.PSObject.Properties['rules']) { return $null }
+  $matching = @()
+  foreach ($r in @($Document.rules)) {
+    $pattern = [string]$r.verb
+    $verbMatch = ($pattern -eq $Verb) -or ($pattern -eq '*')
+    if (-not $verbMatch -and $pattern.EndsWith('.*')) {
+      # The namespace prefix stops at the LAST dot, not one character before the asterisk. Taking the
+      # string minus its final character turns "file.*" into "file." (correct) but also turns
+      # "file.delete" into "file.d", which then prefix-matches "file.delete" AND "file.destroy" and every
+      # other verb that happens to start with the same letters. A rule for one verb must not deny another.
+      $prefix = $pattern.Substring(0, $pattern.Length - 2) + '.'
+      $verbMatch = $Verb.StartsWith($prefix)
+    }
+    if (-not $verbMatch) { continue }
+    $value = '*'
+    if ($null -ne $r.target -and $null -ne $r.target.PSObject.Properties['value']) { $value = [string]$r.target.value }
+    # A target that is not the wildcard only matches when the caller's own string matches it exactly.
+    # The argument is used AS WRITTEN rather than resolved to an absolute path: a rule is granted on the
+    # thing the user was shown, and rewriting it here would make matching depend on the working directory.
+    if ($value -ne '*' -and $value -ne $Target) { continue }
+    $matching += $r
+  }
+  foreach ($r in $matching) { if ($r.decision -eq 'deny-always') { return $r } }
+  foreach ($r in $matching) { if ($r.decision -eq 'allow-always') { return $r } }
+  return $null
+}
+
+# The value a rule is written against, derived from the verb and the caller's own argument.
+#
+# The verb layer has one thing the tool layer does not: the exact argv. So the target here is the
+# argument AS TYPED - a path, a service name, a variable name, a pid - which is the string a human would
+# have written into a rule. An unresolvable verb shape yields '*' (verb-wide only), which is the
+# conservative direction: a rule scoped to one path can only fail to match, never match too much.
+function Get-PermissionTarget {
+  param($Parsed, [string]$Verb)
+  $first = $null
+  if ($Parsed.positionals.Length -ge 1) { $first = [string]$Parsed.positionals[0] }
+  if ([string]::IsNullOrEmpty($first)) { return '*' }
+  switch -Regex ($Verb) {
+    '^file\.' { return $first }
+    '^service\.' { return $first }
+    '^task\.(launch|kill)$' { return $first }
+    '^environment\.' { return $first }
+    default { return '*' }
+  }
+}
+
 # The well-known SID for "Everyone". Layer A denies write access to it, because denying Everyone
 # covers every context that could open the file, including the automation one, without this process
 # having to know which account the harness runs as.

package/src/host/bin/dsh-os7.ps1

@@ -589,6 +589,56 @@ function Assert-Allowed {
   if ($Positionals -ge 0 -and $Parsed.positionals.Length -gt $Positionals) {
     throw (New-OsError -Code 'E_USAGE' -Message ("unexpected extra argument <{0}>" -f $Parsed.positionals[$Positionals]))
   }
+
+  # ---------------------------------------------------------------------------
+  # The durable rules are consulted HERE, at the one gate every mutating verb passes through.
+  #
+  # Before this existed, `permission.json` was written by the consent delegate and read by
+  # `permission.list` / `permission.query` for DISPLAY only: no verb ever looked at a rule, so a
+  # `deny-always` stopped nothing and an `allow-always` bought nothing. The file recorded decisions that
+  # had no effect, which is worse than having no file at all, because it reads as enforcement.
+  #
+  # A deny is checked FIRST and wins outright, so the answer never depends on the order rules were
+  # appended in. It is checked BEFORE the `--allow` flag, deliberately: `--allow` says a caller believes
+  # it is authorized, and a rule is the user having said otherwise. A deny that `--allow` could overrule
+  # would be a rule that does not deny.
+  #
+  # An allow rule still requires `--allow`, and that is not an oversight: the flag is the per-call
+  # statement that a caller has been authorized for THIS call, while the rule is the standing permission
+  # to be authorized at all. Requiring both keeps the flag meaningful for callers that never consult the
+  # rules, and stops a durable grant from silently authorizing every future call on its own.
+  #
+  # Both helpers live in permission.ps1, which is assembled AFTER this module. That is not a problem:
+  # PowerShell binds function calls at invocation time, not at definition time, and no verb runs until
+  # every module has been assembled into the one script. The golden suite exercises this path, so a
+  # load-order mistake cannot pass silently.
+  # ---------------------------------------------------------------------------
+  $state = Read-PermissionFile
+  # An UNTRUSTED file is treated as having no rules at all, which is what the consent delegate does
+  # (`readDocument` returns an empty document when `updatedBy` is not its own). Only setting a `trusted`
+  # flag and then honouring the rules anyway would let anyone who can write the file both grant and deny
+  # by hand: the delegate is supposed to be its only writer, so a file it did not write is not evidence.
+  if ($null -ne $state.document -and $state.trusted) {
+    $target = Get-PermissionTarget -Parsed $Parsed -Verb $Verb
+    # THE TWO SPELLINGS ARE NOT THE SAME STRING, and that is the whole trap here.
+    #
+    # Every call site passes the verb in its HUMAN form, with spaces ("file delete"), because that is the
+    # text the error messages show. `permission.json` stores it in its TABLE form, with dots
+    # ("file.delete"), because that is what `selfcheck` and `permission.query` report and what a user
+    # writes into a rule. Comparing the two directly made every rule fail to match - silently, and only
+    # for the enforcement path, since the display path was always given the dotted form by its caller.
+    # A rule that never matches is indistinguishable from no rule at all, so this had to be normalized
+    # rather than documented.
+    $ruleVerb = $Verb.Replace(' ', '.')
+    $rule = Get-PermissionDecision -Document $state.document -Verb $ruleVerb -Target $target
+    if ($null -ne $rule -and
+        [string]::Equals([string]$rule.decision, 'deny-always', [System.StringComparison]::Ordinal)) {
+      throw (New-OsError -Code 'E_PERMISSION_DENIED_BY_RULE' `
+          -Message ("{0} on '{1}' is denied by the stored rule {2}" -f $Verb, $target, $rule.id) `
+          -Hint 'the rule was written by the consent delegate; remove it with os_permission_revoke before retrying')
+    }
+  }
+
   if (-not (Test-HasFlag -Parsed $Parsed -Name 'allow')) {
     throw (New-OsError -Code 'E_PERMISSION' `
         -Message ("{0} is a mutating operation and requires user authorization" -f $Verb) `
@@ -3557,26 +3607,9 @@ function Invoke-PermissionQuery {
   $target = Get-Positional -Parsed $Parsed -Index 1 -Name 'target' -Optional -Default '*'
   Assert-NoExtra -Parsed $Parsed -Expected 2
   $state = Read-PermissionFile
-  $matched = $null
-  if ($null -ne $state.document -and $null -ne $state.document.PSObject.Properties['rules']) {
-    foreach ($r in @($state.document.rules)) {
-      # The rule text comes from permission.json and the verb comes from argv, so both comparisons are
-      # named rather than linguistic. A rule written "file.*" matches every verb under "file." because
-      # the trailing asterisk is dropped and what remains is used as a prefix.
-      $verbMatch = [string]::Equals([string]$r.verb, $verb, [System.StringComparison]::OrdinalIgnoreCase)
-      if (-not $verbMatch -and $r.verb.EndsWith('.*', [System.StringComparison]::Ordinal)) {
-        $prefix = $r.verb.Substring(0, $r.verb.Length - 1)
-        # The prefix test keeps the case-sensitivity the 5.1 code had; only its tolerance of control
-        # characters is dropped.
-        $verbMatch = $verb.StartsWith($prefix, [System.StringComparison]::Ordinal)
-      }
-      if (-not $verbMatch) { continue }
-      $value = '*'
-      if ($null -ne $r.target -and $null -ne $r.target.PSObject.Properties['value']) { $value = [string]$r.target.value }
-      if ([string]::Equals($value, '*', [System.StringComparison]::OrdinalIgnoreCase) -or
-          [string]::Equals($value, $target, [System.StringComparison]::OrdinalIgnoreCase)) { $matched = $r; break }
-    }
-  }
+  # One evaluator, shared with the verb layer's authorization gate, so the answer this verb REPORTS and
+  # the answer a mutating verb ACTS ON cannot drift apart.
+  $matched = Get-PermissionDecision -Document $state.document -Verb $verb -Target $target
   $decision = 'ask'
   if ($null -ne $matched) { $decision = [string]$matched.decision }
   elseif (-not $state.trusted) { $decision = 'ask' }
@@ -3592,6 +3625,79 @@ function Invoke-PermissionQuery {
   }
 }
 
+# ---------------------------------------------------------------------------
+# Rule evaluation for the verb layer
+# ---------------------------------------------------------------------------
+
+# DENY FIRST, then allow. This is the deliberate departure from "first match wins" that the consent
+# delegate already implements, and it is what the two readers had disagreed about: this function used to
+# take the first matching rule in array order, so a deny and an allow that both matched resolved by
+# whichever happened to be appended first. The safe answer must not depend on append order.
+#
+# Every comparison below is named ORDINAL, for the reason this whole module names its comparisons: from
+# .NET 5 an ignorable character compares equal to almost anything, so a linguistic `-eq` would let a rule
+# whose verb carries a stray control byte match a verb it is not. The delegate's JS reader compares by
+# exact string equality, so ordinal is also what keeps the two readers agreeing.
+#
+# Returns the DECIDING rule, or $null when no rule matches (the caller then falls back to defaults).
+function Get-PermissionDecision {
+  param($Document, [string]$Verb, [string]$Target)
+  if ($null -eq $Document) { return $null }
+  if ($null -eq $Document.PSObject.Properties['rules']) { return $null }
+  $matching = @()
+  foreach ($r in @($Document.rules)) {
+    $pattern = [string]$r.verb
+    $verbMatch = [string]::Equals($pattern, $Verb, [System.StringComparison]::OrdinalIgnoreCase)
+    if (-not $verbMatch) {
+      $verbMatch = [string]::Equals($pattern, '*', [System.StringComparison]::OrdinalIgnoreCase)
+    }
+    if (-not $verbMatch -and $pattern.EndsWith('.*', [System.StringComparison]::Ordinal)) {
+      # The namespace prefix stops at the LAST dot, not one character before the asterisk. Taking the
+      # string minus its final character turns "file.*" into "file." (correct) but also turns
+      # "file.delete" into "file.d", which then prefix-matches "file.delete" AND "file.destroy" and every
+      # other verb that happens to start with the same letters. A rule for one verb must not deny another.
+      $prefix = $pattern.Substring(0, $pattern.Length - 2) + '.'
+      $verbMatch = $Verb.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)
+    }
+    if (-not $verbMatch) { continue }
+    $value = '*'
+    if ($null -ne $r.target -and $null -ne $r.target.PSObject.Properties['value']) { $value = [string]$r.target.value }
+    # A target that is not the wildcard only matches when the caller's own string matches it exactly.
+    # The argument is used AS WRITTEN rather than resolved to an absolute path: a rule is granted on the
+    # thing the user was shown, and rewriting it here would make matching depend on the working directory.
+    if (-not [string]::Equals($value, '*', [System.StringComparison]::OrdinalIgnoreCase)) {
+      if (-not [string]::Equals($value, $Target, [System.StringComparison]::OrdinalIgnoreCase)) { continue }
+    }
+    $matching += $r
+  }
+  foreach ($r in $matching) {
+    if ([string]::Equals([string]$r.decision, 'deny-always', [System.StringComparison]::Ordinal)) { return $r }
+  }
+  foreach ($r in $matching) {
+    if ([string]::Equals([string]$r.decision, 'allow-always', [System.StringComparison]::Ordinal)) { return $r }
+  }
+  return $null
+}
+
+# The value a rule is written against, derived from the verb and the caller's own argument.
+#
+# The verb layer has one thing the tool layer does not: the exact argv. So the target here is the argument
+# AS TYPED - a path, a service name, a variable name, a pid - which is the string a human would have
+# written into a rule. An unrecognised verb shape yields '*' (verb-wide only), which is the conservative
+# direction: a path-scoped rule can then only fail to match, never match too much.
+function Get-PermissionTarget {
+  param($Parsed, [string]$Verb)
+  $first = $null
+  if ($Parsed.positionals.Length -ge 1) { $first = [string]$Parsed.positionals[0] }
+  if ([string]::IsNullOrEmpty($first)) { return '*' }
+  if ($Verb.StartsWith('file.', [System.StringComparison]::Ordinal)) { return $first }
+  if ($Verb.StartsWith('service.', [System.StringComparison]::Ordinal)) { return $first }
+  if ($Verb.StartsWith('environment.', [System.StringComparison]::Ordinal)) { return $first }
+  if ([string]::Equals($Verb, 'task.launch', [System.StringComparison]::Ordinal) -or
+      [string]::Equals($Verb, 'task.kill', [System.StringComparison]::Ordinal)) { return $first }
+  return '*'
+}
+
 # The well-known SID for "Everyone". Layer A denies write access to it, because denying Everyone
 # covers every context that could open the file, including the automation one, without this process
 # having to know which account the harness runs as.

package/src/permission/index.js

@@ -192,7 +192,12 @@ function nextRuleId(document) {
   return `r-${String(max + 1).padStart(4, '0')}`
 }
 
-export function apply(ctx, config = {}) {
+export function apply(ctx, rawConfig) {
+  // `?? {}` rather than a default parameter: Cordis passes a row's config as `null` when the row declares
+  // none, and a default parameter only fires for `undefined`. This row happens to ship with a config, so
+  // it never hit the fault — but the fix belongs here too, or a deployment that trims the row's config
+  // takes the consent delegate down with it.
+  const config = rawConfig ?? {}
   const path = permissionPathOf(config)
   const auditLimit = config.auditLimit ?? AUDIT_LIMIT
 
@@ -339,6 +344,68 @@ export function apply(ctx, config = {}) {
     ctx.tools.register(spec)
   }
 
+  /**
+   * Ask the user before a DURABLE decision is written.
+   *
+   * The delegate's whole reason for existing is that the scripts cannot reach the approval UI: there is
+   * no write verb in the verb table precisely so that `permission.json` has exactly one writer, and that
+   * writer is supposed to be gated by a human. Until now the gate was only a sentence in this tool's
+   * description asking the model to behave — the enforcement was a request, not a check. This makes it a
+   * check.
+   *
+   * The Web composition already ships the answerer (`dsh-client-ui-approval`), so nothing here renders a
+   * prompt; it asks, and the client shows the banner. `allowed-once` is the seam's only grant, and for
+   * this purpose it means "yes, record this rule" — the rule's own persistence is what makes it durable,
+   * which is why a durable decision uses this seam while a one-shot verb call does not.
+   *
+   * Absence of the seam is reported rather than ignored: a rule that nobody approved must not be written
+   * quietly. A deployment that wants unattended grants has to say so by configuring `requireApproval:
+   * false`, which is a decision on the record instead of a default nobody chose.
+   */
+  async function approvedForDurableWrite(exec, { verb, target, decision, revoke }) {
+    if (config.requireApproval === false) return { granted: true, outcome: 'not-required' }
+    const approval = typeof ctx.get === 'function' ? ctx.get('approval') : undefined
+    if (approval === undefined) {
+      return {
+        granted: false,
+        outcome: 'unavailable',
+        detail: 'no approval service is loaded, so a durable decision cannot be confirmed by the user; set requireApproval: false in this row\'s config to grant unattended',
+      }
+    }
+    if (exec?.agent === undefined || exec?.agent === null) {
+      return {
+        granted: false,
+        outcome: 'unavailable',
+        detail: 'this call carries no agent, so there is no session to show the request in; a durable decision needs an interactive turn',
+      }
+    }
+    const verbLabel = revoke === true ? `revoke ${verb}` : `${decision} for ${verb}`
+    try {
+      const outcome = await approval.request({
+        agent: exec.agent,
+        toolName: revoke === true ? 'os_permission_revoke' : 'os_permission_grant',
+        ...exec.callId === undefined ? {} : { callId: exec.callId },
+        reason: `dsh-os wants to ${verbLabel} on ${target}`,
+        displayReason: {
+          en: revoke === true
+            ? `dsh-os wants to remove the stored rule for "${verb}".`
+            : `dsh-os wants to remember "${decision === 'allow-always' ? 'always allow' : 'always deny'}" for "${verb}" on ${target}.`,
+        },
+        ...exec.signal === undefined ? {} : { signal: exec.signal },
+      })
+      if (outcome === 'allowed-once') return { granted: true, outcome }
+      return {
+        granted: false,
+        outcome,
+        detail: outcome === 'rejected'
+          ? 'refused — note that a session policy of "never" refuses before any prompt is shown, so nothing was displayed to the user'
+          : 'no answerer accepted the request',
+      }
+    } catch (error) {
+      return { granted: false, outcome: 'unavailable', detail: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
   tool({
     name: 'os_permission_query',
     description:
@@ -384,8 +451,24 @@ export function apply(ctx, config = {}) {
       required: ['verb', 'target', 'decision'],
     },
     output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
-    async execute(args) {
-      return JSON.stringify(grant(args), null, 2)
+    async execute(args, exec) {
+      // The user decides before anything is written. A refusal is reported as a result rather than an
+      // exception, so the model can tell "the user said no" from "the tool broke".
+      const permission = await approvedForDurableWrite(exec, {
+        verb: args.verb,
+        target: args.target ?? '*',
+        decision: args.decision,
+      })
+      if (!permission.granted) {
+        return JSON.stringify({
+          ok: false,
+          written: false,
+          authorization: permission.outcome,
+          ...permission.detail === undefined ? {} : { reason: permission.detail },
+          note: 'permission.json was NOT modified.',
+        }, null, 2)
+      }
+      return JSON.stringify({ ...grant(args), authorizedBy: permission.outcome }, null, 2)
     },
   })
 
@@ -400,8 +483,25 @@ export function apply(ctx, config = {}) {
       required: ['ruleId'],
     },
     output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
-    async execute(args) {
-      return JSON.stringify(revoke({ ruleId: args.ruleId }), null, 2)
+    async execute(args, exec) {
+      // Revoking is a durable decision too — it removes a rule the user already agreed to, so it takes
+      // the same gate as writing one.
+      const permission = await approvedForDurableWrite(exec, {
+        verb: `rule ${args.ruleId}`,
+        target: args.ruleId,
+        decision: 'revoke',
+        revoke: true,
+      })
+      if (!permission.granted) {
+        return JSON.stringify({
+          ok: false,
+          written: false,
+          authorization: permission.outcome,
+          ...permission.detail === undefined ? {} : { reason: permission.detail },
+          note: 'permission.json was NOT modified.',
+        }, null, 2)
+      }
+      return JSON.stringify({ ...revoke({ ruleId: args.ruleId }), authorizedBy: permission.outcome }, null, 2)
     },
   })
 

package/src/plugin/index.js

@@ -24,10 +24,67 @@ import { resolveInvocation, runScript, searchedDirectory } from './invoke.js'
 
 export const name = 'dsh-os'
 
-/** The plugin is inert without the tool registry. */
+/** The plugin is inert without the tool registry; the approval seam is optional and read at use time. */
 export const inject = ['tools']
 
-export function apply(ctx, config = {}) {
+/**
+ * Parse an envelope, or undefined when the text is not one.
+ *
+ * Used only to READ the error code of a refusal. A caller that cannot parse it gets the text back
+ * unchanged, so a malformed envelope is never made worse by this.
+ */
+function parseEnvelope(text) {
+  try {
+    const parsed = JSON.parse(text)
+    return parsed !== null && typeof parsed === 'object' ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Ask the DSH approval seam for a one-shot decision on one call.
+ *
+ * A host plugin does NOT register an answerer to reach the user — the opposite is true. The Web
+ * composition already ships `dsh-client-ui-approval`, which answers `approval/request` and renders the
+ * banner ("tool X requests elevated execution" with Reject / Allow once). A plugin only has to ASK, and
+ * the client renders it. That is why this file carries no UI code for the decision.
+ *
+ * Three facts about the seam shape the code below, all read from `@deepseek-ai/dsh-user-approval`:
+ *
+ *   * `request()` reads `req.agent.session`, so a call with no agent THROWS rather than being refused
+ *     politely. The caller must not invoke it in that case, which is why `agent` is passed in and
+ *     checked here rather than being trusted.
+ *   * the only grant in the outcome vocabulary is `'allowed-once'`; `'rejected'`, `'cancelled'` and
+ *     `'unavailable'` all mean "no". They are reported distinctly so the caller can say which happened.
+ *   * a session whose policy is `never` resolves to `'rejected'` BEFORE the waterfall, so no prompt is
+ *     ever rendered. That is a deployment setting, not a fault in this code, and the message says so.
+ *
+ * The seam is consumed opportunistically with `ctx.get('approval')`, the same way `dsh-tools` does it: a
+ * deployment without the approval service keeps every verb that does not need a prompt.
+ */
+async function askApproval(ctx, { agent, callId, toolName, reason, displayReason, signal }) {
+  const approval = typeof ctx.get === 'function' ? ctx.get('approval') : undefined
+  if (approval === undefined) {
+    return { granted: false, outcome: 'unavailable', detail: 'no approval service is loaded in this deployment' }
+  }
+  if (agent === undefined || agent === null) {
+    return { granted: false, outcome: 'unavailable', detail: 'the call carries no agent, so there is no session to route an approval through' }
+  }
+  try {
+    const outcome = await approval.request({ agent, toolName, ...callId === undefined ? {} : { callId }, reason, displayReason, signal })
+    if (outcome === 'allowed-once') return { granted: true, outcome }
+    return { granted: false, outcome, detail: outcome === 'rejected' ? 'the request was refused (a session policy of "never" refuses before any prompt is shown)' : undefined }
+  } catch (error) {
+    return { granted: false, outcome: 'unavailable', detail: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+export function apply(ctx, rawConfig) {
+  // `?? {}` rather than a default parameter: Cordis passes a row's config as `null` when the row declares
+  // none, and a default parameter only fires for `undefined`. Every entry point in this package guards the
+  // same way, so a row whose config is trimmed degrades to defaults instead of failing to activate.
+  const config = rawConfig ?? {}
   const timeoutMs = config.timeoutMs ?? 120000
 
   ctx.tools.register({
@@ -89,18 +146,24 @@ export function apply(ctx, config = {}) {
 
       // The verb may be given as several words; the script resolves multi-word verbs itself, so it is
       // split here rather than guessed at.
-      const verbArgs = [...String(args.verb).trim().split(/\s+/)]
-      for (const value of args.arguments ?? []) verbArgs.push(String(value))
-      for (const flag of args.flags ?? []) verbArgs.push(String(flag))
-      if (args.allow === true) verbArgs.push('--allow')
+      const baseArgs = [...String(args.verb).trim().split(/\s+/)]
+      for (const value of args.arguments ?? []) baseArgs.push(String(value))
+      for (const flag of args.flags ?? []) baseArgs.push(String(flag))
 
-      const result = await runScript(invocation, verbArgs, timeoutMs, exec?.signal)
+      const runOnce = (withAllow) => runScript(
+        invocation,
+        withAllow ? [...baseArgs, '--allow'] : baseArgs,
+        timeoutMs,
+        exec?.signal,
+      )
+
+      let result = await runOnce(args.allow === true)
 
       if (result.timedOut) {
         throw new Error(`dsh-os verb "${args.verb}" timed out after ${timeoutMs}ms`)
       }
 
-      const text = result.stdout.trim()
+      let text = result.stdout.trim()
       if (text === '') {
         // An empty stdout would leave the caller with nothing to parse, so the exit code and the
         // captured diagnostics are reported instead of an empty success.
@@ -110,6 +173,51 @@ export function apply(ctx, config = {}) {
         )
       }
 
+      // A refusal that a user decision could actually resolve is turned into one, ONCE, in this same
+      // call: mutating verbs answer `E_PERMISSION` when they arrive without `--allow`, so the user is
+      // asked and the verb is retried with it. Asking is skipped when the request already carried
+      // `--allow`, because then the refusal came from somewhere a prompt cannot change.
+      if (args.allow !== true) {
+        const refusal = parseEnvelope(text)
+        if (refusal?.error?.code === 'E_PERMISSION') {
+          const decision = await askApproval(ctx, {
+            agent: exec?.agent,
+            callId: exec?.callId,
+            toolName: 'dsh_os',
+            reason: `dsh-os verb "${args.verb}" needs authorization`,
+            displayReason: {
+              en: `dsh-os wants to run "${args.verb}", which changes something on this machine.`,
+            },
+            signal: exec?.signal,
+          })
+          if (decision.granted) {
+            result = await runOnce(true)
+            if (result.timedOut) {
+              throw new Error(`dsh-os verb "${args.verb}" timed out after ${timeoutMs}ms after approval`)
+            }
+            text = result.stdout.trim()
+          } else if (decision.outcome !== 'unavailable' || decision.detail !== undefined) {
+            // Report the refusal as the typed envelope the caller already branches on, with the reason
+            // attached — a bare "no" from a prompt that was never shown would be indistinguishable
+            // from a verb that failed on its own.
+            return JSON.stringify({
+              ok: false,
+              verb: refusal.verb ?? String(args.verb).trim().replace(/\s+/g, '.'),
+              error: {
+                code: 'E_PERMISSION',
+                message: `"${args.verb}" was not authorized (approval: ${decision.outcome})`,
+                ...decision.detail === undefined ? {} : { hint: decision.detail },
+              },
+              meta: { ...refusal.meta, approval: decision.outcome },
+            })
+          }
+        }
+      }
+
+      if (text === '') {
+        throw new Error(`dsh-os verb "${args.verb}" produced no envelope after approval (exit ${result.code})`)
+      }
+
       // The envelope is returned verbatim, including when ok is false: a typed failure is a result the
       // caller must be able to read (error.code is authoritative), not an exception that loses it.
       return text

package/src/plugin/invoke.js

@@ -113,7 +113,11 @@ export const DEFAULT_SCRIPT_DIR = 'src/host/bin'
  * DSH_OS_POWERSHELL still overrides the executable. `'auto'` uses 7.6 only when both the artefact and
  * a pwsh executable are present, and falls back to 5.1 otherwise.
  */
-export function resolveInvocation(config = {}) {
+export function resolveInvocation(rawConfig) {
+  // `?? {}` rather than a default parameter. Cordis passes a row's config through as `null` when the row
+  // declares none, and a default parameter only fires for `undefined` — so `config.scriptPath` on that
+  // null threw and the plugin row failed to activate. Every caller may pass null.
+  const config = rawConfig ?? {}
   const explicit = config.scriptPath ? [config.scriptPath] : []
   const dir = config.scriptPath
     ? dirname(config.scriptPath)
@@ -192,7 +196,8 @@ export function resolveInvocation(config = {}) {
 }
 
 /** The directory an invocation would search, for error messages that name a real path. */
-export function searchedDirectory(config = {}) {
+export function searchedDirectory(rawConfig) {
+  const config = rawConfig ?? {}
   return config.scriptPath ?? join(PKG_ROOT, config.scriptDir ?? DEFAULT_SCRIPT_DIR)
 }
 

package/src/plugin/settings.js

@@ -110,9 +110,15 @@ export function writeSettings(file, settings) {
  * second one is evidence that the feature works.
  */
 export class SettingsService {
-  constructor(ctx, config = {}) {
+  constructor(ctx, config) {
     this.ctx = ctx
-    this.file = config.settingsPath ?? settingsPath()
+    // `config ?? {}` rather than a default parameter: Cordis passes the row's config as `null` when the
+    // row declares none, and a default parameter does not fire for null. This is exactly what made the
+    // shipped 0.1.5 fail to activate with "Cannot read properties of null (reading 'settingsPath')".
+    const resolved = config ?? {}
+    this.file = typeof resolved.settingsPath === 'string' && resolved.settingsPath.trim() !== ''
+      ? resolved.settingsPath
+      : settingsPath()
     this.settings = readSettings(this.file)
     this.activity = []
     this.listeners = new Set()
@@ -312,8 +318,11 @@ export function makeSettingsRoutes(service) {
  */
 export const name = 'dsh-os-settings'
 
-export function apply(ctx, config = {}) {
-  const service = new SettingsService(ctx, config)
+export function apply(ctx, rawConfig) {
+  // `?? {}` rather than a default parameter: Cordis passes a row's config as `null` when the row declares
+  // none, and a default parameter only fires for `undefined`. This row ships WITHOUT a config, which is
+  // what made the shipped 0.1.5 fail with "Cannot read properties of null (reading 'settingsPath')".
+  const service = new SettingsService(ctx, rawConfig ?? {})
 
   // `ctx.provide` REGISTERS the service and returns a disposer; `ctx.set` only overwrites the value of a
   // service that was already provided, and calling it first throws

package/src/plugin/takeover.js

@@ -388,7 +388,11 @@ function eligible(tool, args) {
   }
 }
 
-export function apply(ctx, config = {}) {
+export function apply(ctx, rawConfig) {
+  // `?? {}` rather than a default parameter: Cordis passes a row's config as `null` when the row declares
+  // none, and a default parameter only fires for `undefined`, so the first property read threw and the
+  // row never activated. This row is shipped WITHOUT a config, so it hit exactly that.
+  const config = rawConfig ?? {}
   const toolTimeoutMs = config.timeoutMs ?? 120000
   // Mirrors the `tool-fs` row's `readLimit` (2000 by default): the interception must not quietly apply
   // a different window size than the built-in it replaced.

package/src/plugin/workflow.js

@@ -1405,12 +1405,17 @@ export function workflowToolDefinition(handlers) {
   }
 }
 
-export function apply(ctx, config = {}) {
-  const root = typeof config.workflowRoot === 'string' && config.workflowRoot.trim() !== ''
-    ? config.workflowRoot
+export function apply(ctx, config) {
+  // `config ?? {}` rather than a `config = {}` default parameter, because the two are NOT equivalent:
+  // a default parameter only fires for `undefined`, and Cordis hands the row's config through as `null`
+  // when the row declares none. The shipped 0.1.5 read `config.workflowRoot` off that null and the row
+  // failed to activate with "Cannot read properties of null".
+  const resolved = config ?? {}
+  const root = typeof resolved.workflowRoot === 'string' && resolved.workflowRoot.trim() !== ''
+    ? resolved.workflowRoot
     : workflowRoot()
-  const autoCompact = config.autoCompact !== false
-  const maxCheckpoints = Number.isInteger(config.maxCheckpoints) && config.maxCheckpoints > 0 ? config.maxCheckpoints : 20
+  const autoCompact = resolved.autoCompact !== false
+  const maxCheckpoints = Number.isInteger(resolved.maxCheckpoints) && resolved.maxCheckpoints > 0 ? resolved.maxCheckpoints : 20
 
   // The engine's own automatic compaction is named in the checkpoint result rather than invoked: this
   // plugin holds no session handle, and a call into a service whose context contract is not published
@@ -1446,14 +1451,28 @@ export function apply(ctx, config = {}) {
 
   if (typeof ctx.tools?.register === 'function') ctx.tools.register(workflowToolDefinition(handlers))
 
-  // The prompt half is registered only when the registry is present, so a deployment without it loses
-  // the section rather than the feature. The text is a constant: no state is read, nothing is looked up,
-  // and the model's cached prefix survives every phase of every workflow. See SECTION_TEXT.
-  if (typeof ctx.systemPrompt?.section === 'function') {
-    ctx.systemPrompt.section({
-      name: 'dsh-os:workflow',
-      order: sectionOrder(ctx.systemPrompt),
-      text: SECTION_TEXT,
+  // The prompt half is registered through `ctx.inject`, NOT by reading `ctx.systemPrompt` directly.
+  //
+  // Reading it directly is what broke the shipped 0.1.5: Cordis resolves a service property through an
+  // enforcing proxy, so an undeclared service does not read as `undefined` — it THROWS
+  //   Error: cannot get property "systemPrompt" without inject
+  // and a guard of the form `typeof ctx.systemPrompt?.section === 'function'` never gets to run, because
+  // the property access itself is the throw. The row then failed to activate entirely, losing the tool
+  // as well as the section.
+  //
+  // `ctx.inject` is the first-party pattern for an optional service (`dsh-tool-fs` registers its image
+  // tool the same way): the callback runs when the service is present and unwinds when it goes away, and
+  // a deployment without a system prompt keeps the tool instead of losing everything.
+  //
+  // The text is a constant: no state is read, nothing is looked up, and the model's cached prefix
+  // survives every phase of every workflow. See SECTION_TEXT.
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['systemPrompt'], (scoped) => {
+      scoped.systemPrompt.section({
+        name: 'dsh-os:workflow',
+        order: sectionOrder(scoped.systemPrompt),
+        text: SECTION_TEXT,
+      })
     })
   }