Move permissions.defaultMode mode prose to a value-conditional annotation

Putting the mode-specific prose in the drawer header was misleading: a
header that silently changes when the value changes makes readers
think they're seeing the description of the knob, not the description
of the current value. Move it under the EFFECTIVE block, prefixed `→`,
so the position signals "this annotates the value."

resolveDescription returns to its pre-permissions-modes behavior; a
new resolveValueAnnotation helper carries the value-conditional
lookup. Annotation preserves the full multi-line prose (no first-line
truncation) since it now lives in its own block.

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

Author: samkeen

spec/roadmap.md

@@ -351,22 +351,30 @@ Shipped:
   `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.
+  modes, the drawer surfaces that mode's specific prose as a
+  *value-conditional annotation* below the EFFECTIVE block — keeping
+  the header description ("Default permission mode.") tied to the
+  knob itself, not its current value. The structural separation
+  matters: a header that silently changes prose when the value
+  changes would be misleading; an annotation labelled by position
+  (under EFFECTIVE, prefixed `→`) makes it obvious the prose
+  describes the *value*. Joins through `findPermissionMode(name)` in
+  `src/lib/catalog.ts` (name-indexed Map built at hydration time) and
+  a new `resolveValueAnnotation(row)` helper in `KeyDrawer.tsx`,
+  parallel to `resolveDescription`. 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 renders no annotation rather than misleading
+  prose. Undocumented enum values (`delegate` — experimental
+  agent-team only, in the JSON Schema enum but not in the upstream
+  permissions docs) also render no annotation. The annotation
+  preserves the full multi-line catalog prose (no first-line
+  truncation) since it lives in its own block — qualifiers like
+  "Currently a research preview" stay visible. Second drawer-side
+  consumer of a non-settings catalog after env-vars; further
+  validates the seam for `hooks.events` next, where the same
+  value-vs-knob distinction will apply.
 - **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

@@ -1,6 +1,10 @@
 import { describe, expect, test } from "vitest";
 
-import { envVarNameFromKeyPath, resolveDescription } from "./KeyDrawer";
+import {
+  envVarNameFromKeyPath,
+  resolveDescription,
+  resolveValueAnnotation,
+} from "./KeyDrawer";
 import type { Row } from "@/lib/rows";
 
 function rowWithKey(keyPath: string, partial: Partial<Row> = {}): Row {
@@ -113,78 +117,84 @@ 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.
+  test("keeps the generic settings catalog description for permissions.defaultMode regardless of value", () => {
+    // The mode-specific prose moved out of the header — it's value-
+    // conditional and belongs under the EFFECTIVE block. The header
+    // describes the knob itself, not its current value.
     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);
+    expect(resolveDescription(row)).toBe("Default permission mode.");
   });
+});
 
-  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.");
+describe("resolveValueAnnotation", () => {
+  test("returns the cataloged mode description for permissions.defaultMode when the value is documented", () => {
+    // The annotation surfaces what the current *value* does, not what
+    // the knob does. Anchor on `acceptEdits` — its prose is stable.
+    const row = rowWithKey("permissions.defaultMode", { value: "acceptEdits" });
+    const anno = resolveValueAnnotation(row);
+    expect(anno).not.toBeNull();
+    expect(anno).toMatch(/edits/i);
   });
 
-  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.
+  test("returns null for permissions.defaultMode when the value is undocumented", () => {
+    // `delegate` is in the JSON Schema enum but not in the upstream
+    // permissions docs. Don't render an annotation — the alternative is
+    // misleading prose.
+    const row = rowWithKey("permissions.defaultMode", { value: "delegate" });
+    expect(resolveValueAnnotation(row)).toBeNull();
+  });
+
+  test("fires for unset permissions.defaultMode rows whose value is the catalog default", () => {
+    // Unset rows carry value from `catalog.default` (see rows.ts). The
+    // unset case is the common state for new users; the annotation
+    // should still help them understand what the default actually does.
     const row = rowWithKey("permissions.defaultMode", {
       value: "default",
       state: "unset",
-      catalog: {
-        key: "permissions.defaultMode",
-        description: "Default permission mode.\nGeneric prose.",
-        default: "default",
-      },
+      catalog: { key: "permissions.defaultMode", default: "default" },
     });
-    const desc = resolveDescription(row);
-    expect(desc).not.toBe("Default permission mode.");
-    expect(desc?.length ?? 0).toBeGreaterThan(0);
+    const anno = resolveValueAnnotation(row);
+    expect(anno).not.toBeNull();
+    expect(anno!.length).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("returns null for non-string values without throwing", () => {
+    // Defensive: malformed settings.json could put a non-string here.
+    const row = rowWithKey("permissions.defaultMode", { value: 42 as unknown });
+    expect(resolveValueAnnotation(row)).toBeNull();
   });
 
-  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");
+  test("returns null for any other keyPath", () => {
+    // Only permissions.defaultMode joins to permissions.modes today.
+    // Other permissions.* rows (allow / deny / ask / ...) and unrelated
+    // rows must not get an annotation.
+    expect(
+      resolveValueAnnotation(rowWithKey("permissions.allow", { value: ["Bash"] })),
+    ).toBeNull();
+    expect(
+      resolveValueAnnotation(rowWithKey("model", { value: "claude-sonnet-4-6" })),
+    ).toBeNull();
+    expect(
+      resolveValueAnnotation(rowWithKey("env.ANTHROPIC_API_KEY", { value: "sk-x" })),
+    ).toBeNull();
+  });
+
+  test("preserves the full multi-line description (no first-line truncation)", () => {
+    // The annotation lives in a block of its own under EFFECTIVE, not
+    // a single-line header band. Keep the full prose so the user sees
+    // qualifiers like 'Currently a research preview' that follow on
+    // later lines if upstream ever adds them.
+    const row = rowWithKey("permissions.defaultMode", { value: "auto" });
+    const anno = resolveValueAnnotation(row);
+    // Real catalog prose for `auto` includes a second clause that the
+    // header would have truncated; assert structurally — the prose drifts.
+    expect(anno).not.toBeNull();
+    expect(anno!.length).toBeGreaterThan(40);
   });
 });

src/components/inspector/KeyDrawer.tsx

@@ -206,6 +206,7 @@ function EffectiveBlock({
   row: Row;
   formatted: ReturnType<typeof formatValue>;
 }) {
+  const annotation = resolveValueAnnotation(row);
   return (
     <div className="border-b border-line px-5 py-4">
       <span className="corner-tag mb-2 block">Effective</span>
@@ -238,6 +239,15 @@ function EffectiveBlock({
           )}
         </span>
       </div>
+      {annotation ? (
+        <div
+          className="mt-2 flex gap-2 pl-3 text-[11.5px] leading-snug text-fg-3"
+          data-testid="value-annotation"
+        >
+          <span aria-hidden className="text-fg-4">→</span>
+          <span>{annotation}</span>
+        </div>
+      ) : null}
     </div>
   );
 }
@@ -353,31 +363,39 @@ 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.
- * - 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.
+ * 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.
  */
 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];
   }
+  return row.catalog?.description?.split("\n")[0] ?? null;
+}
+
+/**
+ * Resolve a value-conditional annotation rendered under the EFFECTIVE
+ * block — explains what the current value *does* without conflating it
+ * with the description of the knob itself.
+ *
+ * Currently fires only for `permissions.defaultMode` rows whose
+ * effective value matches a cataloged mode (the 6 documented modes,
+ * not the experimental `delegate` enum value). Returns null for
+ * undocumented values, non-string values, and any other keyPath, so
+ * the drawer renders nothing rather than mislead.
+ */
+export function resolveValueAnnotation(row: Row): string | null {
   if (row.keyPath === "permissions.defaultMode" && typeof row.value === "string") {
     const mode = findPermissionMode(row.value);
-    if (mode) return mode.description.split("\n")[0];
+    if (mode) return mode.description;
   }
-  return row.catalog?.description?.split("\n")[0] ?? null;
+  return null;
 }
 
 function describeShape(row: Row): string {