@gaunt-sloth/core 2.0.0-alpha.29 → 2.0.0-alpha.30

package/dist/config/shell-policy.d.ts

@@ -240,30 +240,38 @@ export declare function getShellMaxOutputBytes(devTools: GthDevToolsConfig | und
 export declare function getEffectiveDevToolsConfig(config: Pick<GthConfig, 'commands' | 'builtInTools' | 'askWriteMode'> | undefined, command: GthCommand | undefined): GthDevToolsConfig | undefined;
 /**
  * CFG-27 (spec §1, §2) — **the ladder**. There is ONE approvals setting and it is a single ordered
- * ladder of five rungs; each rung fully determines behaviour. There are no severity thresholds, no
- * strictness levels and no independent rater on/off switch.
+ * ladder; each rung fully determines behaviour. There are no severity thresholds, no strictness
+ * levels and no independent rater on/off switch.
  *
  * | # | Rung | Rater | LLM cost |
  * |---|---|---|---|
- * | 1 | `read-only` | no | none |
+ * | 1 | `manual` | no | none |
  * | 2 | `write` | no | none |
- * | 3 | `auto-safe` | yes | 1 call per gated call |
- * | 4 | `full-auto` | yes | 1–2 calls per gated call |
+ * | 3 | `assisted` | yes | 1 call per gated call |
+ * | 4 | `auto` | yes | 1–2 calls per gated call |
  * | 5 | `bypass` | no | none |
  *
  * Rungs 1, 2 and 5 are fully deterministic: no model is consulted, so behaviour is reproducible
  * and costs nothing.
  *
- * **`bypass` is NOT a higher-autonomy rung than `full-auto`** (§2.5). Both let the agent act
+ * **CFG-39 — four postures plus one modifier, not five peers.** `write` is not a rung on a trust
+ * ladder: it is the same posture as `manual` with a different auto-granted set. The four postures
+ * a user chooses between are {@link APPROVAL_POSTURES} (`manual` → `assisted` → `auto`, plus
+ * `bypass`), and that ordering is legible in the names themselves. `write` remains fully settable
+ * — via `/approvals write` and via config — and simply does not occupy a row in quick access.
+ * This constant keeps ALL FIVE members: it is the type's domain, the set
+ * {@link resolveInterruptToolNames} unions over, and what makes `write` settable at all.
+ *
+ * **`bypass` is NOT a higher-autonomy rung than `auto`** (§2.5). Both let the agent act
  * without asking; `bypass` is the same autonomy with the checks removed. The ordering below is the
- * order the rungs are *offered* in, and must never be presented as though `full-auto` were an
+ * order the rungs are *offered* in, and must never be presented as though `auto` were an
  * incomplete `bypass`.
  *
- * Identifiers are kebab-case (§9.1) because the same token must work as a config value, a
- * slash-command argument and a CLI flag — a space breaks the last two. Display names keep their
- * spaces; see {@link APPROVAL_RUNG_LABELS}.
+ * Identifiers are lower-case single words (§9.1) because the same token must work as a config
+ * value, a slash-command argument and a CLI flag — a space breaks the last two. Display names are
+ * capitalised; see {@link APPROVAL_RUNG_LABELS}.
  */
-export declare const APPROVAL_RUNGS: readonly ['read-only', 'write', 'auto-safe', 'full-auto', 'bypass'];
+export declare const APPROVAL_RUNGS: readonly ['manual', 'write', 'assisted', 'auto', 'bypass'];
 /** One rung of {@link APPROVAL_RUNGS}. */
 export type ApprovalRung = (typeof APPROVAL_RUNGS)[number];
 /**
@@ -273,22 +281,224 @@ export type ApprovalRung = (typeof APPROVAL_RUNGS)[number];
  */
 export declare const APPROVAL_RUNG_LABELS: Record<ApprovalRung, string>;
 /**
- * §10 — the one sentence shown wherever a rung is chosen or displayed. **Copied verbatim from the
- * specification**; the wording is constrained by four normative rules there (state what the rung
- * PERMITS, state the allow-list carve-out, never claim safety this system cannot deliver, use the
- * display spelling) plus §8.1 (the hardline floor is real but is NEVER advertised — descriptions
- * cite only protections the user can inspect and extend, i.e. the deny list). Do not "improve"
- * these: `auto-safe` in particular MUST keep the sentence saying files are still rewritten and
- * deleted without asking.
+ * CFG-39 — **the four postures**, in the order they are offered: the rows `/approvals` presents
+ * when it asks the user to choose one.
+ *
+ * `write` is deliberately absent, and its absence is the whole point of the reframe. It is not a
+ * rung on a trust ladder — it is `manual`'s posture with a different auto-granted set, so listing
+ * it as a fifth peer is what made a four-point ladder read as five indistinguishable ones. It stays
+ * fully settable via `/approvals write` and via config; it simply leaves quick access.
  *
- * The only departure from the source text is that §10's markdown emphasis markers (`**not**` in
- * *Full auto*) are dropped, since these strings are rendered as plain terminal copy.
+ * **This is a presentation list, never a policy one.** Every predicate, every `Record<ApprovalRung,
+ * …>` and the interrupt set are built from {@link APPROVAL_RUNGS}, which keeps all five. Using this
+ * constant to decide behaviour would silently un-settle `write`.
+ */
+export declare const APPROVAL_POSTURES: readonly ["manual", "assisted", "auto", "bypass"];
+/**
+ * CFG-39 — the one-line note that `write` exists, shown as picker CHROME beside the `manual` row.
+ *
+ * It lives here rather than appended to {@link APPROVAL_RUNG_DESCRIPTIONS}`.manual` on purpose: the
+ * descriptions are one surface's copy shared by six, so a sentence about quick-access mechanics
+ * would follow the mode into the status display and the tool-description layer, where it means
+ * nothing.
+ */
+export declare const APPROVAL_WRITE_MODIFIER_HINT: string;
+/**
+ * §10 — what each mode is **for**, in at most two sentences, shown wherever a mode is chosen or
+ * displayed.
+ *
+ * **The first sentence is load-bearing and must stand alone.** The `/approvals` picker, the text
+ * fallback and the usage hint all render one line per mode through `firstSentence`, so sentence
+ * one has to answer "what is this mode for" on its own and sentence two carries the qualification.
+ * Keep it short enough to read as a menu row.
+ *
+ * **Say what the mode is for, not only what it permits.** A description that lists permissions
+ * invites the category error these modes actually suffer: Manual reads as "the safe one", so it
+ * gets picked for a long unattended run — where the deciding is done by a human, and a human is the
+ * fastest-degrading decider in the system. Manual and Write are bounded-volume tools and their copy
+ * says so.
+ *
+ * The wording is constrained by four normative rules (state what the mode PERMITS, state the
+ * allow-list carve-out, never claim safety this system cannot deliver, use the display spelling)
+ * plus §8.1 — the hardline floor is real but is NEVER advertised, so descriptions cite only
+ * protections the user can inspect and extend, i.e. the deny list. Five further constraints bind
+ * every edit here:
+ *
+ * 1. **No description may imply containment.** The gate protects against accidents, not intent, and
+ *    a working-folder claim collapses the moment the agent has a shell — `write_file` refuses a
+ *    path that `touch` then writes. The narrow true form (the built-in file *tools* are confined)
+ *    is stated once, on `write`, alongside the fact that the shell is not confined that way.
+ * 2. **Claims are scoped to the session the user is in.** These strings render on terminal surfaces
+ *    only; a sentence whose subject is "Gaunt Sloth" and whose claim is that it always asks would
+ *    be false over the AG-UI and ACP servers, which never drain an approval interrupt ([[EXT-94]]).
+ * 3. **`assisted` MUST keep the sentence saying files are still rewritten and deleted without
+ *    asking** — it sounds safer than it is, and that clause is the correction.
+ * 4. **A qualification may not live in the second sentence alone.** The picker, the text fallback
+ *    and the usage hint all render `firstSentence` and nothing else, so the opener is the whole
+ *    message on the three surfaces a user reads while *choosing* a mode. An opener that sells a
+ *    behavioural difference the product does not have is not rescued by a sentence two those
+ *    surfaces never print — check a wording by rendering it, not by reading the constant.
+ * 5. **`auto` is the mode a reader most wants to hear is quiet, and it is not.** It settles some
+ *    risky commands with the rater instead of interrupting — that difference is real and may be
+ *    stated — but the copy MUST also say that a bounded exchange ends at the user, and MUST NOT
+ *    promise the user watches it happen. The rounds reach a person at the escalation, all of them
+ *    at once, and nothing renders them before that ([[TUI-C26]]), so a sentence implying a live
+ *    commentary would be describing a screen that does not exist.
+ *
+ * Everything these two sentences cannot hold lives at {@link APPROVAL_PROTECTION_DOCS_URL}, which
+ * the surfaces print beside the copy rather than each description repeating it.
  */
 export declare const APPROVAL_RUNG_DESCRIPTIONS: Record<ApprovalRung, string>;
+/**
+ * The page that carries what these modes do and do NOT protect you from — the reasoning the
+ * two-sentence descriptions deliberately do not hold.
+ *
+ * **A GitHub blob URL, matching the one other user-facing runtime doc link in this package** (the
+ * 2.0 migration pointer in `config/schema.ts`). The docs site publishes the same page at
+ * `https://gauntsloth.app/docs/guides/what-approvals-protect-you-from/`; move this constant there
+ * once that path serves the page, and nothing else changes.
+ */
+export declare const APPROVAL_PROTECTION_DOCS_URL = "https://github.com/pukeko-robotics/gaunt-sloth/blob/main/docs/guides/what-approvals-protect-you-from.md";
+/**
+ * The docs pointer as the surfaces print it: **label and URL as two separate lines**, never one
+ * joined string. Every notice surface takes `lines: string[]` and renders one line each, so a bare
+ * URL on its own line is the only form that survives a narrow pane without the break landing
+ * mid-path — and it is what lets a terminal that linkifies URLs pick the whole thing up.
+ *
+ * It lives beside the descriptions rather than inside them for {@link APPROVAL_WRITE_MODIFIER_HINT}'s
+ * reason: one line about where to read more, repeated into all five descriptions, would follow each
+ * mode into the tool-description layer and the status display, where it is noise.
+ */
+export declare const APPROVAL_PROTECTION_DOCS_LINES: readonly string[];
 /** Narrowing type guard for a raw string that may name a rung. */
 export declare function isApprovalRung(value: unknown): value is ApprovalRung;
 /** The rungs at which every gated call is rated by the model (§2.3, §2.4). */
 export declare function isRatedRung(rung: ApprovalRung): boolean;
+/**
+ * [[EXT-29]] (§5) — the rung at which a `destructive` rating opens a **negotiation** with the rater
+ * instead of going to the human: the agent may revise the command or justify it, the rater re-rates
+ * with the exchange in view, and only a spent bound reaches a person.
+ *
+ * **This is the one predicate that separates `auto` from `assisted`, and it is deliberately ONE.**
+ * Three places have to agree about it — the decision mapping
+ * ({@link import('../core/shell/rater.js').mapVerdictToAction}, which returns `reject` here and
+ * `escalate` at `assisted`), the rating prompt (§5.2's wording rules are addressed to the agent, so
+ * they are turned on by this and not by whether a transcript happens to exist yet), and the runner
+ * that counts the rounds. Two of them agreeing and the third not is exactly how the two rated rungs
+ * would drift back into being the same posture with different names.
+ *
+ * Written as a `=== 'auto'` test rather than as "rated but not assisted" so that a sixth rung has to
+ * be classified deliberately rather than inheriting a negotiation by omission.
+ */
+export declare function isNegotiatingRung(rung: ApprovalRung): boolean;
+/**
+ * The rungs that decide a gated call **without a model** — `manual` and `write` (§2.1, §2.2).
+ * Everything they do not auto-grant goes to the human, so these are the two rungs a user picks in
+ * order to read and approve every tool call themselves.
+ *
+ * The complement of {@link isRatedRung} plus `bypass`; written out rather than negated so that a
+ * sixth rung would have to be classified deliberately instead of defaulting into this set.
+ */
+export declare function isDeterministicRung(rung: ApprovalRung): boolean;
+/**
+ * **The one rule: does `rung` gate this tool — i.e. must this call be decided rather than simply
+ * run?** Everything else in this area is a projection of this predicate over a set of names.
+ *
+ * - The shell is gated whenever the shell gate is on, at EVERY rung (`bypass` included, so §2.5's
+ *   deny list can still fire — see the `bypass` arm of `GthAgentRunner.decideToolApproval`).
+ * - At the two **deterministic** rungs, a tool is gated when the rung's own grant does not cover its
+ *   access class ({@link isAccessClassGrantedAtRung}). At `manual` that leaves only the built-in
+ *   READ tools free; at `write`, the built-in read and write tools. The write built-ins, the shell,
+ *   deepagents' `execute`, MCP tools and custom/agent-authored tools all escalate to the human.
+ * - At `assisted`, `auto` and `bypass` nothing but the shell is gated. **That split is
+ *   deliberate and load-bearing, not tidiness.** At a rated rung a gated non-shell call reaches the
+ *   `subject.kind !== 'shell'` arm of `GthAgentRunner.decideToolApproval`, which floors it at
+ *   `destructive` and sends it to the human *with no rating call*, because §4.3 keeps the rater on
+ *   the shell until [[EXT-30]]. Gating there would silently turn every MCP call at `assisted` into
+ *   a human prompt — a UX change belonging to EXT-30, not to the two rungs whose published
+ *   descriptions this predicate makes true.
+ *
+ * `gateShell` only ever WIDENS the result. At a deterministic rung the shell is gated by its own
+ * (absent) access class if it is bound at all, so `gateShell: false` does not exempt it — an
+ * exemption keyed to one tool NAME is the defect class this predicate exists to remove. In practice
+ * a disabled shell tool is never bound, so the two agree.
+ *
+ * **This takes no bound toolset**, which is what lets `GthAgentRunner` ask it about a single
+ * arriving call: the runner sees the names the graph registered, and on the deep backend that list
+ * omits tools deepagents registers itself. A decision that consulted a bound list would grant
+ * `execute` at `manual` purely because the runner could not see it.
+ */
+export declare function isToolGatedAtRung(options: {
+    toolName: string;
+    rung: ApprovalRung;
+    gateShell: boolean;
+}): boolean;
+/**
+ * **The LIVE gated set: which bound tools the rung in force actually gates.** What a decision is
+ * measured against — the tool descriptions the model reads (§4.5) and the rater's granted-tools
+ * summary (§4.4) are both built from this, so neither can tell the model a tool is free while the
+ * gate escalates it.
+ *
+ * **It is NOT what the backends wire into the interrupt.** That is
+ * {@link resolveInterruptToolNames}, and the two are different sets on purpose: the interrupt is
+ * installed once, at agent init, while `/approvals <rung>` moves the rung underneath it for the rest
+ * of the session. A set that carried the rung would be frozen at the rung the session started on —
+ * and since the default is `assisted`, typing `/approvals manual` would leave exactly the write
+ * tools this design escalates ungated. So the interrupt is wired rung-independently and
+ * `GthAgentRunner.decideToolApproval` consults {@link isToolGatedAtRung} against the LIVE rung.
+ *
+ * **Derived from the bound toolset, never a hand-written list.** A static list of built-ins would
+ * leave MCP, custom and agent-authored tools out — the exact tools with no access class and so the
+ * exact tools the deterministic rungs must escalate. `boundToolNames` must therefore be the FINAL
+ * toolset the graph is handed, including tools the graph builder registers itself (deepagents'
+ * filesystem tools, `execute`, `task` and `write_todos` never appear in the array gsloth passes it).
+ *
+ * Order is stable: the shell first, then bound order. Duplicates are collapsed, so a caller may pass
+ * overlapping name sources without deduplicating first.
+ */
+export declare function resolveGatedToolNames(options: {
+    rung: ApprovalRung;
+    gateShell: boolean;
+    boundToolNames: readonly string[];
+}): readonly string[];
+/**
+ * {@link COMMAND_ANSWERS_APPROVALS} as a predicate. An unset command is a session driven by
+ * `GthAgentRunner` (nothing else leaves it unset), so it answers approvals.
+ *
+ * **`?? true` is the fail-safe default, not defensive noise.** The lookup yields `undefined` for a
+ * value outside {@link GthCommand}, and `undefined` is falsy — which would tell the caller to
+ * install NO approval interrupt, the one direction this predicate must never fail in. TypeScript
+ * makes that unreachable from inside this repo, but the function is re-exported from the public
+ * `@gaunt-sloth/core/config.js` barrel, so an untyped consumer can reach it. The coalesce restores
+ * runtime totality without weakening the compile-time totality the record already gives.
+ */
+export declare function commandAnswersApprovals(command: GthCommand | undefined): boolean;
+/**
+ * **The interrupt set: which tool names the backends wire into the approval interrupt.** Every bound
+ * tool that ANY rung could gate — the union of {@link resolveGatedToolNames} over
+ * {@link APPROVAL_RUNGS}, which in practice is the shell plus every bound tool that is not a
+ * built-in READ tool.
+ *
+ * One derivation for both backends, for the same reason {@link resolveShellApprovalGate} is one: the
+ * lean backend installs `humanInTheLoopMiddleware` directly and the deep backend installs the very
+ * same middleware through deepagents' `interruptOn`, and a set computed twice is a set that drifts.
+ *
+ * **Deliberately rung-independent.** The interrupt is installed once, when the agent is built, and
+ * `/approvals <rung>` then moves the rung for the rest of the session without rebuilding it. Only a
+ * set that covers every rung can survive that: the interrupt fires and
+ * `GthAgentRunner.decideToolApproval` decides on the rung in force, which is where the rung has
+ * always been read. **Wiring wider does not gate wider** — a call the live rung does not gate is
+ * approved there with no rating call and no prompt, so `assisted`, `auto` and `bypass` behave
+ * exactly as they do when the interrupt holds the shell alone.
+ *
+ * **Only for a command that answers approvals** ({@link commandAnswersApprovals}). A surface that
+ * drains nothing gets the shell-gate set instead, because a rung-independent set there parks tool
+ * calls nobody can reach.
+ */
+export declare function resolveInterruptToolNames(options: {
+    gateShell: boolean;
+    boundToolNames: readonly string[];
+}): readonly string[];
 /**
  * EXT-71 §3.1 — the **subject** axis of a rule entry, and only that. The schema twin is
  * `APPROVAL_ENTRY_TYPES` in `config/schema.ts`. What holds the two together is
@@ -572,7 +782,7 @@ export interface McpAnnotationTrustChange extends McpServerAnnotationTrust {
     invalidates: string[];
 }
 /**
- * §1.1 — **the default rung is `auto-safe`, everywhere.** It is the default in every interactive
+ * §1.1 — **the default rung is `assisted`, everywhere.** It is the default in every interactive
  * context, it does NOT vary with the configured model, and there is no separate non-interactive
  * default. What changes without a human is what an escalation *does* (§6.2: an immediate non-zero
  * exit, never an approval), not which rung the session starts on. A context-dependent default
@@ -582,7 +792,7 @@ export declare const DEFAULT_APPROVAL_RUNG: ApprovalRung;
 /**
  * CFG-27 — resolve the effective {@link ResolvedApprovals} for the active command.
  *
- * There is no defaults *matrix*: §1.1 makes `auto-safe` the default in every context, so this
+ * There is no defaults *matrix*: §1.1 makes `assisted` the default in every context, so this
  * resolver neither detects nor accepts a "context". Precedence is the only thing it decides, and
  * §9.1 splits it in two:
  *
@@ -667,10 +877,15 @@ export interface ShellApprovalGateDecision {
  *
  * What each rung then does is decided in `decideToolApproval`, not here:
  *   • `bypass` — deny list, then approve without prompting or rating.
- *   • `read-only`/`write` — deny list, allow-list, else escalate to the human.
- *   • `auto-safe`/`full-auto` — deny list, allow-list, then the rater.
- *   • With the shell tool disabled — or on a non-dev-tools command (chat/api/…) — nothing is gated
- *     and nothing is announced.
+ *   • `manual`/`write` — deny list, allow-list, else escalate to the human.
+ *   • `assisted`/`auto` — deny list, allow-list, then the rater.
+ *
+ * **This decides the SHELL's gating only, and it is not the whole gated set.** With the shell tool
+ * disabled — or on a non-dev-tools command (chat/api/…) — nothing about the shell is gated and
+ * nothing is announced, but at `manual` and `write` {@link resolveGatedToolNames} still gates
+ * every bound tool the rung does not auto-grant, so an MCP call in a plain `chat` session is
+ * escalated there. Read `gateShell` as "does the shell need the interrupt", never as "is the
+ * interrupt needed at all".
  *
  * Shell enablement itself is resolved through {@link getEffectiveDevToolsConfig} +
  * {@link isShellToolEnabled}, so the gate stays in lockstep with where `GthDevToolkit` actually