Surface permissions.modes catalog prose for permissions.defaultMode

When the row's effective value matches one of the six cataloged modes,
the drawer header now shows that mode's specific prose instead of the
settings catalog's first-line placeholder. Joins through a new
findPermissionMode helper backed by a name-indexed Map built at
hydration time; resolveDescription gains a single string-value branch.
Falls back to the existing settings catalog description when the value
is undocumented (e.g. the experimental `delegate` mode) or a non-string
slipped through a malformed settings.json.

Second drawer-side consumer of a non-settings catalog after env-vars.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: samkeen

spec/roadmap.md

@@ -13,19 +13,19 @@ path-notes click-through + Phase 6 fully shipped + three-OS CI +
 managed-mcp.json topbar pill + catalog-drift cron + sync-sub-agents +
 in-app error log + per-OS capability split + sync-mcp + sync-permissions
 + drawer cross-references env-vars catalog + sync-keybindings +
-sync-cli-reference + hooks catalog pass #2 + drawer cross-reference
-follow-ups slated).
+sync-cli-reference + hooks catalog pass #2 + drawer cross-references
+permissions.modes).
 
 ## Next-up candidates
 
 A digest of what's open across the four tracks below — pick from
 here, then jump to the relevant section for shape and rationale.
 
-- **Drawer cross-references for `permissions.modes` and
-  `hooks.events`** (inspector polish) — concrete coding follow-ups to
-  the env-vars drawer wire-up (2026-05-07). Both catalogs are loaded
-  through `read_catalog` already; the joinpoints are obvious. See
-  Inspector polish § "Open work".
+- **Drawer cross-reference for `hooks.events`** (inspector polish) —
+  concrete follow-up to the env-vars + permissions.modes drawer
+  wire-ups. Catalog already loads through `read_catalog`; main
+  open question is whether the array-typed `hooks.<EventName>` rows
+  fit the existing drawer shape. See Inspector polish § "Open work".
 - **Rail navigability decision** (inspector polish) — spec question,
   not coding work; needs a fork-vs-fork call before any UI lands.
 - **ENV-layer / `env.*`-row seam** (inspector polish) — UX question,
@@ -310,18 +310,6 @@ Phase numbering matches the spec.
 
 Open work (what to pick up next within this track):
 
-- **Drawer cross-references — `permissions.modes` for
-  `permissions.defaultMode`.** The permissions catalog's 6-record
-  `modes` array (default / acceptEdits / plan / auto / dontAsk /
-  bypassPermissions) carries prose richer than the short blurbs in the
-  settings JSON Schema. When a row's keyPath is
-  `permissions.defaultMode`, look up the row's current (or default)
-  value in `permissions.modes` and surface that mode's description in
-  the drawer header — same pattern as the env-vars wire-up (pure
-  helper in `catalog.ts`, `resolveDescription` extension in
-  `KeyDrawer.tsx`, case-sensitive lookup since mode names are
-  camelCase ASCII). Validates a third drawer-side consumer of a
-  non-settings catalog after env-vars and (if shipped first) hooks.
 - **Drawer cross-references — `hooks.events` for `hooks.<EventName>`.**
   Hooks pass #2 (2026-05-08) lifted handler types and per-event
   schemas into `catalog/hooks.json`. The natural drawer consumers are
@@ -359,6 +347,26 @@ Open work (what to pick up next within this track):
 
 Shipped:
 
+- **Drawer cross-references `permissions.modes` for
+  `permissions.defaultMode`.** ✅ shipped 2026-05-08. When a row's
+  keyPath is `permissions.defaultMode` and the row's effective value
+  (set or `catalog.default` for unset) matches one of the 6 cataloged
+  modes, the drawer header surfaces that mode's specific prose
+  (`acceptEdits` → "Automatically accepts file edits and common
+  filesystem commands…") instead of the settings catalog's first-line
+  placeholder ("Default permission mode."). Joins through
+  `findPermissionMode(name)` in `src/lib/catalog.ts` (name-indexed Map
+  built at hydration time) and an extension to `resolveDescription` in
+  `KeyDrawer.tsx`. Case-sensitive lookup — mode names are camelCase
+  ASCII and case-folding would feed false matches for user typos.
+  Defensive: only attempts the lookup when `typeof row.value ===
+  "string"`, so a malformed settings.json with a non-string value
+  falls back cleanly to the settings catalog prose. Undocumented
+  enum values (`delegate` — experimental agent-team only, in the JSON
+  Schema enum but not in the upstream permissions docs) also fall
+  back to the settings catalog. Second drawer-side consumer of a
+  non-settings catalog after env-vars; further validates the seam for
+  `hooks.events` next.
 - **Drawer cross-references env-vars catalog.** ✅ shipped 2026-05-07.
   When a row's keyPath is `env.<VAR>` and `<VAR>` is documented in the
   env-vars catalog (220 entries upstream), the drawer header surfaces

src/components/inspector/KeyDrawer.test.ts

@@ -112,4 +112,79 @@ describe("resolveDescription", () => {
     });
     expect(resolveDescription(row)).toBe("First line.");
   });
+
+  test("uses the permissions catalog mode description for permissions.defaultMode rows whose value is documented", () => {
+    // The permissions catalog has prose richer than the settings
+    // schema's mash-up of every mode in one description. When the row's
+    // effective value is a cataloged mode, surface that mode's prose.
+    const row = rowWithKey("permissions.defaultMode", {
+      value: "acceptEdits",
+      catalog: {
+        key: "permissions.defaultMode",
+        description: "Default permission mode.\nGeneric multi-line prose.",
+      },
+    });
+    const desc = resolveDescription(row);
+    expect(desc).not.toBe("Default permission mode.");
+    expect(desc).toMatch(/edits/i);
+  });
+
+  test("falls back to the settings catalog description for permissions.defaultMode when the value is undocumented", () => {
+    // `delegate` is in the settings JSON Schema enum but isn't in the
+    // upstream permissions docs (experimental agent-team mode). The
+    // drawer must fall back to the settings catalog's first line.
+    const row = rowWithKey("permissions.defaultMode", {
+      value: "delegate",
+      catalog: {
+        key: "permissions.defaultMode",
+        description: "Default permission mode.\nGeneric multi-line prose.",
+      },
+    });
+    expect(resolveDescription(row)).toBe("Default permission mode.");
+  });
+
+  test("uses catalog default when permissions.defaultMode row is unset", () => {
+    // Unset rows carry their value from `catalog.default` (see rows.ts).
+    // The cross-reference must work for the unset case too — that's the
+    // common state for new users who haven't customized permissions.
+    const row = rowWithKey("permissions.defaultMode", {
+      value: "default",
+      state: "unset",
+      catalog: {
+        key: "permissions.defaultMode",
+        description: "Default permission mode.\nGeneric prose.",
+        default: "default",
+      },
+    });
+    const desc = resolveDescription(row);
+    expect(desc).not.toBe("Default permission mode.");
+    expect(desc?.length ?? 0).toBeGreaterThan(0);
+  });
+
+  test("ignores non-string values on permissions.defaultMode without throwing", () => {
+    // Defensive: a malformed settings.json could put a non-string here.
+    // The lookup must not crash; fall back to the settings catalog prose.
+    const row = rowWithKey("permissions.defaultMode", {
+      value: 42 as unknown,
+      catalog: {
+        key: "permissions.defaultMode",
+        description: "Default permission mode.",
+      },
+    });
+    expect(resolveDescription(row)).toBe("Default permission mode.");
+  });
+
+  test("permissions catalog override does not bleed into other permissions.* rows", () => {
+    // Only `permissions.defaultMode` joins to `permissions.modes`. Other
+    // permissions.* rows (allow/deny/ask/...) keep the existing
+    // catalog-description behavior.
+    const row = rowWithKey("permissions.allow", {
+      value: ["Bash"],
+      catalog: {
+        key: "permissions.allow",
+        description: "Tools permitted without prompting",
+      },
+    });
+    expect(resolveDescription(row)).toBe("Tools permitted without prompting");
+  });
 });

src/components/inspector/KeyDrawer.tsx

@@ -1,6 +1,11 @@
 import { useMemo } from "react";
 import { cn } from "@/lib/utils";
-import { findEnvVar, findRelatedKnobs, type CatalogEntry } from "@/lib/catalog";
+import {
+  findEnvVar,
+  findPermissionMode,
+  findRelatedKnobs,
+  type CatalogEntry,
+} from "@/lib/catalog";
 import { formatValue } from "@/lib/format";
 import { buildRows, type Row } from "@/lib/rows";
 import { buildWaterfall } from "@/lib/waterfall";
@@ -348,19 +353,30 @@ export function envVarNameFromKeyPath(keyPath: string): string | null {
 }
 
 /**
- * Resolve the description prose shown in the drawer header. For
- * `env.<VAR>` rows whose var is documented upstream, prefer the
- * env-vars catalog's purpose over the generic parent-`env` description
- * the settings catalog walk-up returns. Falls back to the settings
- * catalog description otherwise; truncates to the first line so the
- * header band stays a single paragraph.
+ * Resolve the description prose shown in the drawer header.
+ *
+ * - For `env.<VAR>` rows whose var is documented upstream, prefer the
+ *   env-vars catalog's purpose over the generic parent-`env`
+ *   description the settings catalog walk-up returns.
+ * - For `permissions.defaultMode` rows whose effective value matches a
+ *   cataloged mode, prefer the permissions catalog's mode-specific
+ *   prose over the settings catalog's first line ("Default permission
+ *   mode."), which is just a placeholder before the multi-line mash-up
+ *   of every mode.
+ *
+ * Falls back to the settings catalog description otherwise; truncates
+ * to the first line so the header band stays a single paragraph.
  */
 export function resolveDescription(row: Row): string | null {
   const envVar = envVarNameFromKeyPath(row.keyPath);
   if (envVar) {
     const entry = findEnvVar(envVar);
     if (entry) return entry.purpose.split("\n")[0];
   }
+  if (row.keyPath === "permissions.defaultMode" && typeof row.value === "string") {
+    const mode = findPermissionMode(row.value);
+    if (mode) return mode.description.split("\n")[0];
+  }
   return row.catalog?.description?.split("\n")[0] ?? null;
 }
 

src/lib/catalog.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { findRelatedKnobs, findCatalogEntry, findEnvVar } from "./catalog";
+import {
+  findRelatedKnobs,
+  findCatalogEntry,
+  findEnvVar,
+  findPermissionMode,
+} from "./catalog";
 
 describe("findRelatedKnobs", () => {
   it("returns sibling entries under the same parent path", () => {
@@ -86,3 +91,32 @@ describe("findEnvVar", () => {
     expect(findEnvVar("anthropic_api_key")).toBeNull();
   });
 });
+
+describe("findPermissionMode", () => {
+  it("looks up a documented mode by exact name", () => {
+    // Stable anchors — `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`,
+    // and `bypassPermissions` are the six modes that have lived in the
+    // upstream docs since the catalog landed. Assert structural shape
+    // and that the description is non-empty; the prose drifts.
+    const e = findPermissionMode("acceptEdits");
+    expect(e).not.toBeNull();
+    expect(e!.name).toBe("acceptEdits");
+    expect(e!.description.length).toBeGreaterThan(0);
+  });
+
+  it("returns null for an undocumented mode", () => {
+    // Settings JSON Schema lists `delegate` as a valid enum value but
+    // the upstream permissions docs don't describe it (it's
+    // experimental, agent-team only). The drawer must fall back to the
+    // settings catalog's first-line description when the mode isn't
+    // cataloged, not silently render the wrong prose.
+    expect(findPermissionMode("delegate")).toBeNull();
+  });
+
+  it("is case-sensitive — mode names are conventionally camelCase", () => {
+    // Real mode names are camelCase ASCII; case-folding the lookup would
+    // create false matches for user typos.
+    expect(findPermissionMode("AcceptEdits")).toBeNull();
+    expect(findPermissionMode("acceptedits")).toBeNull();
+  });
+});

src/lib/catalog.ts

@@ -44,15 +44,28 @@ export interface EnvVarsCatalogFile {
   envVars: EnvVarEntry[];
 }
 
+export interface PermissionMode {
+  name: string;
+  /** Upstream prose describing how the mode behaves. */
+  description: string;
+}
+
+export interface PermissionsCatalogFile {
+  source: string;
+  fetchedAt: string;
+  count: number;
+  modes: PermissionMode[];
+}
+
 export interface CatalogsWire {
   settings: SettingsCatalogFile;
   env_vars: EnvVarsCatalogFile;
+  permissions: PermissionsCatalogFile;
   // Other catalogs are exposed for future Phase 5+ consumers; their shapes
   // aren't modeled yet because nothing in the UI reads them.
   hooks: unknown;
   sub_agents: unknown;
   mcp: unknown;
-  permissions: unknown;
   keybindings: unknown;
   cli_reference: unknown;
 }
@@ -69,6 +82,7 @@ interface InitializedCatalog {
   leaf: CatalogEntry[];
   byKey: Map<string, CatalogEntry>;
   envVarsByName: Map<string, EnvVarEntry>;
+  permissionModesByName: Map<string, PermissionMode>;
   meta: CatalogMeta;
 }
 
@@ -95,6 +109,9 @@ function buildState(data: CatalogsWire): InitializedCatalog {
     leaf,
     byKey: new Map(leaf.map((e) => [e.key, e])),
     envVarsByName: new Map(data.env_vars.envVars.map((e) => [e.name, e])),
+    permissionModesByName: new Map(
+      data.permissions.modes.map((m) => [m.name, m]),
+    ),
     meta: {
       source: data.settings.source,
       fetchedAt: data.settings.fetchedAt,
@@ -173,6 +190,18 @@ export function findEnvVar(name: string): EnvVarEntry | null {
   return requireState().envVarsByName.get(name) ?? null;
 }
 
+/**
+ * Lookup by permission-mode name (e.g. `acceptEdits`). Returns null
+ * when the catalog doesn't document the mode — the settings JSON
+ * Schema has additional enum values like `delegate` (experimental
+ * agent-team only) that aren't in the upstream permissions docs.
+ * Case-sensitive: mode names are camelCase ASCII; case-folding would
+ * create false matches for user typos.
+ */
+export function findPermissionMode(name: string): PermissionMode | null {
+  return requireState().permissionModesByName.get(name) ?? null;
+}
+
 /** Lookup by exact dot-path. Walks up to find the closest parent on miss. */
 export function findCatalogEntry(keyPath: string): CatalogEntry | null {
   const { byKey, full } = requireState();