@gaunt-sloth/core 2.0.0-alpha.24 → 2.0.0-alpha.25

package/dist/config/schema.js

@@ -35,6 +35,9 @@
  * is additive and legitimately differs (no deprecated fields).
  */
 import { z } from 'zod';
+// `constants.ts` is a plain, import-free string module, so this does NOT compromise the purity
+// this file depends on (it feeds `z.toJSONSchema` and must stay cwd/fs-independent).
+import { GSLOTH_DIR, GSLOTH_SETTINGS_DIR } from '#src/constants.js';
 const filesystemSchema = z.union([z.array(z.string()), z.enum(['all', 'read', 'none'])]);
 /**
  * TLS trust for outbound HTTPS (MCP servers over `http` transport, and — because the mechanism is
@@ -84,18 +87,381 @@ const binaryFormatConfigSchema = z.object({
     mimeTypes: z.record(z.string(), z.string()).optional(),
 });
 const binaryFormatsSchema = z.union([z.literal(false), z.array(binaryFormatConfigSchema)]);
-const shellJudgeSchema = z.union([
-    z.boolean(),
+/**
+ * CFG-27 — the five rungs of the approvals ladder, as the schema sees them. Kept as a literal
+ * tuple here (rather than imported from `shell-policy.ts`) so the schema module stays the single
+ * pre-parse source of truth for what the config channel accepts; `APPROVAL_RUNGS` in
+ * `shell-policy.ts` is the runtime twin and `configSchema.spec.ts` pins the two together.
+ */
+const APPROVAL_RUNG_VALUES = ['read-only', 'write', 'auto-safe', 'full-auto', 'bypass'];
+/**
+ * EXT-71 §3.1 — the **subject** axis of a rule entry, and only that: `shell` is a command, `tool`
+ * a built-in or custom in-process tool, `mcpTool` a server's tool. The hand-written twin is
+ * `ApprovalEntryType` in `shell-policy.ts`. What holds the two together is
+ * `approvalEntrySchema.spec.ts`, where a list of `ApprovalEntry`-typed literals is parsed by this
+ * schema: a value either side stops accepting fails there. That is a weaker pin than a direct
+ * equality assertion — it catches a narrowing, not a widening on one side alone.
+ */
+export const APPROVAL_ENTRY_TYPES = ['shell', 'tool', 'mcpTool'];
+/**
+ * EXT-71 §3.1 — the **comparison** axis of a rule entry, and only that. `exact`/`glob`/`regexp`
+ * take a string pattern; `hint` takes an object over the annotation names and is valid on tool
+ * subjects only (on `shell` it is a config error — see {@link shellEntrySchema}).
+ */
+export const APPROVAL_ENTRY_MATCHERS = ['exact', 'glob', 'regexp', 'hint'];
+/**
+ * EXT-71 §3.1 / §4.7 — the four MCP `ToolAnnotations` booleans a `hint` pattern may name, and the
+ * names a user may list in `approvals.mcp.*.trustAnnotations` (§4.7.1). This is the whole
+ * vocabulary: an unknown name is a config error, never an ignored key, because a hint pattern that
+ * quietly drops a constraint matches MORE than its author wrote, and a trust list that quietly
+ * drops one reads as working while believing something else.
+ *
+ * **The runtime twin `TOOL_ANNOTATION_HINTS` in `shell-policy.ts` is a deliberate duplicate, and
+ * the reason is layering, not oversight.** Neither file may import the other. This module must stay
+ * pure and cwd/fs-independent because it feeds `z.toJSONSchema()` (see the header), and importing
+ * `shell-policy.ts` would pull `core/types.js` and the whole runtime policy surface into it;
+ * importing this module from there would in turn pull zod into every module that only wanted a
+ * policy type. So the vocabulary is written once per layer on purpose — do not "simplify" it by
+ * making one import the other. The equality assertion in `mcpApprovalsBlock.spec.ts` is what fails
+ * when they drift.
+ */
+export const HINT_ANNOTATION_KEYS = [
+    'readOnlyHint',
+    'destructiveHint',
+    'idempotentHint',
+    'openWorldHint',
+];
+/**
+ * EXT-71 §3.1 — the length cap on a `regexp` pattern, enforced when the config LOADS.
+ *
+ * 200 characters. The longest pattern the spec itself writes is under 40, and every rule entry
+ * names one command or tool shape rather than a grammar, so 200 is an order of magnitude of
+ * headroom over real use while still bounding what the matcher can ever be handed. The cap is a
+ * cheap load-time bound, NOT a backtracking defence — a short pattern can backtrack
+ * catastrophically too, and the run-time match budget is the separate backstop for that. What the
+ * cap buys is that a pattern nobody could have read and reviewed cannot be smuggled past load.
+ */
+export const APPROVAL_REGEXP_MAX_LENGTH = 200;
+/**
+ * EXT-71 §3.1 — a `hint` pattern: an object over {@link HINT_ANNOTATION_KEYS} mapping each named
+ * annotation to the boolean it must effectively hold. All named hints must match (AND within the
+ * entry); hints not named are unconstrained; `false` is the spelling of negation.
+ *
+ * Strict, and non-empty: an empty object or an unknown name is a hard config error and **never a
+ * match-everything**. `minProperties` is attached as metadata rather than being left to the
+ * refinement alone so the constraint survives into the emitted JSON Schema (zod drops refinements
+ * there), which is what the hosted schema channels and editor validation actually read.
+ */
+const hintPatternSchema = z
+    .strictObject({
+    readOnlyHint: z.boolean().optional(),
+    destructiveHint: z.boolean().optional(),
+    idempotentHint: z.boolean().optional(),
+    openWorldHint: z.boolean().optional(),
+})
+    .meta({ minProperties: 1 })
+    .refine((pattern) => Object.keys(pattern).length > 0, {
+    message: 'a hint pattern must name at least one of ' +
+        HINT_ANNOTATION_KEYS.join(', ') +
+        ' — an empty object is a config error, never a match-everything',
+});
+/**
+ * EXT-71 §3.1 — a `regexp` pattern: capped at {@link APPROVAL_REGEXP_MAX_LENGTH} and required to
+ * COMPILE when the config loads, never when it first runs. Both failures name the offending
+ * pattern in the message: an entry the user cannot trace back to the line they wrote is
+ * indistinguishable from a bug.
+ *
+ * `.max()` is kept alongside the refinement so the cap emits as `maxLength` in the JSON Schema
+ * (refinements do not survive `z.toJSONSchema`); the refinement is what produces the message that
+ * quotes the pattern.
+ */
+const regexpPatternSchema = z
+    .string()
+    .max(APPROVAL_REGEXP_MAX_LENGTH)
+    .superRefine((pattern, ctx) => {
+    if (pattern.length > APPROVAL_REGEXP_MAX_LENGTH) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `regexp pattern ${JSON.stringify(pattern)} is ${pattern.length} characters, over the ` +
+                `${APPROVAL_REGEXP_MAX_LENGTH}-character cap for an approvals rule pattern`,
+        });
+        return;
+    }
+    try {
+        new RegExp(pattern);
+    }
+    catch (e) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `regexp pattern ${JSON.stringify(pattern)} does not compile: ` +
+                `${e instanceof Error ? e.message : String(e)}`,
+        });
+    }
+});
+/** `rate` (§3.2) — optional on EVERY entry type, and the only optional field they all share. */
+const rateField = { rate: z.boolean().optional() };
+/**
+ * `host` (§4.7.4) — optional on TOOL subjects only, exact-match. Forbidden on `shell`, where the
+ * host is already inside the command string; the shell arms are strict objects, so writing it
+ * there is an unrecognized-key error.
+ */
+const hostField = { host: z.string().min(1).optional() };
+/**
+ * EXT-71 §3.1 — a `shell` entry. `matcher` deliberately omits `hint`: a command carries no tool
+ * annotations, so `{"type":"shell","matcher":"hint"}` is a discriminator error naming the three
+ * matchers a command actually supports. Neither `server` nor `host` exists here.
+ */
+const shellEntrySchema = z.discriminatedUnion('matcher', [
+    z.strictObject({
+        type: z.literal('shell'),
+        matcher: z.literal('exact'),
+        pattern: z.string(),
+        ...rateField,
+    }),
+    z.strictObject({
+        type: z.literal('shell'),
+        matcher: z.literal('glob'),
+        pattern: z.string(),
+        ...rateField,
+    }),
+    z.strictObject({
+        type: z.literal('shell'),
+        matcher: z.literal('regexp'),
+        pattern: regexpPatternSchema,
+        ...rateField,
+    }),
+]);
+/** EXT-71 §3.1 — a `tool` entry: a built-in or custom in-process tool, matched on its name. */
+const toolEntrySchema = z.discriminatedUnion('matcher', [
+    z.strictObject({
+        type: z.literal('tool'),
+        matcher: z.literal('exact'),
+        pattern: z.string(),
+        ...hostField,
+        ...rateField,
+    }),
+    z.strictObject({
+        type: z.literal('tool'),
+        matcher: z.literal('glob'),
+        pattern: z.string(),
+        ...hostField,
+        ...rateField,
+    }),
+    z.strictObject({
+        type: z.literal('tool'),
+        matcher: z.literal('regexp'),
+        pattern: regexpPatternSchema,
+        ...hostField,
+        ...rateField,
+    }),
+    z.strictObject({
+        type: z.literal('tool'),
+        matcher: z.literal('hint'),
+        pattern: hintPatternSchema,
+        ...hostField,
+        ...rateField,
+    }),
+]);
+/**
+ * EXT-71 §3.1 — an `mcpTool` entry. `server` is **required** here and exists nowhere else: it is
+ * the user's own key in `mcpServers` (§4.7.5), the only stable, unique, user-authored identity a
+ * server has. The literal `*` is reserved to mean every server, which is why a configured server
+ * may not be named `*` ({@link findApprovalsGrammarIssues}).
+ */
+const mcpToolEntrySchema = z.discriminatedUnion('matcher', [
+    z.strictObject({
+        type: z.literal('mcpTool'),
+        matcher: z.literal('exact'),
+        server: z.string().min(1),
+        pattern: z.string(),
+        ...hostField,
+        ...rateField,
+    }),
+    z.strictObject({
+        type: z.literal('mcpTool'),
+        matcher: z.literal('glob'),
+        server: z.string().min(1),
+        pattern: z.string(),
+        ...hostField,
+        ...rateField,
+    }),
+    z.strictObject({
+        type: z.literal('mcpTool'),
+        matcher: z.literal('regexp'),
+        server: z.string().min(1),
+        pattern: regexpPatternSchema,
+        ...hostField,
+        ...rateField,
+    }),
+    z.strictObject({
+        type: z.literal('mcpTool'),
+        matcher: z.literal('hint'),
+        server: z.string().min(1),
+        pattern: hintPatternSchema,
+        ...hostField,
+        ...rateField,
+    }),
+]);
+/**
+ * EXT-71 §3.1 — **one** entry in `allow`, `deny` or `escalate`. All three lists take the same
+ * shape, so there is one schema and the list a rule sits in decides only what a match DOES.
+ *
+ * `type`, `matcher` and `pattern` are required on every arm: no field is inferred, and no entry
+ * reads two ways. Every arm is a strict object, so any field the grammar does not define — a typo,
+ * a `server` on a `shell` entry, a `host` on a `shell` entry — is an unrecognized-key error rather
+ * than a silently-ignored key that would widen what the entry matches.
+ *
+ * The `id` is what makes the emitted JSON Schema hoist this union into `$defs` and reference it,
+ * instead of inlining all eleven arms into each of the twenty-four places a rule list appears
+ * (three lists × the root plus seven commands). That is the difference between a schema an editor loads
+ * and one it chokes on, and `$ref` is the standard spelling every JSON Schema consumer already
+ * understands.
+ */
+export const approvalEntrySchema = z
+    .discriminatedUnion('type', [shellEntrySchema, toolEntrySchema, mcpToolEntrySchema])
+    .meta({ id: 'ApprovalEntry' });
+/** The three rule lists, keyed as they appear under `approvals` (§3, §9). */
+const APPROVAL_LIST_KEYS = ['allow', 'deny', 'escalate'];
+/**
+ * EXT-70 §4.7.1/§9.1 — `trustAnnotations`: **the hints believed from one server**, as a LIST of
+ * {@link HINT_ANNOTATION_KEYS} names and never a boolean, because trusting `readOnlyHint` while
+ * distrusting `openWorldHint` is a coherent position and the common one.
+ *
+ * An unknown name is a hard config error rather than an ignored member: a list that quietly drops
+ * a name the user believed they wrote trusts LESS than they asked in one direction and reads as a
+ * working config in the other, and a trust list nobody can verify from its own error output is
+ * worse than none. The custom message quotes the offending value, since the path alone gives an
+ * index and the user needs the word they mistyped.
+ */
+const trustAnnotationsSchema = z.array(z.enum(HINT_ANNOTATION_KEYS, {
+    error: (issue) => `${JSON.stringify(issue.input)} is not an MCP tool annotation. trustAnnotations names the ` +
+        `hints believed from a server, and the whole vocabulary is ` +
+        `${HINT_ANNOTATION_KEYS.join(', ')}.`,
+}));
+/**
+ * EXT-70 §4.7/§9 — one server's entry under `approvals.mcp.servers`, and the shape `defaults`
+ * takes. **Strict**: an unrecognized key is an error, so a hint list misspelt as a whole key
+ * (`trustAnnotation`, `trust`) fails loudly instead of silently trusting nothing while reading as
+ * though it trusted something.
+ */
+const mcpServerApprovalsSchema = z.strictObject({
+    trustAnnotations: trustAnnotationsSchema.optional(),
+});
+/**
+ * EXT-70 §4.7/§9 — the `approvals.mcp` block. `defaults` covers servers not named under `servers`;
+ * `servers` is keyed by the user's own `mcpServers` config key (§4.7.5) and is deliberately NOT
+ * checked against `mcpServers`, so policy may be written before the server it describes.
+ *
+ * Strict, and it stays strict: `expose` (§4.7.6) belongs to [[EXT-73]] and is not accepted here
+ * until that node adds it deliberately. A permissive block would accept `expose` today, do nothing
+ * with it, and leave a user believing their tools were filtered.
+ */
+const mcpApprovalsSchema = z.strictObject({
+    defaults: mcpServerApprovalsSchema.optional(),
+    servers: z.record(z.string().min(1), mcpServerApprovalsSchema).optional(),
+});
+/**
+ * EXT-71 §3.1 — render an entry in the object form the user would write in a config file, with the
+ * fields in grammar order (`type`, `server`, `matcher`, `pattern`, then the optional bounds).
+ *
+ * The ONE place that spelling is produced, because it is shown in two very different moments that
+ * must agree: the load-time error that tells a user what to write instead of their bare string, and
+ * the escalation menu's *this is what will be stored* line (§6). A grant the menu describes one way
+ * and stores another is exactly the drift this design cannot afford.
+ */
+export function renderApprovalEntryObject(entry) {
+    const fields = [['type', entry.type]];
+    if (entry.server !== undefined)
+        fields.push(['server', entry.server]);
+    fields.push(['matcher', entry.matcher], ['pattern', entry.pattern]);
+    if (entry.host !== undefined)
+        fields.push(['host', entry.host]);
+    if (entry.rate !== undefined)
+        fields.push(['rate', entry.rate]);
+    const rendered = fields.map(([key, value]) => `${JSON.stringify(key)}: ${JSON.stringify(value)}`);
+    return `{ ${rendered.join(', ')} }`;
+}
+/**
+ * EXT-71 §2.3/§9.1 — render the object form of a bare string found in a rule list, so the
+ * migration error shows the user the entry they should have written *for their own string*
+ * rather than a generic example.
+ */
+export function renderApprovalEntryForString(pattern) {
+    return renderApprovalEntryObject({ type: 'shell', matcher: 'exact', pattern });
+}
+/**
+ * CFG-27 — the `approvals` value: **either the rung name on its own, or an object when the extras
+ * are needed** (spec §9). There are no other approvals keys.
+ *
+ * ```jsonc
+ * { "approvals": "auto-safe" }
+ * ```
+ * ```jsonc
+ * { "approvals": {
+ *     "mode": "auto-safe",
+ *     "rater": "safety-rater",                     // identity profile the rater runs under
+ *     "allow":    [ { "type": "shell", "matcher": "exact", "pattern": "npm test" } ],
+ *     "deny":     [ { "type": "shell", "matcher": "glob",  "pattern": "npm publish*" } ],
+ *     "escalate": [ { "type": "shell", "matcher": "exact", "pattern": "terraform apply" } ]
+ * } }
+ * ```
+ *
+ * - **The scalar form is exactly sugar for `{ "mode": <value> }`** (§9.1). The union exists so the
+ *   extras have a home when they are needed, not so there are two ways to say the same thing.
+ * - `rater` is a **bare identity-profile name**, not an object (strict resolution, GS2-62: a name
+ *   that does not resolve is a hard config error, never a silent fallback).
+ * - `raterTimeoutMs` (EXT-66) is the wall-clock budget for ONE rating call, defaulting to
+ *   `RATER_DEFAULT_TIMEOUT_MS` (30s) at the read site. **It exists because 30s is a hosted-model
+ *   number and a local model is knowably slower**: measured 2026-07-31, `gemma4:12b` over Ollama
+ *   answered a 23-case corpus in 6.0s–114.7s, and at the fixed limit 3 of 18 calls in one run and
+ *   9 of 17 in the next were cut off — so a local `full-auto` session degraded toward escalating
+ *   everything, which is the opposite of what the rung is for. Deliberately a number the user owns
+ *   rather than a provider→timeout table: a table is a guess about someone else's hardware, and
+ *   the failure it causes is silent.
+ * - `allow`/`deny`/`escalate` are **read-only input**: merged with the runtime stores the
+ *   escalation menu writes, and never written back to config. Every entry is the §3.1 object
+ *   ({@link approvalEntrySchema}); a bare string in any of the three is a hard config error whose
+ *   message shows the object form of that same string ({@link findApprovalsGrammarIssues}).
+ * - `escalate` is the third list (§3, §3.2): a match always asks the human, whatever the rung
+ *   would have done. It takes the same entries as the other two.
+ * - `mcp` (EXT-70 §4.7) holds the per-server relationship — which hints are believed from which
+ *   server — keyed by the user's own `mcpServers` config key, with `defaults` for servers not
+ *   named. Absent or empty `trustAnnotations` believes nothing external, which is also the default.
+ * - The retired `strictness` / `allowlist` / `persistAllowlist` keys and the retired `auto` / `ask`
+ *   mode values are hard migration errors naming their replacement — see `RETIRED_APPROVALS_KEYS` /
+ *   `RETIRED_APPROVAL_MODES` in {@link findDeprecatedConfigIssues}. So is a NON-ARRAY `escalate`,
+ *   which is the retired severity threshold rather than the new list.
+ *
+ * Defaults are applied at the READ site (`resolveApprovals` in `shell-policy.ts`), not in
+ * DEFAULT_CONFIG, so the effective-config snapshot never churns (à la GS2-34/GS2-63).
+ *
+ * NOTE: "judge" is reserved for the eval grader (`gth eval --judge <profile>`) — a different
+ * concept that keeps its name.
+ */
+const approvalsSchema = z.union([
+    z.enum(APPROVAL_RUNG_VALUES),
     z.object({
-        enabled: z.boolean().optional(),
-        autoApproveLow: z.boolean().optional(),
-        blockHigh: z.boolean().optional(),
-        model: llmConfigSchema.optional(),
+        mode: z.enum(APPROVAL_RUNG_VALUES).optional(),
+        rater: z.string().optional(),
+        // EXT-71 §3.1 — the three rule lists. Same entry grammar in all three; the list decides only
+        // what a match DOES (§3: deny over escalate over allow).
+        allow: z.array(approvalEntrySchema).optional(),
+        deny: z.array(approvalEntrySchema).optional(),
+        escalate: z.array(approvalEntrySchema).optional(),
+        // EXT-66 — wall-clock budget (ms) for one rating call. See the note on the union above for
+        // why this is a user-owned number rather than a per-provider table.
+        // `.min(1)`, not `.positive()`: the latter emits `exclusiveMinimum`, a JSON-Schema draft
+        // keyword this repo avoids on principle (GS2-57 — Google GenAI rejects it outright in tool
+        // declarations). This schema is not a tool declaration, but one spelling everywhere is what
+        // stops the wrong one being copied into somewhere that is.
+        raterTimeoutMs: z.number().int().min(1).optional(),
+        // EXT-70 §4.7/§9 — the per-server MCP relationship, keyed by the user's own `mcpServers` key.
+        mcp: mcpApprovalsSchema.optional(),
     }),
 ]);
 /**
  * EXT-36 — the tool-loop guard (repeated identical `(tool, args)` / no-progress detector), the
- * orthogonal sibling of GS2-36's error budget. Modeled on {@link shellJudgeSchema}: `false` disables
+ * orthogonal sibling of GS2-36's error budget. A boolean-or-object union: `false` disables
  * it entirely; `true`/absent is warn-on defaults; the object form is fine-grained. `warn` (default
  * ON) injects a control-flow-free nudge at the threshold; `halt` (default OFF, opt-in) ends the run
  * cleanly at the threshold; `threshold` is the number of consecutive identical calls that trip it.
@@ -113,19 +479,20 @@ const toolLoopGuardSchema = z.union([
 /**
  * CFG-18 — the per-tool config object carried as a value in the widened `builtInTools` registry.
  * One permissive shape covering every tool: `command` for the fixed dev-command tools
- * (run_tests/run_lint/run_build/run_single_test), the EXT-9/10/12 knobs for `run_shell_command`
- * (`yolo` is the folded former `shellYolo`), `fileSet` for `gth_grep` (GS2-51), and `enabled` for a
- * plain built-in tool.
+ * (run_tests/run_lint/run_build/run_single_test), the EXT-12 execution knobs for
+ * `run_shell_command` (`timeout`/`maxOutputBytes`), `fileSet` for `gth_grep` (GS2-51), and
+ * `enabled` for a plain built-in tool.
+ *
+ * CFG-26 — the APPROVAL knobs that used to live here (`allowlist`, `persistAllowlist`, `judge`,
+ * `yolo`) moved to the top-level {@link approvalsSchema}. They were fields of the object shared by
+ * EVERY built-in tool, which is why a nonsensical `gth_grep: { yolo: true }` validated. Each is now
+ * a hard migration error — see `RETIRED_SHELL_TOOL_PAIRS` in {@link findDeprecatedConfigIssues}.
  */
 const builtInToolConfigSchema = z.object({
     enabled: z.boolean().optional(),
     command: z.string().optional(),
     timeout: z.number().optional(),
     maxOutputBytes: z.number().optional(),
-    allowlist: z.boolean().optional(),
-    persistAllowlist: z.boolean().optional(),
-    judge: shellJudgeSchema.optional(),
-    yolo: z.boolean().optional(),
     // GS2-51 — `gth_grep`: which corpus to search. `gitignore` (default) respects .gitignore/.ignore
     // and skips hidden dot-files; `all` scans everything but the noise dirs. See BuiltInToolConfig.
     fileSet: z.enum(['gitignore', 'all']).optional(),
@@ -179,6 +546,9 @@ const prCommandSchema = z.object({
     requirementSource: z.string().optional(),
     filesystem: filesystemSchema.optional(),
     builtInTools: builtInToolsSchema.optional(),
+    // CFG-27/§9.1 — per-command approvals. It overrides only the fields it names: `mode`,
+    // `rater`, `raterTimeoutMs` and `allow` replace the root's; `deny`/`escalate` concatenate.
+    approvals: approvalsSchema.optional(),
     customTools: customToolsOrFalseSchema.optional(),
     allowedTools: z.array(z.string()).optional(),
     logWorkForReviewInSeconds: z.number().optional(),
@@ -190,6 +560,9 @@ const reviewCommandSchema = z.object({
     requirementSource: z.string().optional(),
     filesystem: filesystemSchema.optional(),
     builtInTools: builtInToolsSchema.optional(),
+    // CFG-27/§9.1 — per-command approvals. It overrides only the fields it names: `mode`,
+    // `rater`, `raterTimeoutMs` and `allow` replace the root's; `deny`/`escalate` concatenate.
+    approvals: approvalsSchema.optional(),
     customTools: customToolsOrFalseSchema.optional(),
     allowedTools: z.array(z.string()).optional(),
     rating: ratingConfigSchema.optional(),
@@ -198,6 +571,9 @@ const reviewCommandSchema = z.object({
 const askCommandSchema = z.object({
     filesystem: filesystemSchema.optional(),
     builtInTools: builtInToolsSchema.optional(),
+    // CFG-27/§9.1 — per-command approvals. It overrides only the fields it names: `mode`,
+    // `rater`, `raterTimeoutMs` and `allow` replace the root's; `deny`/`escalate` concatenate.
+    approvals: approvalsSchema.optional(),
     customTools: customToolsOrFalseSchema.optional(),
     allowedTools: z.array(z.string()).optional(),
     binaryFormats: binaryFormatsSchema.optional(),
@@ -205,6 +581,9 @@ const askCommandSchema = z.object({
 const chatCommandSchema = z.object({
     filesystem: filesystemSchema.optional(),
     builtInTools: builtInToolsSchema.optional(),
+    // CFG-27/§9.1 — per-command approvals. It overrides only the fields it names: `mode`,
+    // `rater`, `raterTimeoutMs` and `allow` replace the root's; `deny`/`escalate` concatenate.
+    approvals: approvalsSchema.optional(),
     customTools: customToolsOrFalseSchema.optional(),
     allowedTools: z.array(z.string()).optional(),
     binaryFormats: binaryFormatsSchema.optional(),
@@ -212,6 +591,9 @@ const chatCommandSchema = z.object({
 const codeCommandSchema = z.object({
     filesystem: filesystemSchema.optional(),
     builtInTools: builtInToolsSchema.optional(),
+    // CFG-27/§9.1 — per-command approvals. It overrides only the fields it names: `mode`,
+    // `rater`, `raterTimeoutMs` and `allow` replace the root's; `deny`/`escalate` concatenate.
+    approvals: approvalsSchema.optional(),
     customTools: customToolsOrFalseSchema.optional(),
     allowedTools: z.array(z.string()).optional(),
     binaryFormats: binaryFormatsSchema.optional(),
@@ -219,6 +601,9 @@ const codeCommandSchema = z.object({
 const execCommandSchema = z.object({
     filesystem: filesystemSchema.optional(),
     builtInTools: builtInToolsSchema.optional(),
+    // CFG-27/§9.1 — per-command approvals. It overrides only the fields it names: `mode`,
+    // `rater`, `raterTimeoutMs` and `allow` replace the root's; `deny`/`escalate` concatenate.
+    approvals: approvalsSchema.optional(),
     customTools: customToolsOrFalseSchema.optional(),
     allowedTools: z.array(z.string()).optional(),
     binaryFormats: binaryFormatsSchema.optional(),
@@ -226,6 +611,9 @@ const execCommandSchema = z.object({
 const apiCommandSchema = z.object({
     filesystem: filesystemSchema.optional(),
     builtInTools: builtInToolsSchema.optional(),
+    // CFG-27/§9.1 — per-command approvals. It overrides only the fields it names: `mode`,
+    // `rater`, `raterTimeoutMs` and `allow` replace the root's; `deny`/`escalate` concatenate.
+    approvals: approvalsSchema.optional(),
     port: z.number().optional(),
     cors: z
         .object({
@@ -318,6 +706,12 @@ export const rawGthConfigSchema = z.looseObject({
     noDefaultPrompts: z.boolean().optional(),
     filesystem: filesystemSchema.optional(),
     builtInTools: builtInToolsSchema.optional(),
+    // CFG-27 — the approvals ladder: a rung name, or an object carrying the rater profile and the
+    // declared allow/deny lists. Settable at the root or per command
+    // (`commands.<command>.approvals`, which per §9.1 overrides only the fields it names — the
+    // restrictive lists concatenate across scopes, `allow` replaces). Absent = `auto-safe`
+    // (`resolveApprovals` in shell-policy.ts).
+    approvals: approvalsSchema.optional(),
     // Live tool instances / toolkits in JS configs — kept permissive.
     tools: z.array(z.unknown()).optional(),
     allowedTools: z.array(z.string()).optional(),
@@ -326,7 +720,15 @@ export const rawGthConfigSchema = z.looseObject({
     streamOutput: z.boolean().optional(),
     writeOutputToFile: z.union([z.boolean(), z.string()]).optional(),
     writeBinaryOutputsToFile: z.boolean().optional(),
+    // CFG-30 — rung 3 of the colour ladder (`config/colour.ts`), NOT the final say: `FORCE_COLOR`
+    // and `NO_COLOR` outrank it, and when it is absent colour auto-detects from stdout's TTY status.
+    // MUST stay `.optional()` — absence is what distinguishes "the user chose true" from the `true`
+    // in `defaults.ts`, and the ladder collapses without that. User docs: docs/configuration/output.md
     useColour: z.boolean().optional(),
+    // TUI-C37 — rung 2 of the mouse ladder (`config/mouse.ts`). MUST stay `.optional()` for the same
+    // reason as `useColour`: absence is what tells "the user chose true" from the `true` in
+    // `defaults.ts`, and rung 2 collapses into rung 4 without it.
+    useMouse: z.boolean().optional(),
     streamSessionInferenceLog: z.boolean().optional(),
     canInterruptInferenceWithEsc: z.boolean().optional(),
     debugLog: z.boolean().optional(),
@@ -472,6 +874,94 @@ const DEPRECATED_COMMAND_PAIRS = [
 const REMOVED_COMMAND_KEYS = [
     ['devTools', 'builtInTools'],
 ];
+/**
+ * CFG-26 — approval knobs retired from the `builtInTools.run_shell_command` entry and moved to the
+ * top-level `approvals` block. `[retired, "how to say it now"]`. Rejected pre-parse for the same
+ * reason as {@link REMOVED_COMMAND_KEYS}: `builtInToolConfigSchema` is a strict `z.object`, so once
+ * the field is gone zod SILENTLY STRIPS it and an old config would run with its approval posture
+ * quietly ignored — the worst possible failure for a safety gate.
+ *
+ * `judge.autoApproveLow` / `judge.blockHigh` have no 1:1 successor (the rung replaced the
+ * `low/medium/high` × `destructive` conjunction), so `judge`'s message points at `approvals.mode`
+ * and names the outcome scale that took the tiers' place.
+ */
+const RETIRED_SHELL_TOOL_PAIRS = [
+    ['yolo', '"approvals": "bypass"'],
+    [
+        'judge',
+        '"approvals": "auto-safe" (or "full-auto"), optionally with "approvals.rater" naming an ' +
+            'identity profile — the low/medium/high tiers became the ' +
+            'safe/destructive/catastrophic/attack outcomes, and autoApproveLow/blockHigh are replaced ' +
+            'by the rung you choose',
+    ],
+    ['allowlist', '"approvals.allow" (a declared list of rule entries)'],
+    [
+        'persistAllowlist',
+        'nothing — persistence is a per-decision choice at the approval prompt (approve forgets, ' +
+            'always approve persists)',
+    ],
+];
+/** The `builtInTools` entry the retired approval knobs used to hang off. */
+const SHELL_TOOL_REGISTRY_KEY = 'run_shell_command';
+/**
+ * CFG-27 — keys retired from the `approvals` object itself when the four-tier lattice became one
+ * ordered ladder of five rungs. `[retired, "how to say it now"]`.
+ *
+ * Rejected PRE-PARSE rather than left to the union: `approvalsSchema`'s object arm is a `z.object`,
+ * which silently strips unknown keys, so an `approvals: { mode: "auto-safe", strictness: "strict" }`
+ * would otherwise run with its declared posture quietly ignored — the worst possible failure for a
+ * safety gate, and exactly what CFG-26 fixed for the per-tool knobs.
+ *
+ * `strictness` is **deleted, not remapped**: there are no severity thresholds and no independent
+ * rater switch, so the message points at the rung that expresses the intent.
+ *
+ * The retired severity threshold `escalate` is NOT in this table, because EXT-71 gave the name back
+ * as the third rule list (§3). A non-array `escalate` — the shape the threshold had — is still
+ * caught, with the same message, by {@link RETIRED_ESCALATE_THRESHOLD_MESSAGE}.
+ */
+const RETIRED_APPROVALS_KEYS = [
+    [
+        'strictness',
+        'nothing — there are no strictness levels any more. Choose a rung instead: ' +
+            '"read-only"/"write" never rate, "auto-safe" escalates anything not rated safe, ' +
+            '"full-auto" lets the auto-rater decide',
+    ],
+    ['allowlist', '"approvals.allow" (a declared list of rule entries)'],
+    [
+        'persistAllowlist',
+        'nothing — persistence is a per-decision choice at the approval prompt (approve forgets, ' +
+            'always approve persists)',
+    ],
+];
+/**
+ * EXT-71 — `approvals.escalate` used to be a SEVERITY THRESHOLD (a string), and is now the third
+ * rule LIST (an array of §3.1 entries). Only the old shape is an error, so the name could be
+ * reused without stranding anyone: a non-array value gets the message that names the rung which
+ * expresses the old intent, instead of a bare "expected array, received string".
+ */
+const RETIRED_ESCALATE_THRESHOLD_MESSAGE = 'is now the third rule LIST (an array of {type, matcher, pattern} entries that always ask the ' +
+    'human), not a severity threshold. There is no escalate threshold any more: "auto-safe" ' +
+    'escalates everything the auto-rater does not rate safe, and "full-auto" does not stop to ask.';
+/**
+ * CFG-27 — retired `approvals.mode` VALUES → the rung that replaced them. The three-mode
+ * vocabulary is gone: `auto` was the rater-mediated mode (now the `auto-safe` rung) and `ask`
+ * meant "prompt for everything the allow-list does not cover" (now `read-only`, or `write` if the
+ * agent should still edit files freely). `bypass` survives unchanged and is deliberately absent.
+ *
+ * Caught here rather than by the enum so the error NAMES the rung instead of listing five
+ * identifiers and leaving the user to guess which one preserves their intent.
+ */
+const RETIRED_APPROVAL_MODES = [
+    [
+        'auto',
+        '"auto-safe" (the auto-rater rates every gated call and escalates anything questionable)',
+    ],
+    [
+        'ask',
+        '"write" (Gaunt Sloth edits files freely and asks about everything else) or "read-only" ' +
+            '(it asks before writing too)',
+    ],
+];
 /**
  * Pointer to the migration path, appended to every deprecated-shape error so the user
  * always learns HOW to fix it, not just that it broke. Doc link only, per DOC-STYLE
@@ -480,6 +970,99 @@ const REMOVED_COMMAND_KEYS = [
  * reference here when that tooling lands.
  */
 const MIGRATION_HINT = 'See the 2.0 migration notes: https://github.com/pukeko-robotics/gaunt-sloth/blob/main/docs/MIGRATION.md';
+/**
+ * CFG-26 — scan one `builtInTools` value (root or per-command) for the retired
+ * `run_shell_command` approval knobs, pushing one issue per occurrence. Only the OBJECT registry
+ * form can carry them (the legacy `string[]` form is names-only), so an array/non-object value is
+ * a no-op. `pathPrefix` is `builtInTools` at the root and `commands.<name>.builtInTools` per
+ * command, so the reported path points exactly at the offending key.
+ */
+function collectRetiredShellToolIssues(builtInTools, pathPrefix, issues) {
+    if (!builtInTools || typeof builtInTools !== 'object' || Array.isArray(builtInTools))
+        return;
+    const shellEntry = builtInTools[SHELL_TOOL_REGISTRY_KEY];
+    if (!shellEntry || typeof shellEntry !== 'object' || Array.isArray(shellEntry))
+        return;
+    for (const [retired, replacement] of RETIRED_SHELL_TOOL_PAIRS) {
+        if (Object.prototype.hasOwnProperty.call(shellEntry, retired)) {
+            issues.push({
+                path: `${pathPrefix}.${SHELL_TOOL_REGISTRY_KEY}.${retired}`,
+                message: `Config property "${retired}" in ${pathPrefix}.${SHELL_TOOL_REGISTRY_KEY} is no longer ` +
+                    `supported in 2.0. Use ${replacement} instead. ${MIGRATION_HINT}`,
+            });
+        }
+    }
+}
+/**
+ * CFG-27 — scan one `approvals` value (root or per-command) for the keys and `mode` values the
+ * five-rung ladder retired, pushing one issue per occurrence. The scalar form carries no keys, so
+ * only the object form can offend — except for a retired `mode` VALUE, which the scalar form can
+ * carry directly (`"approvals": "auto"`), so both shapes are checked for that.
+ *
+ * `pathPrefix` is `approvals` at the root and `commands.<name>.approvals` per command, so the
+ * reported path points exactly at the offending key.
+ */
+function collectRetiredApprovalsIssues(approvals, pathPrefix, issues) {
+    if (approvals === undefined || approvals === null)
+        return;
+    // The scalar sugar form: `"approvals": "auto"`. Only a retired VALUE is an issue here; an
+    // unknown string is left to the enum, which lists the five valid rungs.
+    if (typeof approvals === 'string') {
+        for (const [retired, replacement] of RETIRED_APPROVAL_MODES) {
+            if (approvals === retired) {
+                issues.push({
+                    path: pathPrefix,
+                    message: `Approval mode "${retired}" is no longer supported: approvals is now one ordered ` +
+                        `ladder of five rungs (read-only, write, auto-safe, full-auto, bypass). ` +
+                        `Use ${replacement} instead. ${MIGRATION_HINT}`,
+                });
+            }
+        }
+        return;
+    }
+    if (typeof approvals !== 'object' || Array.isArray(approvals))
+        return;
+    const block = approvals;
+    for (const [retired, replacement] of RETIRED_APPROVALS_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(block, retired)) {
+            issues.push({
+                path: `${pathPrefix}.${retired}`,
+                message: `Config property "${retired}" in ${pathPrefix} is no longer supported: approvals is now ` +
+                    `one ordered ladder of five rungs (read-only, write, auto-safe, full-auto, bypass), ` +
+                    `and each rung fully determines behaviour. Use ${replacement}. ${MIGRATION_HINT}`,
+            });
+        }
+    }
+    // EXT-71 — `escalate` reused for the third rule list; only the retired THRESHOLD shape errors.
+    if (block.escalate !== undefined && !Array.isArray(block.escalate)) {
+        issues.push({
+            path: `${pathPrefix}.escalate`,
+            message: `Config property "escalate" in ${pathPrefix} ${RETIRED_ESCALATE_THRESHOLD_MESSAGE} ` +
+                MIGRATION_HINT,
+        });
+    }
+    // `rater` flattened from an object to a bare identity-profile name.
+    const rater = block.rater;
+    if (rater !== undefined && typeof rater !== 'string') {
+        issues.push({
+            path: `${pathPrefix}.rater`,
+            message: `Config property "rater" in ${pathPrefix} is now a bare identity-profile name, not an ` +
+                `object or a boolean (e.g. "rater": "safety-rater"). Whether the rater runs at all is ` +
+                `decided by the rung: "auto-safe" and "full-auto" rate, the other three never do. ` +
+                MIGRATION_HINT,
+        });
+    }
+    for (const [retired, replacement] of RETIRED_APPROVAL_MODES) {
+        if (block.mode === retired) {
+            issues.push({
+                path: `${pathPrefix}.mode`,
+                message: `Approval mode "${retired}" is no longer supported: approvals is now one ordered ladder ` +
+                    `of five rungs (read-only, write, auto-safe, full-auto, bypass). Use ${replacement} ` +
+                    `instead. ${MIGRATION_HINT}`,
+            });
+        }
+    }
+}
 /**
  * GS2-28 — detect the removed pre-2.0 config shapes on the RAW input (read-only; no
  * mutation), returning one {@link DeprecatedConfigIssue} per occurrence. A non-empty
@@ -491,7 +1074,13 @@ const MIGRATION_HINT = 'See the 2.0 migration notes: https://github.com/pukeko-r
  * - (C) a deprecated `*Provider*` name ({@link DEPRECATED_ROOT_PAIRS} at root,
  *   {@link DEPRECATED_COMMAND_PAIRS} per command) — must use its `*Source*` replacement;
  * - (D, CFG-18) a removed per-command key folded into another ({@link REMOVED_COMMAND_KEYS}, e.g.
- *   `commands.<cmd>.devTools` → configure under `builtInTools`).
+ *   `commands.<cmd>.devTools` → configure under `builtInTools`);
+ * - (E, CFG-26) a retired `run_shell_command` approval knob ({@link RETIRED_SHELL_TOOL_PAIRS}) at
+ *   EITHER `builtInTools.run_shell_command.*` or `commands.<cmd>.builtInTools.run_shell_command.*`
+ *   — each message names the `approvals.*` key that replaced it;
+ * - (F, CFG-27) a retired `approvals` key or `mode` value ({@link RETIRED_APPROVALS_KEYS},
+ *   {@link RETIRED_APPROVAL_MODES}) at EITHER `approvals.*` or `commands.<cmd>.approvals.*` —
+ *   each message names the rung that replaced it.
  *
  * Runs on the raw input specifically so nested `commands.*.contentProvider` is still visible
  * (zod's per-command `z.object` would strip it before any schema-embedded check could fire).
@@ -520,6 +1109,10 @@ export function findDeprecatedConfigIssues(raw) {
             });
         }
     }
+    // (E, CFG-26) Retired run_shell_command approval knobs at the ROOT builtInTools registry.
+    collectRetiredShellToolIssues(raw.builtInTools, 'builtInTools', issues);
+    // (F, CFG-27) Retired approvals keys / mode values in the ROOT approvals value.
+    collectRetiredApprovalsIssues(raw.approvals, 'approvals', issues);
     // (C) Deprecated *Provider* names + (CFG-18) removed keys inside each commands.<name> block.
     const commands = raw.commands;
     if (commands && typeof commands === 'object' && !Array.isArray(commands)) {
@@ -544,11 +1137,221 @@ export function findDeprecatedConfigIssues(raw) {
                         });
                     }
                 }
+                // (E, CFG-26) retired run_shell_command approval knobs in this command's registry.
+                collectRetiredShellToolIssues(cmd.builtInTools, `commands.${name}.builtInTools`, issues);
+                // (F, CFG-27) retired approvals keys / mode values in this command's approvals value.
+                collectRetiredApprovalsIssues(cmd.approvals, `commands.${name}.approvals`, issues);
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * EXT-71 §3.1 — the reserved MCP server name. `*` in an entry's `server` field means *every
+ * server*, so a server actually CALLED `*` would make `{ "server": "*" }` ambiguous — it could not
+ * be read as either "every server" or "that one server" without picking, and a rule whose scope
+ * depends on which reading won is worse than no rule. The name is therefore refused at load.
+ */
+const RESERVED_MCP_SERVER_NAME = '*';
+/**
+ * EXT-70 §4.7.5 — the MCP server name that cannot be written about. A server key is
+ * `z.string().min(1)` both under `approvals.mcp.servers` (§9) and on an `mcpTool` entry's `server`
+ * field (§3.1), so a server keyed with the empty string is one no approvals rule and no trust
+ * relationship can ever refer to by name. Its tools resolve to the unattributable-server sentinel:
+ * fail-closed, which is safe, but also silently un-configurable — the user would get a server whose
+ * every call is gated with no way to say anything about it and no error explaining why. Refused at
+ * load, for the same reason as {@link RESERVED_MCP_SERVER_NAME}: a name whose rules cannot be
+ * expressed is worse than a rejected config.
+ */
+const UNNAMEABLE_MCP_SERVER_NAME = '';
+/**
+ * EXT-71 §3.1/§9.1 — validate every entry in one `approvals` value's three rule lists (root or per
+ * command), pushing one issue per problem with a path that points at the exact entry and field.
+ *
+ * **Why the entries are checked HERE rather than left to the schema parse**, given that
+ * `approvalsSchema` already carries {@link approvalEntrySchema}: the `approvals` value is a union
+ * (the §9.1 scalar-or-object sugar), and zod reports a failing union as ONE issue at the union's
+ * own path — `approvals: Invalid input` — with every arm's real diagnosis nested out of reach of
+ * the formatter. That is exactly the wrong message for this grammar, where the whole requirement is
+ * that a rejection names the offending field, key or pattern. Parsing each entry on its own gets
+ * the precise issue back, and because this runs BEFORE the parse the precise message is the only
+ * one the user sees. The schema keeps the entries too, so it stays the authority and the emitted
+ * JSON Schema still describes them.
+ *
+ * A bare string is handled separately from the rest, because its message is the migration
+ * affordance: it renders the entry for the string that was actually found rather than a generic
+ * example, since what the user needs is the line they can paste back over the one they wrote.
+ */
+function collectApprovalEntryIssues(approvals, pathPrefix, issues) {
+    if (!approvals || typeof approvals !== 'object' || Array.isArray(approvals))
+        return;
+    const block = approvals;
+    for (const listKey of APPROVAL_LIST_KEYS) {
+        const list = block[listKey];
+        if (list === undefined)
+            continue;
+        // A list written as something other than an array would otherwise fall back to the union's
+        // bland "approvals: Invalid input" — the same message this whole function exists to replace.
+        // `escalate` is exempt: its non-array shape is the retired severity threshold and gets its own
+        // migration message from `collectRetiredApprovalsIssues`.
+        if (!Array.isArray(list)) {
+            if (listKey !== 'escalate') {
+                issues.push({
+                    path: `${pathPrefix}.${listKey}`,
+                    message: `must be a LIST of rule entries, not ${typeof list === 'object' ? 'an object' : `a ${typeof list}`}. ` +
+                        `Write it as an array, e.g. [ ${renderApprovalEntryForString('npm test')} ]. ` +
+                        MIGRATION_HINT,
+                });
+            }
+            continue;
+        }
+        list.forEach((entry, index) => {
+            const entryPath = `${pathPrefix}.${listKey}[${index}]`;
+            if (typeof entry === 'string') {
+                issues.push({
+                    path: entryPath,
+                    message: 'bare strings are no longer accepted in an approvals rule list. Write the entry ' +
+                        `explicitly: ${renderApprovalEntryForString(entry)} — type, matcher and pattern are ` +
+                        `always required, and "matcher" may be exact, glob or regexp. ${MIGRATION_HINT}`,
+                });
+                return;
+            }
+            const parsed = approvalEntrySchema.safeParse(entry);
+            if (parsed.success)
+                return;
+            for (const issue of parsed.error.issues) {
+                issues.push({
+                    path: issue.path.length > 0 ? `${entryPath}.${issue.path.join('.')}` : entryPath,
+                    message: issue.message,
+                });
+            }
+        });
+    }
+}
+/**
+ * EXT-70 §4.7/§9 — validate one `approvals.mcp` block, with a path that names the offending field.
+ *
+ * It runs PRE-PARSE for the same reason the rule entries do: `approvalsSchema` is a `z.union`, so a
+ * bad `mcp` block otherwise collapses into the union's bland "approvals: Invalid input" — the
+ * message this whole family of checks exists to replace. Here the user gets the server key, the
+ * field and (for a hint name) the value they mistyped.
+ */
+function collectMcpApprovalsIssues(approvals, pathPrefix, issues) {
+    if (!approvals || typeof approvals !== 'object' || Array.isArray(approvals))
+        return;
+    const mcp = approvals.mcp;
+    if (mcp === undefined)
+        return;
+    const parsed = mcpApprovalsSchema.safeParse(mcp);
+    if (parsed.success)
+        return;
+    for (const issue of parsed.error.issues) {
+        issues.push({
+            path: issue.path.length > 0 ? `${pathPrefix}.mcp.${issue.path.join('.')}` : `${pathPrefix}.mcp`,
+            message: issue.message,
+        });
+    }
+}
+/**
+ * EXT-71 §3.1 — every hard error the rule grammar defines, found on the RAW input: each entry in
+ * `allow`/`deny`/`escalate` validated with a path that names the offending field
+ * ({@link collectApprovalEntryIssues}), the `approvals.mcp` block ({@link collectMcpApprovalsIssues}),
+ * and the two `mcpServers` keys no rule can refer to — `*` ({@link RESERVED_MCP_SERVER_NAME}, which
+ * an entry already reads as "every server") and the empty name
+ * ({@link UNNAMEABLE_MCP_SERVER_NAME}, which no entry's `server` field can hold). Both need to see
+ * `mcpServers`, a sibling of `approvals` rather than a field of it.
+ *
+ * All of them are HARD errors, reported the same way {@link findDeprecatedConfigIssues} reports
+ * its own, and — like it — this runs BEFORE the schema parse so the precise message is the only
+ * one the user sees.
+ *
+ * PURE: it only reads the object. Kept separate from {@link findDeprecatedConfigIssues} because
+ * these are not removed pre-2.0 shapes; they are rules of the current grammar.
+ */
+export function findApprovalsGrammarIssues(raw) {
+    const issues = [];
+    const mcpServers = raw.mcpServers;
+    if (mcpServers && typeof mcpServers === 'object' && !Array.isArray(mcpServers)) {
+        if (Object.prototype.hasOwnProperty.call(mcpServers, RESERVED_MCP_SERVER_NAME)) {
+            issues.push({
+                path: `mcpServers.${RESERVED_MCP_SERVER_NAME}`,
+                message: `"${RESERVED_MCP_SERVER_NAME}" is a reserved MCP server name: an approvals rule entry ` +
+                    `uses it to mean EVERY server, so a server of that name would make ` +
+                    `{ "type": "mcpTool", "server": "${RESERVED_MCP_SERVER_NAME}", ... } ambiguous. ` +
+                    'Rename the server to anything else. ' +
+                    MIGRATION_HINT,
+            });
+        }
+        if (Object.prototype.hasOwnProperty.call(mcpServers, UNNAMEABLE_MCP_SERVER_NAME)) {
+            issues.push({
+                path: 'mcpServers.""',
+                message: 'an MCP server may not be keyed with an empty name: both an approvals rule entry ' +
+                    '({ "type": "mcpTool", "server": ... }) and a trust relationship under ' +
+                    '"approvals.mcp.servers" require a server name of at least one character, so nothing ' +
+                    "could ever be written about this server's tools — every call it makes would be gated " +
+                    'with no way to say otherwise. Give the server a name. ' +
+                    MIGRATION_HINT,
+            });
+        }
+    }
+    const collect = (approvals, prefix) => {
+        collectApprovalEntryIssues(approvals, prefix, issues);
+        collectMcpApprovalsIssues(approvals, prefix, issues);
+    };
+    collect(raw.approvals, 'approvals');
+    const commands = raw.commands;
+    if (commands && typeof commands === 'object' && !Array.isArray(commands)) {
+        for (const [name, cmd] of Object.entries(commands)) {
+            if (cmd && typeof cmd === 'object' && !Array.isArray(cmd)) {
+                collect(cmd.approvals, `commands.${name}.approvals`);
             }
         }
     }
     return issues;
 }
+/**
+ * CFG-26 — collect every `approvals.rater` in a raw config (root + each `commands.<name>`).
+ * CFG-27 flattened the key: it is a BARE identity-profile name, not `rater.profile`.
+ *
+ * PURE — it only reads the object; the caller decides whether each name RESOLVES. That split is
+ * deliberate: profile resolution needs the filesystem, and `schema.ts` must stay pure so
+ * `z.toJSONSchema` and every spec that validates a config object stay cwd-independent. The loader
+ * pairs this with `resolveIdentityProfileConfigPath` to enforce the GS2-62 rule that an
+ * unresolvable profile is a hard error, never a silent fallback to the main model.
+ */
+export function findApprovalsRaterProfiles(raw) {
+    const refs = [];
+    const collect = (approvals, prefix) => {
+        // The scalar sugar form (`"approvals": "auto-safe"`) carries no rater.
+        if (!approvals || typeof approvals !== 'object' || Array.isArray(approvals))
+            return;
+        const rater = approvals.rater;
+        if (typeof rater === 'string' && rater.trim().length > 0) {
+            refs.push({ path: `${prefix}.rater`, profile: rater.trim() });
+        }
+    };
+    collect(raw.approvals, 'approvals');
+    const commands = raw.commands;
+    if (commands && typeof commands === 'object' && !Array.isArray(commands)) {
+        for (const [name, cmd] of Object.entries(commands)) {
+            if (cmd && typeof cmd === 'object' && !Array.isArray(cmd)) {
+                collect(cmd.approvals, `commands.${name}.approvals`);
+            }
+        }
+    }
+    return refs;
+}
+/**
+ * CFG-26 — the ONE message for an `approvals.rater.profile` that does not resolve. Shared by the
+ * loader (which hard-exits a real run) and {@link validateRawGthConfig} (which backs
+ * `gth config validate`), so the validator can never green-light a config the runtime refuses.
+ */
+export function unresolvedRaterProfileMessage(ref) {
+    return (`identity profile "${ref.profile}" not found ` +
+        `(checked ${GSLOTH_DIR}/${GSLOTH_SETTINGS_DIR}/${ref.profile}/). ` +
+        'Create it with `gth config profile create`, or omit approvals.rater to rate ' +
+        'with the main model.');
+}
 /**
  * Render {@link DeprecatedConfigIssue}s as the same `  - <path>: <message>` block used for
  * Zod validation errors, so a deprecated-shape rejection reads identically to a type-mismatch
@@ -575,7 +1378,7 @@ export function generateConfigJsonSchema() {
  * Read-only: `findDeprecatedConfigIssues`, `findUnknownTopLevelKeys` and `safeParse` never
  * mutate `raw`, so no defensive copy is needed.
  */
-export function validateRawGthConfig(raw) {
+export function validateRawGthConfig(raw, options) {
     const warnings = [];
     // Only an object config can carry deprecated/unknown keys. A null/array/primitive config is
     // handed straight to safeParse (below), which returns a clean "expected object" failure — the
@@ -591,6 +1394,16 @@ export function validateRawGthConfig(raw) {
                 errorMessage: formatDeprecatedConfigIssues(deprecatedIssues),
             };
         }
+        // EXT-71 — the rule-grammar errors that need to be seen before the schema parse, so the
+        // message that explains the fix is the only one the user reads.
+        const grammarIssues = findApprovalsGrammarIssues(raw);
+        if (grammarIssues.length > 0) {
+            return {
+                ok: false,
+                warnings: [],
+                errorMessage: formatDeprecatedConfigIssues(grammarIssues),
+            };
+        }
         const unknownKeys = findUnknownTopLevelKeys(raw);
         if (unknownKeys.length > 0) {
             warnings.push(`Unknown top-level config ${unknownKeys.length === 1 ? 'key' : 'keys'}: ` +
@@ -601,6 +1414,22 @@ export function validateRawGthConfig(raw) {
     if (!result.success) {
         return { ok: false, warnings, errorMessage: formatConfigValidationError(result.error) };
     }
+    // CFG-26 — `approvals.rater.profile` strict resolution, when the caller supplies a resolver.
+    // The predicate is INJECTED rather than imported so this module stays pure (it feeds
+    // `z.toJSONSchema`, and every spec that validates a config object must stay cwd-independent),
+    // while `gth config validate` still agrees with the loader instead of green-lighting a config
+    // the next real run hard-exits on. Without a resolver the check is skipped, preserving the
+    // in-memory callers (e.g. the profile scaffolder).
+    if (options?.resolveProfile && isRecordConfig(raw)) {
+        const unresolved = findApprovalsRaterProfiles(raw).filter((ref) => !options.resolveProfile(ref.profile));
+        if (unresolved.length > 0) {
+            return {
+                ok: false,
+                warnings,
+                errorMessage: formatIssueLines(unresolved.map((ref) => ({ path: ref.path, message: unresolvedRaterProfileMessage(ref) }))),
+            };
+        }
+    }
     return { ok: true, warnings };
 }
 //# sourceMappingURL=schema.js.map