Release v0.2.0 [skip release] [skip actions]

The per-session scope the host half now reads had no writer. This is it: a
crosshair on the composer tool row, present only in sessions running the facet
preset, opening a panel that sets the focus and the paths allowed outside it.

The gate is the session's own `agentPreset` projection rather than anything
inferred from the URL or from the plugin being installed, so a control for a
plugin that is not running never appears.

It writes through the settings document — the same one the plugin card edits —
because `settings.mutate` accepts a path under a volatile node and refuses
anything else. That is what makes the split real rather than aspirational: the
agent has no write path to `scopes`, and the panel's write is the only one that
can widen a session.

The panel also carries the mode details and the usage notes, which the preset
picker's guide dialog cannot show for a preset no core package ships — its
guide table holds four shipped ids and is looked up only for built-ins.

Also adds `@deepseek-ai/dsh-client-ui-conversation` to the client half's inject
list: registering into `conversation.input.left` is a dependency on the package
that declares it, and `slots.inject` waits for a slot rather than creating one,
so naming another package's slot without loading it first registers nothing —
silently, because nothing errors.

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 Every release, newest first, generated from the commits in each release.
 
+## v0.2.0 — 2026-09-27
+
+### Added
+
+- set a conversation's scope from the composer, where the agent cannot reach
+- scope a session from a declaration the agent cannot widen
+
+
+## v0.1.4 — 2026-09-26
+
+### Fixed
+
+- say so when a session has no approval channel to ask through
+
+
+## v0.1.3 — 2026-09-26
+
+### Fixed
+
+- put the settings card on the Plugins page with a browser half
+
+
+## v0.1.2 — 2026-09-26
+
+### Fixed
+
+- show the settings card, and make an edit actually take effect
+
+
 ## v0.1.1 — 2026-09-26
 
 ### Documented

README.md

@@ -103,23 +103,65 @@ first turn has run, so choose it when you start the conversation.
 
 ### Configure it in your profile, not in the package
 
-The host row's config is where this deployment's facts belong — the profile's own
+The host row's config is where this *deployment's* facts belong — the profile's
-`cordis.patch.yml`:
+own `cordis.patch.yml`:
 
 ```yaml
 - id: facet-policy
   name: dsh-facet
   config:
     mode: ask              # ask | deny | off
-    extraRoots:            # always in scope, in every session
+    extraRoots: []         # optional: a seed of paths always in scope, every session
-      - ../../shared       # relative to each session's own directory
 ```
 
-`extraRoots` is for code a module legitimately always depends on. Anything you
+Both are also on the plugin's card under **Plugins** in the Web UI, which is the
-grant by hand is per-conversation and is never persisted — "this session may
+same layer reached a different way: a settings write rewrites this entry in the
-also see `src/shared`" is a statement about one conversation, and writing it down
+profile patch rather than storing anything new. An edit there is live — the guard
-would quietly widen every future one, which is the failure this plugin exists to
+reads `mode` and `extraRoots` on every call, so a change decides the next file
-prevent.
+call without a restart.
+
+The one exception is `off`. Choosing it while a session is running stops the guard
+immediately and empties the binding on the next request, because the binding is a
+callback. The rule is not: it was registered at load as a plain string, and
+nothing unregisters it, so the prompt would go on stating a rule that nothing
+enforces. An `off` *deployment* is therefore settled at load — set it in the
+patch. `ask` and `deny` swap freely in both directions.
+
+`sectionOrder` and `contextOrder` are deliberately absent from the card. They
+place the rule and the binding among the other prompt sections, which is decided
+once at load, and no section is re-ordered without a remount.
+
+### Per-session scope, and who gets to decide it
+
+Scope has two layers, and the split is the point:
+
+| layer | what it is | who can write it |
+|---|---|---|
+| **the user's declaration** | `scopes[<session id>]` in this row's config — a `focus` and a list of `extras` | only the context panel, through the settings service |
+| **the agent's** | a narrowing `focus` and any session grants, held in memory | the agent, and only ever to *reduce* |
+
+The effective root is the agent's narrowing while it still sits inside your root,
+and your root otherwise. So an agent that goes wrong cannot widen its own scope,
+and `facet action=reset` returns it to what you declared rather than to the
+session directory — landing on the directory would have made `reset` a widening.
+
+You set the declaration from the **crosshair button on the composer tool row**,
+which appears only in sessions running the `facet` preset. It shows the focus and
+the allowed paths, adds and removes them, and carries the mode details and usage
+notes that the preset picker's guide dialog cannot show for a preset no core
+package ships. Writes go to the profile patch, so reopening a chat gives back the
+scope it had.
+
+Because the panel owns widening, `facet action=add` is the *other* path and the
+narrower one: it is gated on an approval channel, and a deployment with none — the
+`danger-full-access` permission preset sets `approval: never` — refuses it before
+anyone is asked. In that deployment the panel is the only way to widen, which is
+exactly what the binding tells the agent.
+
+`extraRoots` is only a seed now. Before per-session scope it was the *only* way to
+widen anything, which meant "this conversation needs the entity folder" had to be
+written as a fact about every conversation in every workspace. It is for paths a
+deployment genuinely always wants, and it is empty by default.
 
 ## The compaction row
 
@@ -171,12 +213,15 @@ Honest boundaries, because each one is a decision rather than an oversight:
 
 Verified:
 
-- 42 tests (`npm test`) over the scope algebra, the policy state, and the guard —
+- 73 tests (`npm test`) over the scope algebra, the policy state, the guard, and
-  including that containment is decided on canonical targets (a symlink inside
+  the browser half — including that containment is decided on canonical targets
-  the facet pointing outside it is refused), that a prefix is not a parent
+  (a symlink inside the facet pointing outside it is refused), that a prefix is
-  (`/a/room` does not contain `/a/roommate`), that a malformed tool call never
+  not a parent (`/a/room` does not contain `/a/roommate`), that a malformed tool
-  makes the guard throw, and that every `facet` result satisfies the tool's own
+  call never makes the guard throw, that a live `mode` edit decides the next call
-  declared output schema.
+  without the guard being remounted, that an agent narrowing the user has since
+  narrowed past is dropped rather than honoured, that `reset` lands on the
+  declared scope rather than the session directory, and that every `facet` result
+  satisfies the tool's own declared output schema.
 - The bundle's patch layers parse, merge and land correctly against the real
   profile: `dsh --profile web --patch ./cordis.patch.yml --patch
   ./presets/facet.patch.yml --dump-config` shows `facet-policy`, `preset-facet`,
@@ -246,14 +291,37 @@ it.
 
 ```
 index.js                     host row: the policy, published as ctx.facetPolicy
+client/client.js             browser half: the settings card, and the context panel
 lib/policy.js                the stateful half — scope resolution, grants
 lib/scope.js                 the pure half — argument extraction, text, reasons
 lib/guard.js                 preset row: rule, binding, tool, pre-execute guard
 presets/facet.patch.yml      the `facet` agent preset
 presets/standard-compaction.patch.yml   optional: the same budget for `standard`
-test/                        42 tests
+test/                        73 tests
 ```
 
+`client/client.js` is a browser half rather than a module the host imports, and
+it is not optional decoration. The Plugins page does not build a card from a
+`Config` schema — it draws only what browser halves register into the slots it
+declares. `volatile()` on the host schema makes the namespace *servable*
+(`settings.describe()` drops an entry with none, and the card registers only
+while the namespace is served), but a schema alone puts nothing on the page.
+
+The two keys in that file are deliberately different strings, and that is the
+easy mistake to make here: the settings **document** is filed under the profile
+entry id (`facet-policy`, the row's `id` in `cordis.patch.yml`) while the
+**card** is keyed by the package name (`dsh-facet`). Every sibling plugin
+happens to name them identically, so binding the form to the wrong one produces
+a card that renders, saves, and writes nowhere. `test/client.test.js` pins both.
+
+The same file carries the context panel, registered into
+`conversation.input.left` — the composer tool row — and gated on the session's own
+`agentPreset` projection, so it appears only where the facet is actually in force.
+That gate is why `scopes` is `volatile()` in the host schema: `settings.mutate`
+refuses a path that is not under a volatile node, and refusing is exactly right —
+the panel is the only writer, and a plugin that could not serve the namespace
+would be a control that silently stored nothing.
+
 ## Also in this repository
 
 - [`facet-preset.md`](../facet-preset.md) — the design note this was built from,

client/client.js

@@ -0,0 +1,648 @@
+/**
+ * dsh-facet — the browser half.
+ *
+ * **Why this file exists when the host half already declares the schema.** The
+ * Plugins page does not generate a card from a `Config` schema. It draws whatever
+ * browser halves register into the slots it declares, and `plugins.bundle.config`
+ * is the seat for one package's own configuration. Marking a field `volatile()`
+ * makes the Host *serve* that namespace — `settings.describe()` drops an entry
+ * with no volatile field, and `configForms.whileServed()` below refuses to
+ * register a page the Host does not serve — but serving it is not drawing it. No
+ * browser half means no card, however the schema is marked.
+ *
+ * **The two keys below are not the same string, and that is the trap.** Every
+ * other plugin in this installation happens to name them identically, so the
+ * distinction never shows up until it does:
+ *
+ *   * the settings DOCUMENT is filed under the plugin's profile entry id —
+ *     `facet-policy`, the `id` of this bundle's row in `cordis.patch.yml`.
+ *     Exporting `Config` from `index.js` is the registration; this is the key
+ *     `configForms.get()` addresses.
+ *   * the CARD is filed under the bundle's PACKAGE NAME — `dsh-facet`. That is
+ *     what the Plugins page dispatches `plugins.bundle.config` by, and it goes on
+ *     the bundle's own page between its description and its rows.
+ *
+ * Bind the form to the wrong one and the card renders, saves, and writes nowhere.
+ *
+ * **Loadable without a bundler.** `react` and the primitives package are both in
+ * the boot seed table; the settings document and the slot ledgers arrive as
+ * Cordis services or slot props. Nothing here reaches into another plugin's
+ * bundle.
+ */
+
+window.__ModuleLoader__.load({
+  id: 'dsh-facet',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+
+    const react = require('react')
+    const primitives = require('@deepseek-ai/dsh-client-ui-primitives')
+
+    const { Modal, SegmentedControl, SettingsForm, SettingsFormModel, SettingsValueField } = primitives
+
+    const h = react.createElement
+
+    /** The settings document's key: this bundle's row id, not its package name. */
+    const SETTINGS_ENTRY = 'facet-policy'
+
+    /** The card's key: the bundle's package name, not its row id. */
+    const BUNDLE_CONFIG_KEY = 'dsh-facet'
+
+    /** The modes the host schema accepts, in the order the control offers them. */
+    const MODES = ['ask', 'deny', 'off']
+
+    const TITLE = 'Facet'
+    const DESCRIPTION = 'How a call outside the session\u2019s own folder is handled, and which paths are always in scope.'
+
+    const OVERRIDDEN_LABEL = 'Overridden'
+    const RESET_LABEL = 'Reset to default'
+
+    const MODE_LABELS = { ask: 'Ask', deny: 'Deny', off: 'Off' }
+    const MODE_OPTIONS = MODES.map((value) => ({ value, label: MODE_LABELS[value] }))
+
+    const labelStyle = {
+      display: 'block',
+      marginBottom: '6px',
+      fontSize: '13px',
+      fontWeight: 500,
+      color: 'var(--dsw-alias-label-primary)',
+    }
+    const hintStyle = {
+      margin: '6px 0 0',
+      fontSize: '12px',
+      lineHeight: '18px',
+      color: 'var(--dsw-alias-label-tertiary)',
+    }
+    const badgeStyle = {
+      marginLeft: '8px',
+      fontSize: '11px',
+      fontWeight: 400,
+      color: 'var(--dsw-alias-label-tertiary)',
+    }
+
+    /**
+     * A finite-choice field, staged as the chosen value.
+     *
+     * The primitives ship `settingsNumberField` and `settingsTextField` and
+     * deliberately stop there: only the owning plugin knows what its own
+     * vocabulary is. An unrecognised draft returns `undefined`, which marks the
+     * field invalid and blocks the save rather than quietly coercing a typo into
+     * a mode the schema would reject at the Host anyway.
+     *
+     * @param {string} field - field name inside the namespace section.
+     * @param {readonly string[]} choices - the values the host schema accepts.
+     */
+    function settingsChoiceField(field, choices) {
+      return {
+        field,
+        format: (value) => (typeof value === 'string' && choices.includes(value) ? value : ''),
+        parse: (text) => {
+          const normalised = String(text).trim().toLowerCase()
+          if (normalised === '') return { kind: 'clear' }
+          if (choices.includes(normalised)) return { kind: 'set', value: normalised }
+          return undefined
+        },
+      }
+    }
+
+    /**
+     * A whole-list field: comma or newline separated in the control, an array of
+     * non-empty strings in the document.
+     *
+     * Empty stages a clear rather than an empty array. The schema's own default
+     * is `[]`, so writing one would shadow a deployment's composed default with
+     * nothing and leave the field marked overridden when the user meant to
+     * remove their override.
+     *
+     * @param {string} field - field name inside the namespace section.
+     */
+    function settingsListField(field) {
+      return {
+        field,
+        format: (value) => (Array.isArray(value) ? value.join(', ') : ''),
+        parse: (text) => {
+          const parts = String(text)
+            .split(/[,\n]/)
+            .map((part) => part.trim())
+            .filter((part) => part !== '')
+          return parts.length === 0 ? { kind: 'clear' } : { kind: 'set', value: parts }
+        },
+      }
+    }
+
+    /** The facet page's staged form over the composed `facet-policy` entry. */
+    var FacetCardController = class {
+      /**
+       * @param {object} scope - the shared configuration form for `facet-policy`.
+       */
+      constructor(scope) {
+        this.form = new SettingsFormModel(scope, [
+          settingsChoiceField('mode', MODES),
+          settingsListField('extraRoots'),
+        ])
+        this.store = this.form.bind(() => this.projection())
+      }
+
+      /** @returns {object} the shell's shared state plus this card's two controls. */
+      projection() {
+        return {
+          ...this.form.shell(),
+          mode: this.form.field('mode'),
+          extraRoots: this.form.field('extraRoots'),
+        }
+      }
+
+      /**
+       * Build the face the slot registration injects.
+       *
+       * The `hooks` key becomes the component's `useFacetCard` prop — the slot
+       * runtime turns each entry into a bound hook — and the actions supply
+       * `edit`, `resetField`, `save` and `discard` beside it.
+       *
+       * @returns {object} the snapshot hook and the form actions.
+       */
+      inject() {
+        return { hooks: { facetCard: this.store }, ...this.form.actions() }
+      }
+
+      /** Release the form subscription. */
+      dispose() {
+        this.form.dispose()
+      }
+    }
+
+    /**
+     * Render the facet card's one-liner or its settings form, as the page asks.
+     *
+     * @param {object} props - the view asked for, the bound snapshot, and the form actions.
+     */
+    function FacetCard(props) {
+      if (props.view === 'summary') return DESCRIPTION
+
+      const state = props.useFacetCard((snapshot) => snapshot)
+      const disabled = !state.writable || state.saving
+
+      // The mode is editable as a segmented control rather than through
+      // `SettingsValueField`, because a three-value vocabulary in a free-text box
+      // invites a typo the field can only answer with "invalid". It is still the
+      // same staged draft underneath — the control calls the form's own `edit`,
+      // so nothing is written until Save.
+      const mode = h(
+        'div',
+        { key: 'mode' },
+        h(
+          'label',
+          { style: labelStyle, htmlFor: 'facet-mode' },
+          'Enforcement mode',
+          state.mode.overridden ? h('span', { style: badgeStyle }, OVERRIDDEN_LABEL) : null,
+        ),
+        h(SegmentedControl, {
+          id: 'facet-mode',
+          value: state.mode.text === '' ? 'ask' : state.mode.text,
+          options: MODE_OPTIONS,
+          onChange: (next) => props.edit('mode', next),
+          label: 'Enforcement mode',
+          disabled,
+        }),
+        h(
+          'p',
+          { style: hintStyle },
+          'Ask puts each call outside the facet to you as a question. Deny refuses it. Off disables enforcement while leaving the preset in place — useful for telling a scoping problem from an unrelated one.',
+        ),
+      )
+
+      const extraRoots = h(SettingsValueField, {
+        key: 'extraRoots',
+        id: 'facet-extra-roots',
+        label: 'Standing grants',
+        hint: 'Paths always in scope, in every session — shared types, a common test harness. Separate them with commas. Relative paths resolve against each session\u2019s own directory, so the same list is meaningful in every workspace.',
+        text: state.extraRoots.text,
+        overridden: state.extraRoots.overridden,
+        invalid: state.extraRoots.invalid,
+        overriddenLabel: OVERRIDDEN_LABEL,
+        resetLabel: RESET_LABEL,
+        invalidLabel: 'Enter one or more paths, separated by commas.',
+        disabled,
+        onEdit: (text) => props.edit('extraRoots', text),
+        onReset: () => props.resetField('extraRoots'),
+      })
+
+      return h(
+        SettingsForm,
+        {
+          labels: {
+            unavailable: 'This plugin is not loaded, so it cannot be configured right now.',
+            readOnly: 'This deployment stores settings read-only.',
+            saveFailed: 'The deployment did not accept these values; they were left for you to correct.',
+            save: 'Save',
+            saving: 'Saving\u2026',
+          },
+          state,
+          onSave: props.save,
+          onDiscard: props.discard,
+          // Column rather than a bare array, so the two controls keep the form's
+          // own spacing instead of sitting flush against each other.
+          children: h('div', { style: { display: 'flex', flexDirection: 'column', gap: '18px' } }, mode, extraRoots),
+        },
+      )
+    }
+
+    /**
+     * The preset id whose sessions get a context button.
+     *
+     * A session records its preset as a projection value, so the button can
+     * appear exactly where the facet is in force and stay out of the way
+     * everywhere else. Rendering it unconditionally would put a control for a
+     * plugin that is not running on every conversation in the deployment.
+     */
+    const FACET_PRESET = 'facet'
+
+    /** The composer tool row's entry id, and the button's accessible name. */
+    const CONTEXT_ENTRY_ID = 'facet-context'
+    const CONTEXT_LABEL = 'Facet context'
+
+    /** The scope one session has declared, normalised, or an empty declaration. */
+    function declaredFor(snapshot, sessionId) {
+      const all = snapshot?.value?.scopes
+      const mine = all !== null && typeof all === 'object' ? all[sessionId] : undefined
+      const entry = mine !== null && typeof mine === 'object' ? mine : {}
+      return {
+        focus: typeof entry.focus === 'string' ? entry.focus : '',
+        extras: Array.isArray(entry.extras) ? entry.extras.filter((path) => typeof path === 'string') : [],
+      }
+    }
+
+    /**
+     * Write one session's whole declaration.
+     *
+     * One path, one write: the panel always supplies the complete declaration it
+     * wants, so a queued edit can never half-apply and leave a session scoped to
+     * something nobody chose. An empty declaration is removed rather than stored,
+     * so a session the user has finished with leaves no residue in the profile
+     * patch — and so clearing both fields means "the session directory", which is
+     * the schema's own default rather than a stored empty override.
+     *
+     * @returns {Promise<boolean>} whether the Host accepted the write.
+     */
+    function writeDeclaration(form, sessionId, next) {
+      const focus = typeof next.focus === 'string' ? next.focus.trim() : ''
+      const extras = (next.extras ?? []).map((path) => String(path).trim()).filter((path) => path !== '')
+      const value = {
+        ...(focus === '' ? {} : { focus }),
+        ...(extras.length === 0 ? {} : { extras }),
+      }
+      const op =
+        Object.keys(value).length === 0
+          ? { op: 'unset', path: ['scopes', sessionId] }
+          : { op: 'set', path: ['scopes', sessionId], value }
+      return Promise.resolve(form.mutate([op]))
+    }
+
+    /** Shared control styling, so the panel reads as part of the product. */
+    const controlStyle = {
+      boxSizing: 'border-box',
+      height: '32px',
+      padding: '0 10px',
+      fontSize: '13px',
+      fontFamily: 'inherit',
+      color: 'var(--dsw-alias-label-primary)',
+      background: 'var(--dsw-alias-bg-layer-3)',
+      border: '0.5px solid var(--dsw-alias-border-l4)',
+      borderRadius: 'var(--dsw-radius-md)',
+    }
+    const quietButtonStyle = {
+      ...controlStyle,
+      cursor: 'pointer',
+      color: 'var(--dsw-alias-label-secondary)',
+      background: 'transparent',
+    }
+    const sectionTitleStyle = {
+      margin: '0 0 6px',
+      fontSize: '13px',
+      fontWeight: 600,
+      color: 'var(--dsw-alias-label-primary)',
+    }
+    const bodyStyle = { margin: '0 0 14px', fontSize: '12.5px', lineHeight: '19px', color: 'var(--dsw-alias-label-secondary)' }
+    const listedStyle = { ...bodyStyle, margin: '4px 0 0', fontFamily: 'var(--dsw-font-mono, ui-monospace, monospace)' }
+
+    /** The crosshair that marks the button: a scope, not a setting. */
+    const CONTEXT_GLYPH = h(
+      'svg',
+      { width: 15, height: 15, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': 'true' },
+      h('circle', { cx: 8, cy: 8, r: 3.2, stroke: 'currentColor', strokeWidth: 1.3 }),
+      h('path', {
+        d: 'M8 1.2v2.6M8 12.2v2.6M1.2 8h2.6M12.2 8h2.6',
+        stroke: 'currentColor',
+        strokeWidth: 1.3,
+        strokeLinecap: 'round',
+      }),
+    )
+
+    /**
+     * The facet context panel: what this conversation may see, and who decides.
+     *
+     * This is the only surface that writes per-session scope. The agent has no
+     * write path to it — not a narrow one, none — which is what makes "the user
+     * decides what is in scope" a property of the system rather than of the
+     * agent's instructions.
+     *
+     * @param {object} props - the bound form, the session, and the close command.
+     */
+    function FacetContextPanel(props) {
+      const { form, sessionId, mode, onClose } = props
+
+      // `form` is the settings document for `facet-policy`, already a store: the
+      // panel renders whatever the Host last accepted, including a write from
+      // another tab.
+      const snapshot = react.useSyncExternalStore(
+        (listener) => form.subscribe(listener),
+        () => form.getSnapshot(),
+      )
+      const declared = declaredFor(snapshot, sessionId)
+      const [focusDraft, setFocusDraft] = react.useState(declared.focus)
+      const [extraDraft, setExtraDraft] = react.useState('')
+      const [failure, setFailure] = react.useState('')
+      const disabled = snapshot.writable !== true
+
+      const write = (next) => {
+        writeDeclaration(form, sessionId, next).then(
+          (ok) => setFailure(ok ? '' : 'The deployment did not accept that change.'),
+          () => setFailure('The deployment did not accept that change.'),
+        )
+      }
+
+      const rows = declared.extras.map((path) =>
+        h(
+          'li',
+          { key: path, style: { display: 'flex', alignItems: 'center', gap: '8px', marginTop: '6px' } },
+          h('code', { style: { ...listedStyle, margin: 0, flex: 1, wordBreak: 'break-all' } }, path),
+          h(
+            'button',
+            {
+              type: 'button',
+              style: { ...quietButtonStyle, height: '26px' },
+              disabled,
+              onClick: () => write({ ...declared, extras: declared.extras.filter((other) => other !== path) }),
+            },
+            'Remove',
+          ),
+        ),
+      )
+
+      return h(
+        Modal,
+        { open: true, onClose, title: CONTEXT_LABEL, closeLabel: 'Close', description: `Session ${sessionId}` },
+        h(
+          'div',
+          null,
+          h('h3', { style: sectionTitleStyle }, 'What this conversation may see'),
+          h(
+            'p',
+            { style: bodyStyle },
+            'The agent works inside the focus folder. Anything it needs beyond that is listed below, and the agent can narrow the focus on its own but can never widen it — only you can, here.',
+          ),
+
+          h('label', { style: sectionTitleStyle, htmlFor: 'facet-focus' }, 'Focus'),
+          h(
+            'div',
+            { style: { display: 'flex', gap: '8px' } },
+            h('input', {
+              id: 'facet-focus',
+              type: 'text',
+              style: { ...controlStyle, flex: 1 },
+              placeholder: 'the folder the session started in',
+              value: focusDraft,
+              disabled,
+              'data-modal-autofocus': true,
+              onChange: (event) => setFocusDraft(event.target.value),
+              onKeyDown: (event) => {
+                if (event.key !== 'Enter') return
+                event.preventDefault()
+                write({ ...declared, focus: focusDraft })
+              },
+            }),
+            h(
+              'button',
+              { type: 'button', style: quietButtonStyle, disabled, onClick: () => write({ ...declared, focus: focusDraft }) },
+              'Set',
+            ),
+            h(
+              'button',
+              {
+                type: 'button',
+                style: quietButtonStyle,
+                disabled,
+                onClick: () => {
+                  setFocusDraft('')
+                  write({ ...declared, focus: '' })
+                },
+              },
+              'Clear',
+            ),
+          ),
+          h('p', { style: bodyStyle }, 'Relative to the session folder, or absolute. Empty means the session folder itself.'),
+
+          h('h3', { style: { ...sectionTitleStyle, marginTop: '18px' } }, 'Also allowed'),
+          declared.extras.length === 0
+            ? h('p', { style: bodyStyle }, 'Nothing yet. Shared types, project docs, or a sibling folder go here.')
+            : h('ul', { style: { listStyle: 'none', margin: 0, padding: 0 } }, rows),
+          h(
+            'div',
+            { style: { display: 'flex', gap: '8px', marginTop: '10px' } },
+            h('input', {
+              id: 'facet-extra',
+              type: 'text',
+              style: { ...controlStyle, flex: 1 },
+              placeholder: 'src/shared, ../../CONTROLLER.md',
+              value: extraDraft,
+              disabled,
+              onChange: (event) => setExtraDraft(event.target.value),
+              onKeyDown: (event) => {
+                if (event.key !== 'Enter') return
+                event.preventDefault()
+                if (extraDraft.trim() === '') return
+                write({ ...declared, extras: [...declared.extras, extraDraft] })
+                setExtraDraft('')
+              },
+            }),
+            h(
+              'button',
+              {
+                type: 'button',
+                style: quietButtonStyle,
+                disabled,
+                onClick: () => {
+                  if (extraDraft.trim() === '') return
+                  write({ ...declared, extras: [...declared.extras, extraDraft] })
+                  setExtraDraft('')
+                },
+              },
+              'Add',
+            ),
+          ),
+          h('p', { style: bodyStyle }, 'Relative to the session folder, or absolute — anything the session needs beyond the focus.'),
+
+          failure === '' ? null : h('p', { style: { ...bodyStyle, color: 'var(--dsw-alias-state-error-primary)' } }, failure),
+          h(
+            'p',
+            { style: { ...bodyStyle, marginTop: '18px' } },
+            `Changes take effect on the next tool call. Deployment mode: ${mode ?? 'ask'}.`,
+          ),
+
+          h('h3', { style: { ...sectionTitleStyle, marginTop: '18px' } }, 'Mode details'),
+          h(
+            'p',
+            { style: bodyStyle },
+            'The mode is set on the plugin card under Plugins, and applies to every session: ' +
+              '"ask" puts a call outside the facet to you as a question; "deny" refuses it outright; ' +
+              '"off" disables enforcement while leaving the preset mounted. Where the deployment has no approval ' +
+              'channel — as here, under the danger-full-access permission preset — "ask" cannot actually reach you, ' +
+              'so an out-of-facet call is refused and this panel is the way to widen the scope.',
+          ),
+          h('h3', { style: sectionTitleStyle }, 'How to use'),
+          h(
+            'ol',
+            { style: { ...bodyStyle, paddingLeft: '18px' } },
+            h('li', { style: { marginBottom: '6px' } }, 'Start the chat in the repository you want to work in.'),
+            h('li', { style: { marginBottom: '6px' } }, 'Set Focus to the one folder this conversation is about.'),
+            h(
+              'li',
+              { style: { marginBottom: '6px' } },
+              'Add what it needs beyond that — shared types, project docs, a folder it will create a sibling in.',
+            ),
+            h('li', null, 'Let the agent narrow as the work settles; it will ask you before it needs anything more.'),
+          ),
+        ),
+      )
+    }
+
+    /**
+     * The composer tool row's button, and the panel it opens.
+     *
+     * Present only for a session running the facet preset, which is what "shows
+     * up when in facet mode" means mechanically: the session's own projection
+     * says which preset it runs, so nothing has to be inferred from the URL or
+     * from the plugin being installed.
+     *
+     * @param {object} props - slot props: the session, `useSessions`, and the form.
+     */
+    function FacetContextButton(props) {
+      const { sessionId, useSessions, form } = props
+
+      // Called before the early return, so the hook order is stable across the
+      // sessions that do and do not run the facet.
+      const preset = useSessions((state) => state.byId[sessionId]?.projectionValues?.agentPreset)
+      const [open, setOpen] = react.useState(false)
+
+      if (preset !== FACET_PRESET) return null
+
+      return h(
+        react.Fragment,
+        null,
+        h(
+          'button',
+          {
+            type: 'button',
+            'aria-label': CONTEXT_LABEL,
+            'aria-expanded': open,
+            title: `${CONTEXT_LABEL} — what this conversation may see`,
+            onClick: () => setOpen((value) => !value),
+            style: {
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: '28px',
+              height: '28px',
+              padding: 0,
+              cursor: 'pointer',
+              color: open ? 'var(--dsw-alias-label-primary)' : 'var(--dsw-alias-label-secondary)',
+              background: open ? 'var(--dsw-alias-interactive-bg-hover)' : 'transparent',
+              border: 0,
+              borderRadius: 'var(--dsw-radius-sm)',
+            },
+          },
+          CONTEXT_GLYPH,
+        ),
+        // Mounted only while open, so each visit starts from what the Host holds
+        // rather than from a draft left over from the last one.
+        open ? h(FacetContextPanel, { ...props, onClose: () => setOpen(false) }) : null,
+      )
+    }
+
+    /**
+     * Mount the facet settings card while the Host serves its namespace.
+     *
+     * `whileServed` is the gate that makes the `volatile()` markers load-bearing:
+     * the card is registered only while `facet-policy` appears in the Host's
+     * served namespaces. An unserved namespace would be a control that silently
+     * writes nowhere, so it registers nothing at all.
+     *
+     * @param {object} ctx - the browser plugin context.
+     */
+    function apply(ctx) {
+      // `inject` rather than a required dependency, so a deployment that composed
+      // no settings provider loses the card and keeps everything else this bundle
+      // contributes.
+      ctx.inject(['configForms'], (scoped) => {
+        const form = scoped.configForms.get(SETTINGS_ENTRY)
+        const card = new FacetCardController(form)
+        scoped.effect(() => () => card.dispose(), 'dsh-facet: settings form')
+
+        scoped.effect(
+          () =>
+            scoped.configForms.whileServed([SETTINGS_ENTRY], () =>
+              scoped.slots.inject('plugins.bundle.config', () =>
+                scoped.slots.register(
+                  {
+                    name: 'plugins.bundle.config',
+                    key: BUNDLE_CONFIG_KEY,
+                    inject: () => card.inject(),
+                  },
+                  FacetCard,
+                ),
+              ),
+            ),
+          'dsh-facet: settings page',
+        )
+
+        // The context button rides the same form, so the panel and the plugin
+        // card can never disagree about what the document holds.
+        scoped.effect(
+          () =>
+            scoped.configForms.whileServed([SETTINGS_ENTRY], () =>
+              scoped.slots.inject('conversation.input.left', () =>
+                scoped.slots.register(
+                  {
+                    name: 'conversation.input.left',
+                    id: CONTEXT_ENTRY_ID,
+                    order: 20,
+                    inject: () => ({ form }),
+                  },
+                  FacetContextButton,
+                ),
+              ),
+            ),
+          'dsh-facet: context button',
+        )
+      })
+    }
+
+    module.exports = {
+      name: 'dsh-facet',
+      inject: ['slots'],
+      apply,
+      SETTINGS_ENTRY,
+      BUNDLE_CONFIG_KEY,
+      FACET_PRESET,
+      CONTEXT_ENTRY_ID,
+      FacetCard,
+      FacetCardController,
+      FacetContextButton,
+      FacetContextPanel,
+      declaredFor,
+      writeDeclaration,
+    }
+    return module.exports
+  },
+})

index.js

@@ -16,10 +16,12 @@
  * published once here and consumed there, which is also why the preset can be
  * swapped without touching any of this.
  *
- * There is deliberately no `settings` namespace. A facet grant is a statement
+ * There is deliberately no `settings` *namespace* of our own: a facet grant is a
- * about one conversation, so the only thing worth persisting is the deployment's
+ * statement about one conversation, so the only thing worth persisting is the
- * standing grants, and those belong in the profile patch — the layer where this
+ * deployment's standing grants, and those belong in the profile patch — the
- * machine's facts already live.
+ * layer where this machine's facts already live. What the framework projects
+ * onto this row is the {@link Config} schema below, which is the same patch
+ * layer reached through the Web UI rather than a second place to store things.
  */
 
 import Schema from '@deepseek-ai/schemastery'
@@ -28,21 +30,81 @@ import { createFacetPolicy } from './lib/policy.js'
 
 export const name = 'dsh-facet'
 
-/** Every configuration field this plugin exposes. */
+/**
+ * Every configuration field this plugin exposes.
+ *
+ * `mode`, `extraRoots` and `scopes` are marked `volatile()`, and that marker is
+ * doing two jobs rather than one. It is what puts them on the settings page at
+ * all — the framework's form projection keeps only fields under a volatile
+ * ancestor, and drops an entry with no such field from `settings.describe`
+ * entirely, so without it this row has no card. It is also what makes an edit
+ * *live*: a volatile field is handed to {@link apply} as a reference rather than
+ * a value, and the framework commits an edit into that reference without
+ * re-applying the plugin.
+ *
+ * The second job is why every reader of these fields goes through
+ * `configValue()` in `./lib/policy.js` and reads at the point of use. A plugin
+ * that takes the reference for a string gets a settings card that appears to
+ * work and changes nothing.
+ *
+ * `scopes` is volatile for a third reason: it is the only field the browser
+ * context panel writes, and `settings.mutate` refuses a path that is not under a
+ * volatile node. That is the whole mechanism by which the panel — and not the
+ * agent — decides what one conversation may see.
+ *
+ * `sectionOrder` and `contextOrder` are deliberately NOT volatile. They place
+ * the rule and the binding among the other prompt sections, which is settled
+ * once at load; making them volatile would put two knobs nobody should touch on
+ * the card, and a section cannot be re-ordered without a remount anyway.
+ */
 export const Config = Schema.object({
   /**
    * How a call outside the facet is handled. `ask` questions the user, `deny`
    * refuses outright, `off` disables enforcement while leaving the preset in
    * place — useful for telling a scoping problem from an unrelated one.
    */
-  mode: Schema.union(['ask', 'deny', 'off']).default('ask'),
+  mode: Schema.union(['ask', 'deny', 'off']).default('ask').volatile(),
 
   /**
-   * Paths always in scope, for code a module legitimately depends on — shared
+   * A deployment-wide seed of paths always in scope, for code a module
-   * types, a common test harness. Relative paths resolve against each session's
+   * legitimately depends on — shared types, a common test harness.
-   * own directory, so the same list is meaningful in every workspace.
+   *
+   * Deliberately only a seed. Before per-session scope existed this was the only
+   * way to widen anything, which meant "this one conversation needs the entity
+   * folder" had to be written as a fact about every conversation in every
+   * workspace. Per-session scope belongs in {@link Config.scopes}; this is for
+   * the paths a deployment genuinely always wants, and it is empty by default.
+   *
+   * Relative paths resolve against each session's own directory, so the same
+   * list is meaningful in every workspace.
    */
-  extraRoots: Schema.array(String).default([]),
+  extraRoots: Schema.array(String).default([]).volatile(),
+
+  /**
+   * Per-session scope — the user's declaration for one conversation, keyed by
+   * session id.
+   *
+   * Written only by the browser context panel, through the settings service, and
+   * never by the agent: this plugin exposes no write path to it, and a facet
+   * session carries no settings tool. `focus` narrows the session to a folder;
+   * `extras` are paths the conversation may read outside it. Both are relative
+   * to the session's own directory unless absolute, so a declaration keeps its
+   * meaning wherever the workspace lives.
+   *
+   * Entries outlive their sessions, which is deliberate — reopening a chat
+   * should give back the scope it had — and costs a little growth in the
+   * profile patch that the panel can tidy.
+   */
+  scopes: Schema.dict(
+    Schema.object({
+      /** The session's facet root, relative to the session directory or absolute. Empty means the session directory itself. */
+      focus: Schema.string(),
+      /** Paths this session may also read, outside the root. */
+      extras: Schema.array(String).default([]),
+    }),
+  )
+    .default({})
+    .volatile(),
 
   /** Placement of the invariant rule in the system prompt. */
   sectionOrder: Schema.number().default(100),

lib/guard.js

@@ -64,10 +64,48 @@ export const Config = Schema.object({
  */
 export function apply(ctx, config) {
   const policy = ctx.facetPolicy
-  /** @type {'ask'|'deny'|'off'} */
-  const mode = policy.mode
 
-  if (mode === 'off') return
+  // Read at the point of use, never captured. `mode` is a volatile field, so a
+  // settings edit updates the policy's reference in place and deliberately does
+  // not re-apply this plugin; a `const mode` here would answer with the value
+  // the session was loaded with, for the life of the session.
+  const modeNow = () => policy.mode
+
+  /**
+   * Whether an approval request from this session can reach a person.
+   *
+   * `ask` mode is a promise that an out-of-facet call is *put to the user*, and
+   * that promise needs a channel. A session can be composed without one: the
+   * `danger-full-access` permission preset sets `approval: never`, under which
+   * the approval service's `decide()` returns "rejected" before consulting any
+   * answerer. An ask is then a denial, and `facet action=add` — itself an ask —
+   * is denied with it, so the scope can never be widened while the model is told
+   * only `the user rejected tool "…"`. Naming that is the binding's job; see
+   * `facetContextText`.
+   *
+   * A missing service is a definite no (the tool pipeline denies an ask it
+   * cannot route). An unreadable policy is treated as a yes, so a transient
+   * failure does not tell a user to go and edit their configuration.
+   *
+   * @param {{session?: object}|undefined} agent - the agent whose session supplies the policy.
+   * @returns {boolean} whether an ask can reach a person.
+   */
+  const canAsk = (agent) => {
+    const approval = ctx.get('approval')
+    if (approval === undefined || agent?.session === undefined) return false
+    try {
+      return approval.effectivePolicy(agent.session) !== 'never'
+    } catch {
+      return true
+    }
+  }
+
+  // `off` is the one part that stays a mount-time decision. Deciding it here
+  // means an `off` deployment contributes no rule, no binding and no tool —
+  // which is the point of the mode. The cost is that turning it *on* later needs
+  // a reload, because a volatile-only edit never re-runs this function. `ask`
+  // and `deny` swap freely in both directions.
+  if (modeNow() === 'off') return
 
   const sectionOrder = policy.sectionOrder ?? 100
   const contextOrder = policy.contextOrder ?? 105
@@ -129,6 +167,9 @@ export function apply(ctx, config) {
   const classify = async (exec) => {
     if (exec.signal?.aborted) return undefined
 
+    const mode = modeNow()
+    if (mode === 'off') return undefined
+
     // Widening is the one act that always needs the user, whatever the mode:
     // it is explicit, deliberate, and the only thing standing between a scoped
     // agent and an unscoped one.
@@ -155,11 +196,13 @@ export function apply(ctx, config) {
   }
 
   // The rule. `interpolate: false` because every value in it is already
-  // literal; there is nothing here for the harness to substitute.
+  // literal; there is nothing here for the harness to substitute. It carries no
+  // `mode`, because a section is registered once and cannot follow a live edit —
+  // see `facetRuleText`.
   ctx.systemPrompt.section({
     name: 'facet-scope',
     order: Number(sectionOrder),
-    text: facetRuleText({ mode }),
+    text: facetRuleText(),
     interpolate: false,
   })
 
@@ -173,11 +216,17 @@ export function apply(ctx, config) {
     text: (context) => {
       const scope = policy.scopeFor(context?.agent)
       if (scope === undefined) return ''
-      return facetContextText({ cwd: scope.cwd, root: scope.root, extras: scope.extras, mode })
+      return facetContextText({
+        cwd: scope.cwd,
+        root: scope.root,
+        extras: scope.extras,
+        mode: modeNow(),
+        canAsk: canAsk(context?.agent),
+      })
     },
   })
 
-  if (config.tool) ctx.tools.register(facetTool(ctx, policy, mode))
+  if (config.tool) ctx.tools.register(facetTool(ctx, policy))
 
   // `next()` first, so an earlier policy plugin keeps its say: this listener
   // only ever adds a question or a refusal to a call that was otherwise allowed.
@@ -197,36 +246,42 @@ function requestedPaths(args) {
 }
 
 /**
- * The `facet` tool: read the scope, or ask to widen it.
+ * The `facet` tool: read the scope, narrow it, or ask to widen it.
  *
  * `add` does not enforce anything itself — the pre-execute listener has already
  * put the question to the user, and the body only runs if they said yes. That
  * split is deliberate: the approval is a property of the *call*, so it holds
  * even if this tool is later replaced or dispatched from `run_code`.
  *
+ * `focus` is the one action this tool performs without asking, and it is the
+ * only one that can only ever *reduce* the scope. That asymmetry is the whole
+ * design: an agent may decide a conversation is about one folder, and may not
+ * decide it is about more.
+ *
  * @param {import('@deepseek-ai/cordis').Context} ctx - the guard's context.
  * @param {object} policy - the `facetPolicy` service.
- * @param {'ask'|'deny'|'off'} mode - the deployment's enforcement mode.
  */
-function facetTool(ctx, policy, mode) {
+function facetTool(ctx, policy) {
   return defineTool({
     name: FACET_TOOL,
     description:
-      'Read this session\u2019s facet scope, or ask the user to grant an extra path. A facet is the folder the ' +
+      'Read this session\u2019s facet scope, narrow it to one folder, or ask the user for an extra path. A facet is ' +
-      'conversation was started in; the session is scoped to it. Use `status` to see the current scope. Use `add` ' +
+      'the folder the conversation is scoped to; `status` reports it. Use `focus` when the work has settled on one ' +
-      'only when you actually need a file outside the facet — it asks the user for permission, and the grant lasts ' +
+      'folder inside the facet — narrowing is always allowed and takes effect at once. Use `add` only when you ' +
-      'for the rest of the conversation. Never call `add` for a path you merely expect to need.',
+      'actually need a file outside the facet: it asks the user for permission, and the grant lasts for the rest of ' +
+      'the conversation. Never call `add` for a path you merely expect to need. Where the deployment has no approval ' +
+      'channel, `add` cannot be granted at all and the user widens the scope from the facet panel in their browser.',
     parameters: {
       action: {
         type: 'string',
         required: true,
-        description: 'One of: status, add, remove, reset.',
+        description: 'One of: status, focus, add, remove, reset.',
       },
       paths: {
         type: 'array',
         items: { type: 'string' },
         description:
-          'Paths to grant, relative to the session directory or absolute. Required for add and remove; ignored otherwise.',
+          'Paths, relative to the session directory or absolute. Required for add and remove; for focus, exactly one folder inside the current facet.',
       },
     },
     output: {
@@ -259,13 +314,16 @@ function facetTool(ctx, policy, mode) {
       const problem =
         (action === 'add' || action === 'remove') && requested.length === 0
           ? `facet: action "${action}" needs \`paths\``
-          : !['status', 'add', 'remove', 'reset'].includes(action)
+          : action === 'focus' && requested.length !== 1
-            ? `facet: unknown action "${action}"; expected status, add, remove or reset`
+            ? 'facet: action "focus" needs exactly one folder'
+            : !['status', 'focus', 'add', 'remove', 'reset'].includes(action)
+              ? `facet: unknown action "${action}"; expected status, focus, add, remove or reset`
               : undefined
       if (problem !== undefined) throw new Error(problem)
 
       const before = policy.grantsFor(sessionId)
-      if (action === 'add') policy.grant(sessionId, requested, cwd)
+      if (action === 'focus') policy.narrowTo(sessionId, await narrowing(ctx, policy, exec, requested[0]))
+      else if (action === 'add') policy.grant(sessionId, requested, cwd)
       else if (action === 'remove') policy.revoke(sessionId, requested, cwd)
       else if (action === 'reset') policy.reset(sessionId)
 
@@ -276,7 +334,9 @@ function facetTool(ctx, policy, mode) {
         ok: true,
         root: scope.root,
         facet: scope.root,
-        mode,
+        // Read here rather than captured at mount, so `status` reports the mode
+        // in force now instead of the one this session started under.
+        mode: String(policy.mode),
         standing: policy.standing,
         granted,
         scope: scope.extras,
@@ -290,6 +350,48 @@ function facetTool(ctx, policy, mode) {
   })
 }
 
+/**
+ * Resolve one `focus` request to the canonical root it asks for.
+ *
+ * Refuses anything the scope already in force does not contain, because that
+ * would be a widening by another name — and widening is the user's decision, not
+ * the agent's. The containment test is the filesystem provider's, on canonical
+ * targets, for the same reason the guard uses it: a symlink inside the facet
+ * that points outside it must not become a way through.
+ *
+ * The canonical key is what gets recorded, so a later `scopeFor` compares like
+ * with like. Where the user declared a root through a symlink, the two spellings
+ * may not share a prefix; the narrowing is then dropped rather than trusted,
+ * which loses the narrowing and never the boundary.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the guard's context, holding `fs`.
+ * @param {object} policy - the `facetPolicy` service.
+ * @param {import('@deepseek-ai/dsh-tools').ToolExecution} exec - the running call.
+ * @param {string} raw - the folder the model named.
+ * @returns {Promise<string>} the absolute root to narrow to.
+ */
+async function narrowing(ctx, policy, exec, raw) {
+  const scope = policy.scopeFor(exec.agent)
+  if (scope === undefined) throw new Error('facet: this session has no working directory, so there is nothing to narrow')
+
+  let target
+  let boundary
+  try {
+    target = await ctx.fs.resolve(raw, { cwd: scope.cwd, signal: exec.signal })
+    boundary = await ctx.fs.resolve(scope.root, { cwd: scope.cwd, signal: exec.signal })
+  } catch {
+    throw new Error(`facet: cannot resolve "${raw}", so the facet cannot be narrowed to it`)
+  }
+
+  if (target.targetKey !== boundary.targetKey && !ctx.fs.contains(boundary, target)) {
+    throw new Error(
+      `facet: "${raw}" is outside the current facet (${scope.root}). Narrowing cannot leave the scope already in force; ` +
+        'ask the user to widen it from the facet panel if the work really has moved.',
+    )
+  }
+  return target.targetKey
+}
+
 /** Model-facing text for one `facet` result. Pure. */
 function renderFacet(value) {
   const lines = [

lib/policy.js

@@ -16,7 +16,39 @@
  * exists to prevent.
  */
 
-import { isAbsolute, resolve } from 'node:path'
+import { isAbsolute, resolve, sep } from 'node:path'
+
+/**
+ * The symbol cosmokit uses to mark a volatile config reference.
+ *
+ * Looked up by symbol rather than by importing cosmokit, because the ESM and CJS
+ * copies of that library are distinct module instances and `Symbol.for` is the
+ * only identity they share.
+ */
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
+
+/**
+ * Read one configuration field.
+ *
+ * A `volatile()` field is a *reference* in the running config, not a plain
+ * value: the framework resolves the schema through `Schema.resolve`, which wraps
+ * each volatile field in `createVolatile(...)` — `{get(), [write]}`. A
+ * non-volatile field, or a config object a test handed straight to
+ * {@link createFacetPolicy}, is the value itself. Both are accepted, so one code
+ * path serves a real profile and a direct call.
+ *
+ * Every read has to happen at the point of use rather than once at construction.
+ * A settings write commits into these references in place and deliberately does
+ * *not* re-apply the plugin, so anything captured at construction would never
+ * see the change — which is how a plugin ends up with a settings card that does
+ * nothing.
+ *
+ * @param {unknown} value - a field of the resolved config.
+ * @returns {unknown} the current value.
+ */
+export function configValue(value) {
+  return typeof value === 'object' && value !== null && VOLATILE_WRITE in value ? value.get() : value
+}
 
 /**
  * @typedef {object} FacetScope
@@ -28,15 +60,95 @@ import { isAbsolute, resolve } from 'node:path'
 /**
  * Build the policy for one deployment.
  *
+ * `config` is the *resolved* composition config, so its volatile fields are
+ * references rather than values; every read below goes through
+ * {@link configValue} and happens per use. Holding the config and reading it lazily
+ * is what makes the settings card honest: `mode`, `extraRoots` and `scopes` are
+ * edited live in the Web UI, and a policy that snapshotted them here would keep
+ * answering with the values it was loaded with.
+ *
+ * ## Two layers of scope, and only one of them the agent can move
+ *
+ * The session's scope is declared in two places on purpose, because the two
+ * audiences have opposite authority:
+ *
+ *   * the **user layer** is `config.scopes[sessionId]` — a `focus` and a list of
+ *     `extras`, written only from the browser context panel through the settings
+ *     service. The agent has no write path to it: nothing in this plugin exposes
+ *     one, and a facet session carries no settings tool.
+ *   * the **agent layer** is in memory — a narrowing `focus` override and the
+ *     grants it asked for. Both can only ever *reduce* what the user layer
+ *     allows, so an agent that goes wrong cannot widen its own scope.
+ *
+ * The effective root is the agent's narrowing while it still sits inside the
+ * user's root, and the user's root otherwise. That ordering matters when the
+ * user narrows after the agent has: the stale agent focus is dropped rather than
+ * honoured, because honouring it would put the session outside the scope the
+ * user had just declared.
+ *
  * @param {object} config
  * @param {'ask'|'deny'|'off'} config.mode - how an out-of-scope call is handled.
- * @param {readonly string[]} [config.extraRoots] - standing grants, resolved against each session's cwd.
+ * @param {readonly string[]} [config.extraRoots] - a deployment-wide seed of standing grants.
+ * @param {Record<string, {focus?: string, extras?: readonly string[]}>} [config.scopes] - per-session scope, keyed by session id.
  * @returns {object} the `facetPolicy` service implementation.
  */
 export function createFacetPolicy(config) {
   /** @type {Map<string, string[]>} session id → granted paths, in the order granted. */
   const grants = new Map()
-  const standing = Array.isArray(config.extraRoots) ? config.extraRoots.filter(isPath) : []
+  /** @type {Map<string, string>} session id → the agent's narrowing focus, absolute. */
+  const narrowed = new Map()
+
+  /**
+   * What the user declared for one session, read fresh.
+   *
+   * @param {string|undefined} sessionId - the session to read.
+   * @returns {{focus?: string, extras?: readonly string[]}|undefined} the declaration.
+   */
+  function declaredScope(sessionId) {
+    if (sessionId === undefined) return undefined
+    const all = configValue(config.scopes)
+    if (all === null || typeof all !== 'object') return undefined
+    const entry = all[sessionId]
+    return entry !== null && typeof entry === 'object' ? entry : undefined
+  }
+
+  /**
+   * The root in force for one session.
+   *
+   * The user's `focus` is resolved against the session directory, not against
+   * the process, so a relative declaration keeps its meaning if the workspace
+   * moves. The agent's narrowing is applied only while it is still inside that
+   * root; a plain prefix test is enough here because the guard's own containment
+   * check, which resolves symlinks, is what authorises a narrowing in the first
+   * place — this one only has to notice a root that has since moved out from
+   * under it.
+   *
+   * @param {string|undefined} sessionId - the session.
+   * @param {string} sessionCwd - its resolved working directory.
+   * @returns {string} the absolute facet root.
+   */
+  function rootFor(sessionId, sessionCwd) {
+    const declared = declaredScope(sessionId)?.focus
+    const base = typeof declared === 'string' && declared.trim() !== '' ? resolve(sessionCwd, declared) : sessionCwd
+    const agentFocus = sessionId === undefined ? undefined : narrowed.get(sessionId)
+    if (agentFocus === undefined) return base
+    if (agentFocus === base || agentFocus.startsWith(base.endsWith(sep) ? base : `${base}${sep}`)) return agentFocus
+    return base
+  }
+
+  /**
+   * The deployment's standing grants, read fresh on every call.
+   *
+   * Not filtered once at construction: `extraRoots` is volatile, so an edit in
+   * the settings UI replaces the reference's contents without remounting this
+   * plugin, and the next scope resolution is expected to see it.
+   *
+   * @returns {string[]} configured paths, blanks dropped.
+   */
+  function standingRoots() {
+    const configured = configValue(config.extraRoots)
+    return Array.isArray(configured) ? configured.filter(isPath) : []
+  }
 
   /**
    * The scope of one agent, or `undefined` when it has none.
@@ -45,31 +157,77 @@ export function createFacetPolicy(config) {
    * something arbitrary: `undefined` here means the guard has no opinion, which
    * is the only safe reading of "we do not know where this agent is".
    *
+   * `cwd` stays the session directory even when the root is narrower, because
+   * it is what relative paths — a grant, a `focus`, an `extraRoots` entry —
+   * resolve against. A declaration written relative to the session keeps the
+   * same meaning whatever the session is focused on.
+   *
    * @param {{session?: {header?: {cwd?: unknown}, id?: unknown}}|undefined} agent - the calling agent.
    * @returns {FacetScope|undefined} the scope.
    */
   function scopeFor(agent) {
     const cwd = agent?.session?.header?.cwd
     if (typeof cwd !== 'string' || cwd.trim() === '') return undefined
-    const root = resolve(cwd)
+    const sessionCwd = resolve(cwd)
-    return { cwd: root, root, extras: extrasFor(agent, root) }
+    const sessionId = idOf(agent)
+    return {
+      cwd: sessionCwd,
+      root: rootFor(sessionId, sessionCwd),
+      extras: extrasFor(agent, sessionCwd),
+    }
   }
 
   /**
-   * Every path in scope beyond the root: standing grants first, then this
+   * Every path in scope beyond the root: the deployment seed, then what the user
-   * session's, deduplicated so the prompt does not repeat itself.
+   * declared for this session, then what the agent was granted — deduplicated so
+   * the prompt does not repeat itself.
+   *
+   * All three are kept rather than layered, because they answer different
+   * questions. The seed is "this deployment always needs it", the declaration is
+   * "this conversation needs it", and a grant is "the user allowed this call".
+   * Removing one from the list when a narrower one exists would mean a user
+   * editing their panel could silently drop a path the deployment depends on.
    *
    * @param {{session?: {id?: unknown}}|undefined} agent - the calling agent.
    * @param {string} cwd - the resolved session directory.
    * @returns {string[]} absolute paths.
    */
   function extrasFor(agent, cwd) {
-    const sessionId = typeof agent?.session?.id === 'string' ? agent.session.id : undefined
+    const sessionId = idOf(agent)
     const own = sessionId === undefined ? [] : grants.get(sessionId) ?? []
-    const all = [...standing, ...own].map((path) => (isAbsolute(path) ? resolve(path) : resolve(cwd, path)))
+    const declared = declaredScope(sessionId)?.extras
+    const listed = Array.isArray(declared) ? declared.filter(isPath) : []
+    const all = [...standingRoots(), ...listed, ...own].map((path) =>
+      isAbsolute(path) ? resolve(path) : resolve(cwd, path),
+    )
     return [...new Set(all)]
   }
 
+  /**
+   * Narrow one session's facet to a path the caller has already authorised.
+   *
+   * The containment check is the caller's, and deliberately so: only the guard
+   * holds `ctx.fs`, and deciding containment on canonical targets is the whole
+   * reason a symlink inside the facet does not open it. This records the answer;
+   * {@link rootFor} re-checks that the user has not since narrowed past it.
+   *
+   * @param {string} sessionId - the session being narrowed.
+   * @param {string} absolute - the absolute root to narrow to.
+   * @returns {string} the recorded focus.
+   */
+  function narrowTo(sessionId, absolute) {
+    narrowed.set(sessionId, absolute)
+    return absolute
+  }
+
+  /**
+   * @param {string} sessionId - the session to read.
+   * @returns {string|undefined} the agent's narrowing for it, if any.
+   */
+  function narrowFor(sessionId) {
+    return narrowed.get(sessionId)
+  }
+
   /**
    * @param {string} sessionId - the session being widened.
    * @param {readonly string[]} paths - raw paths, resolved against `cwd`.
@@ -102,11 +260,19 @@ export function createFacetPolicy(config) {
   }
 
   /**
+   * Clear one session's agent-side scope: its grants and any narrowing it asked
+   * for.
+   *
+   * Deliberately not a widening. The user's declaration is not touched, so this
+   * returns the session to what the user set up in the panel — which may be
+   * narrower than where the agent had got to, and can never be wider.
+   *
    * @param {string} sessionId - the session to clear.
    * @returns {string[]} always empty.
    */
   function reset(sessionId) {
     grants.delete(sessionId)
+    narrowed.delete(sessionId)
     return []
   }
 
@@ -121,15 +287,27 @@ export function createFacetPolicy(config) {
   /** Drop a finished session's grants. Called on `session/disposed`. */
   function forget(sessionId) {
     grants.delete(sessionId)
+    narrowed.delete(sessionId)
   }
 
   return {
-    mode: config.mode,
+    /** The enforcement mode. A getter, so a settings edit is answered on the next call. */
+    get mode() {
+      return configValue(config.mode)
+    },
     /** Prompt placements, carried here so the preset row needs no configuration of its own. */
-    sectionOrder: config.sectionOrder ?? 100,
+    sectionOrder: configValue(config.sectionOrder) ?? 100,
-    contextOrder: config.contextOrder ?? 105,
+    contextOrder: configValue(config.contextOrder) ?? 105,
-    standing: [...standing],
+    /** The deployment-wide seed of standing grants. A getter for the same reason as {@link mode}. */
+    get standing() {
+      return standingRoots()
+    },
+    /** What the user declared for one session: their `focus` and `extras`. */
+    declaredFor: declaredScope,
     scopeFor,
+    rootFor,
+    narrowTo,
+    narrowFor,
     grant,
     revoke,
     reset,
@@ -146,3 +324,13 @@ export function createFacetPolicy(config) {
 function isPath(value) {
   return typeof value === 'string' && value.trim() !== ''
 }
+
+/**
+ * The session id of a calling agent, when it has one.
+ *
+ * @param {{session?: {id?: unknown}}|undefined} agent - the calling agent.
+ * @returns {string|undefined} the id.
+ */
+function idOf(agent) {
+  return typeof agent?.session?.id === 'string' ? agent.session.id : undefined
+}

lib/scope.js

@@ -118,25 +118,24 @@ export function isWideningCall(toolName, args) {
  * treatment the sandbox policy and approval policy already get, for the same
  * reason.
  *
- * @param {object} input
+ * It takes no configuration, and that is deliberate rather than an oversight.
- * @param {'ask'|'deny'|'off'} input.mode - how an out-of-scope call is handled.
+ * A system-prompt section is a plain string registered once; there is no
- * @returns {string} prompt section text, or `''` to contribute nothing.
+ * callback to re-render it, and a settings write to a `volatile()` field
+ * updates the config reference *without* re-applying the plugin. So anything
+ * this function interpolated would freeze at whatever the value was at load —
+ * the prompt would go on describing the old `mode` while the guard enforced the
+ * new one. Everything that depends on `mode` therefore lives in the binding,
+ * which is a callback and therefore live.
+ *
+ * @returns {string} prompt section text.
  */
-export function facetRuleText(input) {
+export function facetRuleText() {
-  const { mode } = input
-  if (mode === 'off') return ''
-
-  const reach =
-    mode === 'deny'
-      ? 'A call outside it is refused. `facet action=add` asks the user to grant a path, and is the only way to widen the scope.'
-      : 'A call outside it is not refused: it is put to the user as a question, so say in one line what you need and why. If they agree, record it with `facet action=add` so the rest of the session does not have to ask again.'
-
   return [
     '# Facet scope',
     '',
-    'This session is scoped to one facet of the project — one module rather than the whole system. Your runtime context states which.',
+    'This session is scoped to one facet of the project — one module rather than the whole system. Your runtime context states which, and says how a call outside it is treated.',
     '',
-    `Work inside the facet. ${reach}`,
+    'Work inside the facet.',
     '',
     'Never widen the scope on your own initiative: a grant is the user\u2019s decision, and an unrequested one is a bug, not initiative. Do not add paths you merely expect to need — ask when you actually need them.',
     '',
@@ -164,28 +163,53 @@ export function displayPath(cwd, path) {
 /**
  * The mutable half of the facet, for the runtime-context snapshot.
  *
- * Kept to three short lines because it is re-sent as part of the conversation
+ * Kept short because it is re-sent as part of the conversation whenever it
- * whenever it changes, and a scope statement that costs more than the scope is
+ * changes, and a scope statement that costs more than the scope is worth is a
- * worth is a scope that does not pay for itself.
+ * scope that does not pay for itself. It carries one sentence more than the bare
+ * binding used to, because `mode` now belongs here: this is the only half that
+ * is re-rendered per request, so it is the only half that can follow a settings
+ * change. See {@link facetRuleText}.
  *
  * @param {object} input
  * @param {string} input.cwd - the session working directory.
  * @param {string|undefined} input.root - the facet root, or undefined when unscoped.
  * @param {readonly string[]} input.extras - absolute granted paths, outside the root.
  * @param {'ask'|'deny'|'off'} input.mode - how an out-of-scope call is handled.
+ * @param {boolean} [input.canAsk] - whether an approval request can reach the user. False means every ask is refused before anyone is consulted.
  * @returns {string} context text, or `''` to contribute nothing.
  */
 export function facetContextText(input) {
-  const { cwd, root, extras = [], mode } = input
+  const { cwd, root, extras = [], mode, canAsk = true } = input
   if (mode === 'off' || typeof root !== 'string' || root === '') return ''
 
+  // Stated in terms of what the model should *do*, because the same sentence is
+  // what the user reads in an approval prompt. A denial that does not say how to
+  // proceed is a denial the agent works around with `bash`.
+  //
+  // `canAsk` comes first because it collapses the other two. A session can be
+  // composed without an approval channel — the `danger-full-access` permission
+  // preset sets `approval: never`, and `decide()` then returns "rejected" before
+  // any answerer is consulted. There, an out-of-facet call is refused whatever
+  // `mode` says, and `facet action=add` is refused with it, because widening is
+  // itself a question. Telling the agent to ask would send it into a loop, and
+  // the reason this guard writes never reaches it: `serviceAsk` replaces a
+  // rejected ask with `the user rejected tool "…"`. So the binding is the one
+  // channel that can say what is true, and it names the mechanism that still
+  // works: the facet's context panel, which the user owns and the agent has no
+  // write path to.
+  const reach = !canAsk
+    ? 'refused — this session has no approval channel, so `facet action=add` cannot be granted; ask the user to widen the facet from its context panel'
+    : mode === 'deny'
+      ? 'refused — ask the user to widen the facet from its context panel, or with `facet action=add` where that can be granted'
+      : 'put to the user as a question — say in one line what you need and why, then record it with `facet action=add` so the rest of the session does not have to ask again'
+
   // The root is stated absolutely even though it is the session's own directory
   // and a relative form would be shorter. `facet: .` is true and useless: the
   // model needs a path it can reason about, and the user reading an approval
   // prompt needs to see which folder they are being asked about.
   const lines = [`facet: ${root}`]
   if (extras.length > 0) lines.push(`granted outside it: ${extras.map((path) => displayPath(cwd, path)).join(', ')}`)
-  lines.push(`outside the facet: ${mode === 'deny' ? 'refused' : 'ask the user'}`)
+  lines.push(`outside the facet: ${reach}`)
   return lines.join('\n')
 }
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-facet",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "description": "Scope an agent session to one facet of a multi-faceted system: the session's own folder, plus whatever files the user grants it.",
@@ -14,6 +14,9 @@
       "types": "./lib/types/guard.d.ts",
       "default": "./lib/guard.js"
     },
+    "./client": {
+      "default": "./client/client.js"
+    },
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./presets/facet.patch.yml": "./presets/facet.patch.yml",
     "./package.json": "./package.json"
@@ -21,6 +24,7 @@
   "files": [
     "index.js",
     "lib",
+    "client",
     "presets",
     "cordis.patch.yml",
     "README.md"
@@ -40,6 +44,14 @@
         "./cordis.patch.yml",
         "./presets/facet.patch.yml"
       ]
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
     }
   },
   "keywords": [

test/client.test.js

@@ -0,0 +1,405 @@
+/**
+ * The browser half: the two keys it binds, and the fields it stages.
+ *
+ * This file exists because of a bug that no host-side test could catch. Marking
+ * the schema's fields `volatile()` makes the Host *serve* the namespace, but the
+ * Plugins page draws only what a browser half registers — so the plugin showed no
+ * settings card at all, and every host-side test passed.
+ *
+ * The wiring is therefore the thing worth testing, and the two keys are the trap:
+ * the settings DOCUMENT is keyed by the profile entry id (`facet-policy`) while
+ * the CARD is keyed by the package name (`dsh-facet`). Every sibling plugin
+ * happens to name those identically, which is exactly why this drifted. A card
+ * bound to the wrong id renders, saves, and writes nowhere.
+ *
+ * `client/client.js` is a `window.__ModuleLoader__` module rather than an ES
+ * module — that is how the harness loads a browser half without a bundler — so
+ * the test stands up the two globals it reads and drives it from there.
+ */
+
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { test } from 'node:test'
+
+import { Config } from '../index.js'
+
+/** Load the browser half with `window` and `require` faked, as the seed would. */
+async function loadClient() {
+  const source = await readFile(new URL('../client/client.js', import.meta.url), 'utf8')
+
+  /** Every spec a card staged, in construction order. */
+  const staged = []
+
+  const primitives = {
+    Modal: 'Modal',
+    SettingsForm: 'SettingsForm',
+    SettingsValueField: 'SettingsValueField',
+    SegmentedControl: 'SegmentedControl',
+    /** Stands in for the real model: records the specs and answers with the value. */
+    SettingsFormModel: class {
+      constructor(scope, specs) {
+        this.scope = scope
+        this.specs = specs
+        staged.push(...specs)
+      }
+      bind(project) {
+        this.project = project
+        return { project }
+      }
+      shell() {
+        return { available: true, writable: true, dirty: false, invalid: false, saving: false, failed: false }
+      }
+      field(name) {
+        const spec = this.specs.find((candidate) => candidate.field === name)
+        return { text: spec?.format(this.scope.value?.[name]) ?? '', overridden: false, invalid: false }
+      }
+      actions() {
+        return { edit: () => {}, resetField: () => {}, save: () => {}, discard: () => {} }
+      }
+      dispose() {}
+    },
+  }
+
+  const require = (id) => {
+    if (id === 'react') {
+      return {
+        createElement: (type, props, ...children) => ({ type, props, children }),
+        // Single-pass stand-ins: the tests render a component once and read the
+        // tree, so a hook only has to answer, not to re-render.
+        useState: (initial) => [typeof initial === 'function' ? initial() : initial, () => {}],
+        useSyncExternalStore: (_subscribe, getSnapshot) => getSnapshot(),
+      }
+    }
+    if (id === '@deepseek-ai/dsh-client-ui-primitives') return primitives
+    throw new Error(`client.js required an unexpected module: ${id}`)
+  }
+
+  let registered
+  const loader = { load: (value) => (registered = value) }
+  // eslint-disable-next-line no-new-func -- the file is a ModuleLoader script, not an ES module.
+  new Function('window', 'require', source)({ __ModuleLoader__: loader }, require)
+
+  assert.notEqual(registered, undefined, 'client.js never called window.__ModuleLoader__.load')
+  return { module: registered.factory(require), staged, primitives }
+}
+
+/** Drive `apply` against a fake slot/configForms surface and report what it did. */
+function drive(mod, { served = true, value = {} } = {}) {
+  const seen = { formNs: undefined, watched: undefined, registrations: [] }
+  const disposers = []
+  let currentSlot
+
+  const ctx = {
+    inject: (names, scope) => {
+      const scoped = {
+        configForms: {
+          get: (ns) => {
+            seen.formNs = ns
+            return { value, getSnapshot: () => ({ value, writable: true }), subscribe: () => () => {}, mutate: () => true }
+          },
+          whileServed: (namespaces, register) => {
+            seen.watched = namespaces
+            // The real `whileServed` registers only while the Host serves the
+            // namespace; `served` is what the Host's `settings.describe` answers.
+            if (!served) return () => {}
+            return register(new Set(namespaces))
+          },
+        },
+        slots: {
+          inject: (name, register) => {
+            currentSlot = name
+            register()
+            currentSlot = undefined
+          },
+          register: (options, component) => {
+            seen.registrations.push({ slot: currentSlot, options, component })
+            return () => {}
+          },
+        },
+        effect: (fn) => {
+          const dispose = fn()
+          if (typeof dispose === 'function') disposers.push(dispose)
+          return dispose
+        },
+      }
+      scope(scoped)
+    },
+  }
+
+  mod.apply(ctx)
+  return { seen, disposers }
+}
+
+/** The one registration a test cares about, by the slot it went into. */
+function registrationFor(seen, slot) {
+  const found = seen.registrations.filter((entry) => entry.slot === slot)
+  assert.equal(found.length, 1, `expected exactly one registration into ${slot}`)
+  return found[0]
+}
+
+test('the module is the one the Plugins page loads, and asks for the slots it registers into', async () => {
+  const { module: mod } = await loadClient()
+  assert.equal(mod.name, 'dsh-facet')
+  assert.deepEqual(mod.inject, ['slots'])
+  assert.equal(typeof mod.apply, 'function')
+})
+
+test('the form binds to the profile entry id while the card registers under the package name', async () => {
+  const { module: mod } = await loadClient()
+  const { seen } = drive(mod)
+  const card = registrationFor(seen, 'plugins.bundle.config')
+
+  // These two are deliberately different strings. `facet-policy` is the `id` of
+  // this bundle's row in cordis.patch.yml — what `Config` is filed under. The
+  // card is dispatched by the BUNDLE's package name.
+  assert.equal(seen.formNs, 'facet-policy')
+  assert.equal(card.options.key, 'dsh-facet')
+  assert.notEqual(seen.formNs, card.options.key, 'if these ever coincide, the trap this test guards has moved')
+
+  assert.equal(card.slot, 'plugins.bundle.config')
+  assert.deepEqual(seen.watched, ['facet-policy'])
+})
+
+test('the context button rides the composer tool row, gated on the same namespace', async () => {
+  const { module: mod } = await loadClient()
+  const { seen } = drive(mod)
+  const button = registrationFor(seen, 'conversation.input.left')
+
+  // An id, not a key: `conversation.input.left` is a list, and the row shows one
+  // entry per id.
+  assert.equal(button.options.id, 'facet-context')
+  assert.equal(typeof button.options.inject, 'function')
+  // It has to receive the settings form, because the panel writes through the
+  // very same document the plugin card does.
+  assert.equal(typeof button.options.inject().form, 'object')
+})
+
+test('the host row the form binds to is the one cordis.patch.yml actually declares', async () => {
+  const patch = await readFile(new URL('../cordis.patch.yml', import.meta.url), 'utf8')
+  const { module: mod } = await loadClient()
+  const { seen } = drive(mod)
+  const card = registrationFor(seen, 'plugins.bundle.config')
+
+  // A rename in the patch without a rename here is a card that writes nowhere,
+  // so the id is read out of the patch rather than trusted to the test.
+  assert.match(patch, new RegExp(`id:\\s*${seen.formNs}\\b`))
+  assert.equal((await import('../package.json', { with: { type: 'json' } })).default.name, card.options.key)
+})
+
+test('nothing is registered while the Host does not serve the namespace', async () => {
+  const { module: mod } = await loadClient()
+  const { seen } = drive(mod, { served: false })
+  assert.equal(seen.formNs, 'facet-policy', 'the form is still bound')
+  // Neither the card nor the button: each would be a control that writes nowhere.
+  assert.deepEqual(seen.registrations, [])
+})
+
+test('the card stages exactly the deployment fields the host marks volatile', async () => {
+  const { module: mod, staged } = await loadClient()
+  drive(mod)
+
+  const volatileFields = Object.entries(Config.dict)
+    .filter(([, schema]) => schema.meta.volatile === true)
+    .map(([key]) => key)
+
+  // `scopes` is volatile too, but it is not a deployment field and must not be a
+  // control on the card: it is per-session state, written by the context panel
+  // and keyed by session id. Staging it here would render a dictionary blob a
+  // user could not sensibly edit, and would put the panel's store on the one
+  // surface that edits the deployment.
+  assert.ok(volatileFields.includes('scopes'), 'scopes must be volatile or the panel cannot write it')
+  const declared = volatileFields.filter((key) => key !== 'scopes')
+
+  // A field served but never staged is invisible in the UI; a field staged but
+  // never served makes `whileServed` withhold the whole card.
+  assert.deepEqual(
+    staged.map((spec) => spec.field).sort(),
+    declared.sort(),
+    'the card and the host schema have drifted apart',
+  )
+})
+
+test('the choice field refuses a value the schema would reject, and clears on empty', async () => {
+  const { module: mod, staged } = await loadClient()
+  drive(mod)
+  const mode = staged.find((spec) => spec.field === 'mode')
+
+  assert.equal(mode.parse('deny').value, 'deny')
+  assert.equal(mode.parse(' DENY ').value, 'deny')
+  assert.deepEqual(mode.parse(''), { kind: 'clear' })
+  // Undefined marks the draft invalid, which blocks the save rather than
+  // coercing a typo into a mode the Host would reject anyway.
+  assert.equal(mode.parse('maybe'), undefined)
+})
+
+test('the list field clears rather than storing an empty array that shadows the default', async () => {
+  const { module: mod, staged } = await loadClient()
+  drive(mod)
+  const roots = staged.find((spec) => spec.field === 'extraRoots')
+
+  assert.deepEqual(roots.parse('a, b\nc').value, ['a', 'b', 'c'])
+  assert.deepEqual(roots.parse('   '), { kind: 'clear' })
+  assert.equal(roots.format(['a', 'b']), 'a, b')
+  assert.equal(roots.format(undefined), '')
+})
+
+test('the card renders both views without reaching for anything it was not given', async () => {
+  const { module: mod } = await loadClient()
+  const { seen } = drive(mod)
+  const { component: card } = registrationFor(seen, 'plugins.bundle.config')
+
+  assert.equal(typeof card, 'function')
+  assert.equal(card({ view: 'summary' }), 'How a call outside the session\u2019s own folder is handled, and which paths are always in scope.')
+
+  const tree = card({
+    view: 'page',
+    useFacetCard: (select) =>
+      select({
+        available: true,
+        writable: true,
+        dirty: false,
+        invalid: false,
+        saving: false,
+        failed: false,
+        mode: { text: 'deny', overridden: false, invalid: false },
+        extraRoots: { text: 'src/shared', overridden: true, invalid: false },
+      }),
+    edit: () => {},
+    resetField: () => {},
+    save: () => {},
+    discard: () => {},
+  })
+
+  // The form frame, with the segmented control reading the staged mode. Children
+  // ride the `children` prop, which is how the platform's own cards pass them.
+  assert.equal(tree.type, 'SettingsForm')
+  const controls = tree.props.children.children
+  assert.equal(controls[0].type, 'div')
+  assert.equal(controls[1].type, 'SettingsValueField')
+  assert.equal(controls[0].children[1].props.value, 'deny')
+  assert.equal(controls[1].props.text, 'src/shared')
+})
+
+test('the client half loads the packages whose slots it registers into', async () => {
+  const pkg = (await import('../package.json', { with: { type: 'json' } })).default
+  const inject = pkg.dsh.client.inject
+
+  // Registering into a slot is a dependency on the package that declares it.
+  // `slots.inject` waits for a slot rather than creating one, so a half that
+  // names a slot belonging to a package the boot graph has not loaded yet
+  // registers nothing at all — and silently, because nothing errors.
+  assert.ok(inject.includes('@deepseek-ai/dsh-client-ui-plugin-manager'), 'registers into plugins.bundle.config')
+  assert.ok(inject.includes('@deepseek-ai/dsh-client-ui-conversation'), 'registers into conversation.input.left')
+  assert.ok(inject.includes('@deepseek-ai/dsh-client-ui-settings'), 'reads configForms')
+})
+
+// ── the context button and panel ─────────────────────────────────────────────
+
+test('the context button appears for a facet session and nowhere else', async () => {
+  const { module: mod } = await loadClient()
+  const { seen } = drive(mod)
+  const { component: button, options } = registrationFor(seen, 'conversation.input.left')
+  const { form } = options.inject()
+
+  const render = (preset) =>
+    button({
+      sessionId: 'session-1',
+      useSessions: (select) => select({ byId: { 'session-1': { projectionValues: { agentPreset: preset } } } }),
+      locked: false,
+      form,
+    })
+
+  assert.notEqual(render('facet'), null)
+  // Every other preset in the deployment is untouched: a control for a plugin
+  // that is not running would be worse than no control.
+  assert.equal(render('standard'), null)
+  assert.equal(render(undefined), null)
+})
+
+test('declaredFor normalises whatever the document holds', async () => {
+  const { module: mod } = await loadClient()
+
+  assert.deepEqual(mod.declaredFor({ value: { scopes: { a: { focus: 'src/x', extras: ['p'] } } } }, 'a'), {
+    focus: 'src/x',
+    extras: ['p'],
+  })
+  // A session with no entry, a document with no scopes, and junk in either all
+  // answer with the same empty declaration rather than throwing in a render.
+  const empty = { focus: '', extras: [] }
+  assert.deepEqual(mod.declaredFor({ value: {} }, 'a'), empty)
+  assert.deepEqual(mod.declaredFor({}, 'a'), empty)
+  assert.deepEqual(mod.declaredFor({ value: { scopes: { a: 'nonsense' } } }, 'a'), empty)
+  assert.deepEqual(mod.declaredFor({ value: { scopes: { a: { focus: 7, extras: ['ok', 3, null] } } } }, 'a'), {
+    focus: '',
+    extras: ['ok'],
+  })
+})
+
+test('writeDeclaration writes one whole declaration, and removes an empty one', async () => {
+  const { module: mod } = await loadClient()
+  const calls = []
+  const form = { mutate: (ops) => (calls.push(ops), true) }
+
+  mod.writeDeclaration(form, 'session-1', { focus: ' src/x ', extras: ['p', ' ', 'q'] })
+  mod.writeDeclaration(form, 'session-1', { focus: '', extras: [] })
+
+  // One path, one write: a queued edit can never half-apply.
+  assert.deepEqual(calls[0], [{ op: 'set', path: ['scopes', 'session-1'], value: { focus: 'src/x', extras: ['p', 'q'] } }])
+  // Both fields empty means "the session directory", which is the schema default
+  // — so it is removed rather than stored as an empty override.
+  assert.deepEqual(calls[1], [{ op: 'unset', path: ['scopes', 'session-1'] }])
+})
+
+test('the panel renders the scope, the guidance, and a way to add and remove', async () => {
+  const { module: mod } = await loadClient()
+  const written = []
+  const form = {
+    getSnapshot: () => ({
+      status: 'ready',
+      writable: true,
+      revision: 4,
+      value: { mode: 'deny', scopes: { 'session-1': { focus: 'src/room', extras: ['CONTROLLER.md'] } } },
+    }),
+    subscribe: () => () => {},
+    mutate: (ops) => (written.push(ops), true),
+  }
+
+  const tree = mod.FacetContextPanel({ form, sessionId: 'session-1', mode: 'deny', onClose: () => {} })
+  assert.equal(tree.type, 'Modal')
+
+  // Walk the tree for the text and controls a user would see.
+  const texts = []
+  const buttons = []
+  const inputs = []
+  const walk = (node) => {
+    if (typeof node === 'string') return texts.push(node)
+    if (node === null || node === undefined || typeof node !== 'object') return
+    if (Array.isArray(node)) return node.forEach(walk)
+    if (node.type === 'button') buttons.push(node)
+    if (node.type === 'input') inputs.push(node)
+    // Children arrive either as createElement arguments or, as the card does it,
+    // through the `children` prop.
+    if (Array.isArray(node.children)) node.children.forEach(walk)
+    walk(node.props?.children)
+  }
+  walk(tree)
+
+  const labelOf = (node) => (node.children ?? [])[0]
+
+  const prose = texts.join('\n')
+  assert.match(prose, /What this conversation may see/)
+  // The two tabs the preset picker cannot show for a custom preset live here.
+  assert.match(prose, /Mode details/)
+  assert.match(prose, /How to use/)
+  // The honest bit about this deployment, so the panel does not promise a
+  // question no approval channel can carry.
+  assert.match(prose, /no approval channel/)
+  assert.match(prose, /danger-full-access/)
+
+  // The declared scope is on screen, and the existing extra has its own control.
+  assert.equal(inputs[0].props.value, 'src/room')
+  assert.equal(buttons.filter((button) => labelOf(button) === 'Remove').length, 1)
+  assert.ok(buttons.some((button) => labelOf(button) === 'Add'))
+  assert.ok(buttons.some((button) => labelOf(button) === 'Clear'))
+  assert.ok(buttons.some((button) => labelOf(button) === 'Set'))
+})

test/guard.test.js

@@ -18,6 +18,15 @@ import { after, before, test } from 'node:test'
 
 import { apply as guard } from '../lib/guard.js'
 import { createFacetPolicy } from '../lib/policy.js'
+import { Config } from '../index.js'
+
+/**
+ * The symbol cosmokit marks a volatile config reference with. A settings write
+ * reaches a running plugin as `target[write](value)` — that is literally what
+ * `updateVolatile` does — so a test can commit an edit the way the framework
+ * does, without a settings service.
+ */
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
 
 /** A filesystem provider with `dsh-fs-local`'s two relevant behaviours. */
 const fsLikeLocal = {
@@ -49,13 +58,22 @@ const fsLikeLocal = {
   },
 }
 
-/** Capture what `apply` registered, so the test can drive it. */
+/**
-function harness({ mode = 'ask', extraRoots = [], tool = true } = {}) {
+ * Capture what `apply` registered, so the test can drive it.
-  const policy = createFacetPolicy({ mode, extraRoots })
+ *
+ * `approval` stands in for the approval service named by its policy: `'ask'`
+ * and `'never'` are the two the schema admits, and leaving it undefined models a
+ * deployment that composed no approval service at all — a case the tool pipeline
+ * denies outright, so the guard must treat it as no channel.
+ */
+function harness({ mode = 'ask', extraRoots = [], tool = true, config, approval } = {}) {
+  const policy = createFacetPolicy(config ?? { mode, extraRoots })
   const captured = { section: undefined, context: undefined, tool: undefined, preExecute: undefined }
   const ctx = {
     facetPolicy: policy,
     fs: fsLikeLocal,
+    get: (name) =>
+      name === 'approval' && approval !== undefined ? { effectivePolicy: () => approval } : undefined,
     systemPrompt: {
       section: (value) => {
         captured.section = value
@@ -89,6 +107,7 @@ before(async () => {
   root = await realpath(await mkdtemp(join(tmpdir(), 'dsh-facet-')))
   facet = join(root, 'src', 'controllers', 'room')
   await mkdir(facet, { recursive: true })
+  await mkdir(join(facet, 'inner'), { recursive: true })
   await mkdir(join(root, 'src', 'controllers', 'other'), { recursive: true })
   await mkdir(join(root, 'src', 'shared'), { recursive: true })
   await writeFile(join(facet, 'index.ts'), 'export {}\n')
@@ -217,6 +236,25 @@ test('off mode registers nothing', () => {
   assert.equal(captured.tool, undefined)
 })
 
+test('a live mode edit decides the next call, without the guard being remounted', async () => {
+  // The loader hands the guard the schema-resolved config, so `mode` arrives as
+  // a volatile reference rather than a string. This drives that exact shape.
+  const config = Config({ mode: 'ask' })
+  const { captured } = harness({ config })
+  const outside = { name: 'read', args: { file_path: '../../shared/types.ts' }, agent: agent() }
+
+  assert.equal((await dispatch(captured, outside)).kind, 'ask')
+
+  // What a settings write does: commit into the reference in place, and
+  // deliberately do not re-apply the plugin. One mount, three answers.
+  config.mode[VOLATILE_WRITE]('deny')
+  assert.equal((await dispatch(captured, outside)).kind, 'deny')
+
+  // `off` silences the guard entirely, which is the whole meaning of the mode.
+  config.mode[VOLATILE_WRITE]('off')
+  assert.equal((await dispatch(captured, outside)).kind, 'allow')
+})
+
 test('the guard adds to a decision, never overrides one', async () => {
   const { captured } = harness()
   const denied = await dispatch(captured, {
@@ -247,6 +285,41 @@ test('the binding follows the agent, and is empty without one', () => {
   assert.equal(captured.context.text(undefined), '')
 })
 
+test('the binding refuses honestly when the session has no approval channel', () => {
+  // `danger-full-access` sets approval: never, so `decide()` returns "rejected"
+  // before any answerer is consulted — and `facet action=add`, itself an ask, is
+  // refused with it. The reason the guard writes never reaches the model on that
+  // path (`serviceAsk` replaces it with `the user rejected tool "…"`), so the
+  // binding is the only place the truth can be said.
+  const { captured } = harness({ mode: 'ask', approval: 'never' })
+  const text = captured.context.text({ agent: agent() })
+
+  assert.match(text, /no approval channel/)
+  assert.match(text, /cannot be granted/)
+  // It names the mechanism that still works, which is the panel the user owns.
+  assert.match(text, /context panel/)
+
+  // The promise `ask` makes cannot be kept here, so it must not be made.
+  assert.doesNotMatch(text, /put to the user as a question/)
+})
+
+test('an approval channel keeps the promise, and a missing service counts as none', () => {
+  const withChannel = harness({ mode: 'ask', approval: 'ask' })
+  assert.match(withChannel.captured.context.text({ agent: agent() }), /put to the user as a question/)
+
+  // No approval service at all: the tool pipeline denies an ask it cannot route,
+  // so the binding must not offer one.
+  const without = harness({ mode: 'ask' })
+  assert.match(without.captured.context.text({ agent: agent() }), /no approval channel/)
+})
+
+test('deny mode still names the way that works when there is no channel', () => {
+  const { captured } = harness({ mode: 'deny', approval: 'never' })
+  const text = captured.context.text({ agent: agent() })
+  assert.match(text, /refused/)
+  assert.match(text, /context panel/)
+})
+
 test('the facet tool reports the scope', async () => {
   const { captured } = harness()
   const value = await captured.tool.execute({ action: 'status' }, { agent: agent() })
@@ -276,6 +349,60 @@ test('the facet tool grants, narrows and clears', async () => {
   assert.deepEqual(policy.grantsFor('session-1'), [])
 })
 
+test('the facet tool narrows inside the facet and refuses a folder outside it', async () => {
+  const { captured, policy } = harness()
+  const exec = { agent: agent() }
+
+  // Narrowing is the one scope change the agent may make unasked: it can only
+  // ever reduce what is visible, so there is nothing for a user to approve.
+  const narrowed = await captured.tool.execute({ action: 'focus', paths: ['inner'] }, exec)
+  assert.equal(narrowed.root, join(facet, 'inner'))
+  assert.equal(narrowed.facet, join(facet, 'inner'))
+  assert.equal(policy.scopeFor(agent()).root, join(facet, 'inner'))
+
+  // A folder outside the scope already in force is a widening by another name,
+  // and widening is the user's decision, taken in their panel.
+  await assert.rejects(
+    () => captured.tool.execute({ action: 'focus', paths: ['../../shared'] }, exec),
+    /outside the current facet/,
+  )
+  await assert.rejects(
+    () => captured.tool.execute({ action: 'focus', paths: ['../other'] }, exec),
+    /outside the current facet/,
+  )
+  // A refused narrowing must not have moved anything.
+  assert.equal(policy.scopeFor(agent()).root, join(facet, 'inner'))
+})
+
+test('the facet tool needs exactly one folder to focus on', async () => {
+  const { captured } = harness()
+  const exec = { agent: agent() }
+  await assert.rejects(() => captured.tool.execute({ action: 'focus' }, exec), /exactly one folder/)
+  await assert.rejects(
+    () => captured.tool.execute({ action: 'focus', paths: ['inner', '../other'] }, exec),
+    /exactly one folder/,
+  )
+})
+
+test('reset lands on the scope the user declared, never back on the session directory', async () => {
+  const { captured, policy } = harness({
+    config: { mode: 'deny', scopes: { 'session-1': { focus: 'src/controllers/room' } } },
+  })
+  const exec = { agent: agent(root) }
+
+  // The user declared this conversation to be about the room controller, so the
+  // session is already narrower than the directory it was started in.
+  assert.equal(policy.scopeFor(agent(root)).root, facet)
+
+  await captured.tool.execute({ action: 'focus', paths: ['src/controllers/room/inner'] }, exec)
+  assert.equal(policy.scopeFor(agent(root)).root, join(facet, 'inner'))
+
+  // Clearing the agent's side has to land on the user's declaration. Landing on
+  // the session directory would make `reset` a widening.
+  await captured.tool.execute({ action: 'reset' }, exec)
+  assert.equal(policy.scopeFor(agent(root)).root, facet)
+})
+
 test('the facet tool refuses a call it cannot act on', async () => {
   const { captured } = harness()
   const exec = { agent: agent() }

test/index.test.js

@@ -10,6 +10,18 @@ import assert from 'node:assert/strict'
 import { test } from 'node:test'
 
 import { apply, Config } from '../index.js'
+import { configValue } from '../lib/policy.js'
+
+/**
+ * The symbol cosmokit marks a volatile config reference with, and the writer it
+ * carries. A settings write reaches a running plugin through exactly this
+ * function — `updateVolatile(target, source)` is `target[write](source.get())` —
+ * so a test can commit an edit the same way the framework does.
+ */
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
+
+/** Whether a field arrived as a live reference rather than a plain value. */
+const isReference = (value) => typeof value === 'object' && value !== null && VOLATILE_WRITE in value
 
 /** The smallest context this row touches. */
 function harness() {
@@ -28,12 +40,59 @@ function harness() {
 
 test('the schema fills every default, so a bare row is a working row', () => {
   const config = Config({})
-  assert.equal(config.mode, 'ask')
+  assert.equal(configValue(config.mode), 'ask')
-  assert.deepEqual(config.extraRoots, [])
+  assert.deepEqual(configValue(config.extraRoots), [])
   assert.equal(config.sectionOrder, 100)
   assert.equal(config.contextOrder, 105)
 })
 
+test('the editable fields are volatile, which is the only reason they have a settings card', () => {
+  const config = Config({})
+  // The framework's form projection keeps only fields under a volatile ancestor
+  // and drops an entry with no such field from `settings.describe` entirely, so
+  // dropping either of these markers silently removes the card from the UI.
+  assert.equal(isReference(config.mode), true)
+  assert.equal(isReference(config.extraRoots), true)
+
+  // Placement is settled once at load: not settings anyone edits live, and not
+  // on the card.
+  assert.equal(isReference(config.sectionOrder), false)
+  assert.equal(isReference(config.contextOrder), false)
+})
+
+test('a settings edit is answered on the next call, without the plugin being re-applied', () => {
+  const provided = []
+  let applies = 0
+  const config = Config({ mode: 'ask', extraRoots: ['/w/src/shared'] })
+  apply(
+    {
+      provide: (name, value) => {
+        applies += 1
+        provided.push({ name, value })
+      },
+      on: () => {},
+    },
+    config,
+  )
+  const policy = provided[0].value
+  assert.equal(policy.mode, 'ask')
+  assert.deepEqual(policy.standing, ['/w/src/shared'])
+
+  // What the framework does on a settings write: it commits into the running
+  // references and deliberately does NOT re-apply the plugin. Everything the
+  // policy reports has to follow from the reference alone.
+  config.mode[VOLATILE_WRITE]('deny')
+  config.extraRoots[VOLATILE_WRITE](['/w/src/shared', '/w/src/types'])
+
+  assert.equal(applies, 1)
+  assert.equal(policy.mode, 'deny')
+  assert.deepEqual(policy.standing, ['/w/src/shared', '/w/src/types'])
+  assert.deepEqual(
+    policy.scopeFor({ session: { id: 's1', header: { cwd: '/w/src/room' } } }).extras,
+    ['/w/src/shared', '/w/src/types'],
+  )
+})
+
 test('a bad mode fails loudly at load rather than at the first file call', () => {
   assert.throws(() => Config({ mode: 'maybe' }))
 })

test/policy.test.js

@@ -93,3 +93,97 @@ test('prompt placements are carried, so the preset row needs no config', () => {
   assert.equal(createFacetPolicy({ mode: 'ask', sectionOrder: 7, contextOrder: 8 }).sectionOrder, 7)
   assert.equal(createFacetPolicy({ mode: 'ask', sectionOrder: 7, contextOrder: 8 }).contextOrder, 8)
 })
+
+// ── per-session scope ────────────────────────────────────────────────────────
+//
+// The declaration is the user's, written from the browser panel; the narrowing
+// is the agent's, held in memory. Everything below is about which of the two
+// wins, and the answer is always "the narrower one, and never a stale agent
+// focus that the user has since narrowed past".
+
+test('a declared focus narrows the root, and the session directory stays the base', () => {
+  const policy = createFacetPolicy({
+    mode: 'deny',
+    scopes: { s1: { focus: 'src/controllers/room' } },
+  })
+  const scope = policy.scopeFor(agentAt('/w', 's1'))
+
+  assert.equal(scope.root, '/w/src/controllers/room')
+  // `cwd` is still where relative paths resolve from — a declaration written
+  // against the session keeps its meaning whatever the session focuses on.
+  assert.equal(scope.cwd, '/w')
+})
+
+test('a declaration is read live, so the panel needs no remount', () => {
+  const scopes = {}
+  const policy = createFacetPolicy({ mode: 'deny', scopes })
+  assert.equal(policy.scopeFor(agentAt('/w', 's1')).root, '/w')
+
+  // What a panel write does to the running reference.
+  scopes.s1 = { focus: 'src/module' }
+  assert.equal(policy.scopeFor(agentAt('/w', 's1')).root, '/w/src/module')
+})
+
+test('declared extras join the deployment seed and the session grants', () => {
+  const policy = createFacetPolicy({
+    mode: 'deny',
+    extraRoots: ['seed'],
+    scopes: { s1: { focus: 'src/room', extras: ['shared', '/abs/common'] } },
+  })
+  policy.grant('s1', ['granted'], '/w')
+
+  assert.deepEqual(policy.scopeFor(agentAt('/w', 's1')).extras, [
+    '/w/seed',
+    '/w/shared',
+    '/abs/common',
+    '/w/granted',
+  ])
+})
+
+test('an agent narrowing is honoured while it stays inside the declared root', () => {
+  const policy = createFacetPolicy({ mode: 'deny', scopes: { s1: { focus: 'src' } } })
+  policy.narrowTo('s1', '/w/src/room')
+
+  assert.equal(policy.scopeFor(agentAt('/w', 's1')).root, '/w/src/room')
+  assert.equal(policy.narrowFor('s1'), '/w/src/room')
+})
+
+test('a narrowing the user has since narrowed past is dropped, not honoured', () => {
+  const scopes = { s1: { focus: 'src' } }
+  const policy = createFacetPolicy({ mode: 'deny', scopes })
+  policy.narrowTo('s1', '/w/src/room')
+  assert.equal(policy.scopeFor(agentAt('/w', 's1')).root, '/w/src/room')
+
+  // The user narrows to a sibling: the agent's focus is now outside the scope
+  // they declared. Honouring it would put the session back where the user had
+  // just decided it should not be.
+  scopes.s1 = { focus: 'src/other' }
+  assert.equal(policy.scopeFor(agentAt('/w', 's1')).root, '/w/src/other')
+})
+
+test('reset and forget drop the agent side and leave the declaration alone', () => {
+  const policy = createFacetPolicy({ mode: 'deny', scopes: { s1: { focus: 'src', extras: ['shared'] } } })
+  policy.narrowTo('s1', '/w/src/room')
+  policy.grant('s1', ['granted'], '/w')
+
+  policy.reset('s1')
+  // Back to what the user declared — narrower than the session, never wider.
+  assert.equal(policy.scopeFor(agentAt('/w', 's1')).root, '/w/src')
+  assert.deepEqual(policy.grantsFor('s1'), [])
+  assert.deepEqual(policy.scopeFor(agentAt('/w', 's1')).extras, ['/w/shared'])
+
+  policy.narrowTo('s1', '/w/src/room')
+  policy.forget('s1')
+  assert.equal(policy.narrowFor('s1'), undefined)
+  assert.equal(policy.scopeFor(agentAt('/w', 's1')).root, '/w/src')
+})
+
+test('junk in a declaration is ignored rather than thrown on', () => {
+  const policy = createFacetPolicy({
+    mode: 'deny',
+    scopes: { s1: { focus: '   ', extras: ['ok', '', 42, null] }, s2: 'not an object' },
+  })
+  assert.equal(policy.scopeFor(agentAt('/w', 's1')).root, '/w')
+  assert.deepEqual(policy.scopeFor(agentAt('/w', 's1')).extras, ['/w/ok'])
+  assert.equal(policy.scopeFor(agentAt('/w', 's2')).root, '/w')
+})

test/scope.test.js

@@ -51,33 +51,69 @@ test('isWideningCall is true only for the one act that needs the user', () => {
 })
 
 test('facetRuleText states the rule and never the binding', () => {
-  const ask = facetRuleText({ mode: 'ask' })
+  const rule = facetRuleText()
-  assert.match(ask, /put to the user as a question/)
-  // The two modes must not read alike: ask must not claim the call is refused.
-  assert.doesNotMatch(ask, /A call outside it is refused/)
 
-  const deny = facetRuleText({ mode: 'deny' })
+  // Mode-neutral by construction. A prompt section is registered once as a plain
-  assert.match(deny, /A call outside it is refused/)
+  // string, and a `volatile()` edit updates the config reference without
+  // re-applying the plugin — so a `mode` interpolated here would freeze at load
+  // while the guard went on enforcing the new one. The mode-specific sentence
+  // lives in the binding, which is a callback.
+  assert.match(rule, /Work inside the facet\./)
+  assert.doesNotMatch(rule, /refused|put to the user as a question/)
+  assert.match(rule, /Never widen the scope on your own initiative/)
 
   // The rule must not name a path: a changing system prompt invalidates the
   // prompt cache for the whole conversation.
-  assert.doesNotMatch(ask, /\/|src\//)
+  assert.doesNotMatch(rule, /\/|src\//)
 
-  assert.equal(facetRuleText({ mode: 'off' }), '')
   assert.equal(facetContextText({ cwd: '/a', root: '/a/b', extras: [], mode: 'off' }), '')
 })
 
 test('facetContextText carries the binding that does change', () => {
+  const ask = facetContextText({ cwd: '/w', root: '/w/src/room', extras: [], mode: 'ask' })
   assert.equal(
-    facetContextText({ cwd: '/w', root: '/w/src/room', extras: [], mode: 'ask' }),
+    ask,
-    'facet: /w/src/room\noutside the facet: ask the user',
+    'facet: /w/src/room\n' +
+      'outside the facet: put to the user as a question — say in one line what you need and why, then record it with `facet action=add` so the rest of the session does not have to ask again',
   )
+
+  const deny = facetContextText({ cwd: '/w', root: '/w/src/room', extras: ['/w/src/shared'], mode: 'deny' })
   assert.equal(
-    facetContextText({ cwd: '/w', root: '/w/src/room', extras: ['/w/src/shared'], mode: 'deny' }),
+    deny,
-    'facet: /w/src/room\ngranted outside it: src/shared\noutside the facet: refused',
+    'facet: /w/src/room\n' +
+      'granted outside it: src/shared\n' +
+      'outside the facet: refused — ask the user to widen the facet from its context panel, or with `facet action=add` where that can be granted',
   )
+
+  // The binding is the only half that can follow a live edit, so the two modes
+  // have to read differently here — they no longer differ in the rule.
+  assert.notEqual(ask, deny)
+
   // Unscoped sessions contribute nothing rather than an empty heading.
   assert.equal(facetContextText({ cwd: '/w', root: undefined, extras: [], mode: 'ask' }), '')
+  assert.equal(facetContextText({ cwd: '/w', root: '/w/src/room', extras: [], mode: 'off' }), '')
+})
+
+test('a session with no approval channel says so instead of promising a question', () => {
+  // `approval: never` refuses every ask before an answerer is consulted, so the
+  // mode stops mattering: `ask` and `deny` both end in a refusal, and
+  // `facet action=add` cannot be granted either. `canAsk: false` is the one
+  // input that collapses them, and it has to name the mechanism that still
+  // works — the context panel, which the user owns.
+  for (const mode of ['ask', 'deny']) {
+    const text = facetContextText({ cwd: '/w', root: '/w/src/room', extras: [], mode, canAsk: false })
+    assert.match(text, /outside the facet: refused — this session has no approval channel/)
+    assert.match(text, /`facet action=add` cannot be granted/)
+    assert.match(text, /context panel/)
+    assert.doesNotMatch(text, /put to the user as a question/)
+  }
+
+  // The default stays a promise: a caller that knows nothing about approval
+  // channels must not silently change what the binding says.
+  assert.match(
+    facetContextText({ cwd: '/w', root: '/w/src/room', extras: [], mode: 'ask' }),
+    /put to the user as a question/,
+  )
 })
 
 test('displayPath prefers the shortest unambiguous form', () => {