@dungle-scrubs/harness-cli-normalizer 0.4.6 → 0.5.0

package/src/interpretation/tool-vocabulary.ts

@@ -0,0 +1,183 @@
+import type { DescriptorSet } from "../knowledge/overrides.js";
+import { ArgvRefusalError } from "./refusal.js";
+
+export const NATIVE_PREFIX = "native:" as const;
+
+export type VocabularyEntry =
+  | { kind: "builtin"; native: string }
+  | { kind: "category"; key: string };
+
+export const READ_PRESET = ["read", "grep", "glob", "list", "web-fetch", "web-search"] as const;
+
+export type ParsedSelector = { kind: "canonical"; name: string } | { kind: "native"; name: string };
+
+export const parseToolSelector = (raw: string): ParsedSelector =>
+  raw.startsWith(NATIVE_PREFIX)
+    ? { kind: "native", name: raw.slice(NATIVE_PREFIX.length) }
+    : { kind: "canonical", name: raw };
+
+export type ToolMap = Readonly<Record<string, Readonly<Record<string, string>>>>;
+
+export type ToolMapTier = "user-config" | "project-config";
+
+export type MergedToolMap = Readonly<
+  Record<string, Readonly<Record<string, { native: string; tier: ToolMapTier }>>>
+>;
+
+/** Pure merge per harness per canonical: project > user. */
+export const mergeToolMaps = (tiers: {
+  readonly user?: ToolMap;
+  readonly project?: ToolMap;
+}): MergedToolMap => {
+  const merged: Record<string, Record<string, { native: string; tier: ToolMapTier }>> = {};
+  const harnesses = new Set<string>([
+    ...Object.keys(tiers.user ?? {}),
+    ...Object.keys(tiers.project ?? {}),
+  ]);
+  for (const h of harnesses) {
+    const userEntries = tiers.user?.[h] ?? {};
+    const projectEntries = tiers.project?.[h] ?? {};
+    const canonicals = new Set<string>([
+      ...Object.keys(userEntries),
+      ...Object.keys(projectEntries),
+    ]);
+    const perHarness: Record<string, { native: string; tier: ToolMapTier }> = {};
+    for (const c of canonicals) {
+      if (projectEntries[c] !== undefined) {
+        perHarness[c] = { native: projectEntries[c] as string, tier: "project-config" };
+      } else if (userEntries[c] !== undefined) {
+        perHarness[c] = { native: userEntries[c] as string, tier: "user-config" };
+      }
+    }
+    if (Object.keys(perHarness).length > 0) {
+      merged[h] = perHarness;
+    }
+  }
+  return merged;
+};
+
+export type CanonicalTable = Readonly<
+  Record<string, Readonly<Partial<Record<string, VocabularyEntry>>>>
+>;
+
+const tableCache = new WeakMap<DescriptorSet, CanonicalTable>();
+
+export const canonicalTable = (set: DescriptorSet): CanonicalTable => {
+  const cached = tableCache.get(set);
+  if (cached) return cached;
+  const allCanonical = new Set<string>();
+  for (const h of Object.values(set)) {
+    if (!h) continue;
+    for (const b of h.tools.builtins) {
+      if (b.canonical !== null) allCanonical.add(b.canonical);
+    }
+    for (const c of h.tools.categories) {
+      for (const n of c.canonical) allCanonical.add(n);
+    }
+  }
+  const table: Record<string, Record<string, VocabularyEntry>> = {};
+  for (const canonical of allCanonical) {
+    const perHarness: Record<string, VocabularyEntry> = {};
+    for (const h of Object.values(set)) {
+      if (!h) continue;
+      const builtin = h.tools.builtins.find((b) => b.canonical === canonical);
+      if (builtin) {
+        perHarness[h.name] = { kind: "builtin", native: builtin.name };
+        continue;
+      }
+      const cat = h.tools.categories.find((c) =>
+        (c.canonical as readonly string[]).includes(canonical),
+      );
+      if (cat) {
+        perHarness[h.name] = { kind: "category", key: cat.key };
+      }
+    }
+    table[canonical] = perHarness;
+  }
+  const frozen = table as CanonicalTable;
+  tableCache.set(set, frozen);
+  return frozen;
+};
+
+// Backwards compat alias
+export const canonicalToolTable = canonicalTable;
+
+export const canonicalNames = (set: DescriptorSet): readonly string[] => {
+  const table = canonicalTable(set);
+  return Object.keys(table).sort();
+};
+
+export const allCanonicalNames = (
+  set: DescriptorSet,
+  toolMap?: ToolMap | MergedToolMap,
+): readonly string[] => {
+  const base = canonicalNames(set);
+  const extra = toolMap
+    ? Object.values(toolMap).flatMap((m) => Object.keys(m as Record<string, unknown>))
+    : [];
+  return [...new Set([...base, ...extra])].sort();
+};
+
+export const hasCounterpart = (
+  table: CanonicalTable,
+  canonical: string,
+  harnessName: string,
+  toolMap?: MergedToolMap | ToolMap,
+): boolean => {
+  if (toolMap) {
+    const hm = (toolMap as MergedToolMap)[harnessName];
+    if (hm && (hm as Record<string, unknown>)[canonical] !== undefined) {
+      const v = (hm as Record<string, unknown>)[canonical] as unknown;
+      if (typeof v === "object" && v !== null && "native" in (v as Record<string, unknown>))
+        return true;
+      if (typeof v === "string") return true;
+    }
+  }
+  const entry = table[canonical];
+  if (!entry) return false;
+  return entry[harnessName] !== undefined;
+};
+
+export const nativeFor = (
+  table: CanonicalTable,
+  canonical: string,
+  harnessName: string,
+  toolMap?: MergedToolMap | ToolMap,
+): string | null => {
+  if (toolMap) {
+    const hm = (toolMap as Record<string, Record<string, unknown>>)[harnessName];
+    const val = hm?.[canonical];
+    if (val !== undefined) {
+      if (typeof val === "object" && val !== null && "native" in (val as Record<string, unknown>)) {
+        return (val as { native: string }).native;
+      }
+      if (typeof val === "string") return val as string;
+    }
+  }
+  const entry = table[canonical];
+  const v = entry?.[harnessName];
+  if (v?.kind === "builtin") return v.native;
+  return null;
+};
+
+export const validateCanonicalList = (
+  names: readonly string[] | undefined,
+  allCanonical: readonly string[],
+  harness: string,
+): void => {
+  if (!names) return;
+  const set = new Set(allCanonical);
+  for (const name of names) {
+    if (name.startsWith(NATIVE_PREFIX)) continue;
+    if (!set.has(name)) {
+      throw new ArgvRefusalError({
+        issue: "unknown-tool-name",
+        harness: harness as import("../knowledge/descriptor.js").HarnessName,
+        option: "tools",
+        supported: allCanonical as unknown as string[],
+        hint: "use native:<name> for an extension or MCP tool",
+        detail: `unknown tool name ${JSON.stringify(name)}`,
+      });
+    }
+  }
+};

package/src/interpretation/turn-options.ts

@@ -14,7 +14,9 @@ import { DISCOVERY_FACETS, resolveRender, TURN_OPTION_KEYS } from "../knowledge/
 import type { DiscoveryOptions, TurnOptions } from "./argv.js";
 import { hintFor } from "./hints.js";
 import { ArgvRefusalError } from "./refusal.js";
-import { CLEAN_SELECTOR, resolveModel, validateEffort } from "./vocabulary.js";
+import { renderToolSelection } from "./tool-selection.js";
+import { READ_PRESET } from "./tool-vocabulary.js";
+import { CLEAN_SELECTOR, resolveModel, validateAccess, validateEffort } from "./vocabulary.js";
 
 // TOML-quoted value for config-kv: JSON.stringify is sufficient for the
 // closed vocabularies that may use it (enum, effort) - no value contains a
@@ -34,6 +36,20 @@ export const renderTurnOptions = (
 ): string[] => {
   const sequences: string[][] = [];
 
+  const accessRaw = opts.access;
+  if (accessRaw !== undefined) {
+    const v = validateAccess(accessRaw);
+    if (!v.ok) {
+      throw new ArgvRefusalError({
+        issue: "invalid-option-value",
+        harness: h.name,
+        option: "access",
+        supported: ["read", "write"],
+        detail: String(accessRaw),
+      });
+    }
+  }
+
   for (const key of TURN_OPTION_KEYS) {
     const spec = h.turnOptions[key];
     const raw = (opts as unknown as Record<string, unknown>)[key];
@@ -166,9 +182,85 @@ export const renderTurnOptions = (
       continue;
     }
 
+    // Access is opt-in-only, no profile default; dispatch to tool-selection for the preset.
+    if (key === "access") {
+      if (raw === undefined) continue;
+      if (spec === undefined) {
+        throw new ArgvRefusalError({
+          issue: "unsupported-option",
+          harness: h.name,
+          option: key,
+          supported: Object.keys(h.turnOptions).length ? Object.keys(h.turnOptions) : ["(none)"],
+          detail: String(raw),
+          hint: hintFor(h.name, key),
+        });
+      }
+      const v = validateAccess(raw as string);
+      if (!v.ok) {
+        throw new ArgvRefusalError({
+          issue: "invalid-option-value",
+          harness: h.name,
+          option: key,
+          supported: ["read", "write"],
+          detail: String(raw),
+        });
+      }
+      // When discovery.tools is off, the read preset must not re-enable tools.
+      if (raw === "read" && opts.discovery?.tools === false) {
+        if (spec.kind === "tool-preset") continue;
+      }
+      switch (spec.kind) {
+        case "tool-preset": {
+          if (raw === "write") break;
+          const toolMapForHarness = (opts as { toolMap?: Record<string, Record<string, string>> })
+            .toolMap?.[h.name];
+          const filtered = (READ_PRESET as readonly string[]).filter((c) => {
+            if (toolMapForHarness?.[c] !== undefined) return true;
+            if (h.tools.builtins.some((b) => b.canonical === c)) return true;
+            if (h.tools.categories.some((cat) => (cat.canonical as readonly string[]).includes(c)))
+              return true;
+            return false;
+          });
+          if (filtered.length === 0) break;
+          const rendered = renderToolSelection(h, {
+            include: filtered as unknown as string[],
+            toolMap: toolMapForHarness,
+          });
+          if (rendered.tokens.length > 0) sequences.push([...rendered.tokens]);
+          break;
+        }
+        case "flag-value": {
+          const fv = spec as Extract<typeof spec, { kind: "flag-value" }>;
+          const mapped = fv.values[raw as string];
+          if (mapped !== undefined) sequences.push([fv.flag, mapped]);
+          break;
+        }
+        case "flag-list-by-value": {
+          const fl = spec as Extract<typeof spec, { kind: "flag-list-by-value" }>;
+          const list = fl.flags[raw as string] ?? [];
+          if (list.length > 0) sequences.push([...list]);
+          break;
+        }
+        default: {
+          const _exhaustive: never = spec as never;
+          throw new ArgvRefusalError({
+            issue: "invalid-option-value",
+            harness: h.name,
+            option: key,
+            supported: [],
+            detail: String(_exhaustive),
+          });
+        }
+      }
+      continue;
+    }
+
     // Non-discovery keys
-    // Handle enum default on launch
+    // Handle enum default on launch. An access preset already claimed the
+    // sandbox flag on harnesses that express access through it (codex);
+    // the enum default must not emit a second --sandbox.
     if (raw === undefined) {
+      if (key === "sandbox" && opts.access !== undefined) continue;
       if (
         spec !== undefined &&
         spec.kind === "enum" &&
@@ -430,6 +522,11 @@ export const renderTurnOptions = (
       case "discovery":
         // already handled
         break;
+      case "tool-preset":
+      case "flag-value":
+      case "flag-list-by-value":
+        // access-only kinds - handled above for key === "access"
+        break;
       default: {
         const _exhaustive: never = spec as never;
         throw new ArgvRefusalError({

package/src/interpretation/vocabulary.ts

@@ -57,6 +57,11 @@ export const validateModel = (h: HarnessDescriptor, model: string): Validated =>
 /** Validate an effort against the ladder that applies to the pick: the
  * model's own ladder where the harness constrains per model (codex), else
  * the harness-wide ladder. */
+export const validateAccess = (value: string): Validated => {
+  if (value === "read" || value === "write") return { ok: true, id: value };
+  return { ok: false, reason: `unknown access ${JSON.stringify(value)}; accepted: read, write` };
+};
+
 export const validateEffort = (h: HarnessDescriptor, effort: string, model?: string): Validated => {
   let ladder = h.vocabulary.efforts;
   if (model !== undefined && h.vocabulary.effortsByModel !== undefined) {

package/src/knowledge/claude-code.ts

@@ -177,6 +177,7 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
         },
       },
     },
+    access: { kind: "tool-preset", render: { kind: "flag-value", flag: "--allowedTools" } },
   },
   // Phase 0 fixtures: claude-tool-interplay.md. include is a permission
   // grant (Bash, Edit stay visible under --allowedTools Read); only the
@@ -191,19 +192,19 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
     includeIsStrictAllowlist: false,
     composable: true,
     builtins: [
-      { name: "Bash", defaultEnabled: true },
-      { name: "Edit", defaultEnabled: true },
-      { name: "Glob", defaultEnabled: true },
-      { name: "Grep", defaultEnabled: true },
-      { name: "Read", defaultEnabled: true },
-      { name: "Write", defaultEnabled: true },
-      { name: "WebFetch", defaultEnabled: true },
-      { name: "WebSearch", defaultEnabled: true },
-      { name: "Monitor", defaultEnabled: true },
-      { name: "Task", defaultEnabled: true },
-      { name: "Skill", defaultEnabled: true },
-      { name: "NotebookEdit", defaultEnabled: true },
-      { name: "LSP", defaultEnabled: true },
+      { name: "Bash", defaultEnabled: true, canonical: "shell" },
+      { name: "Edit", defaultEnabled: true, canonical: "edit" },
+      { name: "Glob", defaultEnabled: true, canonical: "glob" },
+      { name: "Grep", defaultEnabled: true, canonical: "grep" },
+      { name: "Read", defaultEnabled: true, canonical: "read" },
+      { name: "Write", defaultEnabled: true, canonical: "write" },
+      { name: "WebFetch", defaultEnabled: true, canonical: "web-fetch" },
+      { name: "WebSearch", defaultEnabled: true, canonical: "web-search" },
+      { name: "Monitor", defaultEnabled: true, canonical: null },
+      { name: "Task", defaultEnabled: true, canonical: "subagent" },
+      { name: "Skill", defaultEnabled: true, canonical: "skill" },
+      { name: "NotebookEdit", defaultEnabled: true, canonical: null },
+      { name: "LSP", defaultEnabled: true, canonical: null },
     ],
     categories: [],
     denySemantics: "remove-from-set",

package/src/knowledge/codex.ts

@@ -122,6 +122,12 @@ export const codexCli: HarnessDescriptor = deepFreeze({
       render: { kind: "flag-value", flag: "--sandbox" },
       resumeRender: null,
     },
+    access: {
+      kind: "flag-value",
+      flag: "--sandbox",
+      values: { read: "read-only", write: "workspace-write" },
+      render: { kind: "flag-value", flag: "--sandbox" },
+    },
   },
   // Phase 0 fixtures: codex-tool-surface.md. No name lists anywhere -
   // not on the CLI, not in config.toml. Control is feature booleans
@@ -136,10 +142,10 @@ export const codexCli: HarnessDescriptor = deepFreeze({
     composable: false,
     builtins: [],
     categories: [
-      { key: "shell", disableFlag: null, configKey: "features.shell_tool" },
-      { key: "exec", disableFlag: null, configKey: "features.unified_exec" },
-      { key: "web", disableFlag: null, configKey: "web_search" },
-      { key: "view-image", disableFlag: null, configKey: "tools.view_image" },
+      { key: "shell", disableFlag: null, configKey: "features.shell_tool", canonical: [] },
+      { key: "exec", disableFlag: null, configKey: "features.unified_exec", canonical: [] },
+      { key: "web", disableFlag: null, configKey: "web_search", canonical: [] },
+      { key: "view-image", disableFlag: null, configKey: "tools.view_image", canonical: [] },
     ],
     denySemantics: "no-lists",
   },

package/src/knowledge/descriptor.ts

@@ -26,6 +26,21 @@ export const deepFreeze = <T>(value: T): T => {
   return value;
 };
 
+export const CANONICAL_TOOLS = deepFreeze([
+  "read",
+  "edit",
+  "write",
+  "shell",
+  "grep",
+  "glob",
+  "list",
+  "web-fetch",
+  "web-search",
+  "subagent",
+  "skill",
+] as const);
+export type CanonicalTool = (typeof CANONICAL_TOOLS)[number];
+
 export type StreamingGranularity = "token" | "message" | "none";
 
 export type HarnessMode = "headless-turn" | "headless-session" | "interactive";
@@ -95,6 +110,7 @@ export const TURN_OPTION_KEYS = deepFreeze([
   // that strips the payload changes every bare run's semantics.
   "systemPrompt",
   "appendSystemPrompt",
+  "access",
 ] as const);
 export type TurnOptionKey = (typeof TURN_OPTION_KEYS)[number];
 
@@ -141,6 +157,17 @@ export type TurnOptionSpec =
       readonly values: readonly string[];
       readonly default?: string;
     })
+  /** Access preset: read/write dimension with per-harness rendering. */
+  | (SpecBase & { readonly kind: "tool-preset" })
+  | (SpecBase & {
+      readonly kind: "flag-value";
+      readonly flag: string;
+      readonly values: Readonly<Record<string, string>>;
+    })
+  | (SpecBase & {
+      readonly kind: "flag-list-by-value";
+      readonly flags: Readonly<Record<string, readonly string[]>>;
+    })
   /** Ladder comes from vocabulary.efforts / effortsByModel, not from here. */
   | (SpecBase & { readonly kind: "effort" })
   /** Open selector, CLEAN_SELECTOR-validated. */
@@ -187,8 +214,14 @@ export const getOptionRender = (
   spec: TurnOptionSpec,
   phase: "launch" | "resume",
 ): OptionRender | null => {
-  if (spec.kind === "discovery") return null;
-  return resolveRender(spec, phase);
+  if (
+    spec.kind === "discovery" ||
+    spec.kind === "tool-preset" ||
+    spec.kind === "flag-value" ||
+    spec.kind === "flag-list-by-value"
+  )
+    return null;
+  return resolveRender(spec as SpecBase, phase);
 };
 
 export interface HarnessDescriptor {
@@ -405,11 +438,13 @@ export interface HarnessDescriptor {
     readonly builtins: ReadonlyArray<{
       readonly name: string;
       readonly defaultEnabled: boolean;
+      readonly canonical: CanonicalTool | null;
     }>;
     readonly categories: ReadonlyArray<{
       readonly key: "shell" | "write" | "web" | "exec" | "view-image";
       readonly disableFlag: string | null;
       readonly configKey: string | null;
+      readonly canonical: readonly CanonicalTool[];
     }>;
     readonly denySemantics: "remove-from-set" | "policy-gate" | "no-lists";
   };

package/src/knowledge/muse.ts

@@ -109,6 +109,11 @@ export const museCode: HarnessDescriptor = deepFreeze({
       max: 10000,
       render: { kind: "flag-value", flag: "--max-model-steps" },
     },
+    access: {
+      kind: "flag-list-by-value",
+      flags: { read: ["--disable-write", "--disable-shell"], write: [] },
+      render: { kind: "flag-list", flags: ["--disable-write", "--disable-shell"] },
+    },
   },
   // Phase 0 fixtures: muse-category-flags.md. No name lists; category
   // switches are enforcement gates - tools stay listed in the catalog but
@@ -124,9 +129,19 @@ export const museCode: HarnessDescriptor = deepFreeze({
     composable: false,
     builtins: [],
     categories: [
-      { key: "write", disableFlag: "--disable-write", configKey: null },
-      { key: "shell", disableFlag: "--disable-shell", configKey: null },
-      { key: "web", disableFlag: "--disable-web-tools", configKey: null },
+      {
+        key: "write",
+        disableFlag: "--disable-write",
+        configKey: null,
+        canonical: ["write", "edit"],
+      },
+      { key: "shell", disableFlag: "--disable-shell", configKey: null, canonical: ["shell"] },
+      {
+        key: "web",
+        disableFlag: "--disable-web-tools",
+        configKey: null,
+        canonical: ["web-fetch", "web-search"],
+      },
     ],
     denySemantics: "policy-gate",
   },

package/src/knowledge/overrides.ts

@@ -25,12 +25,14 @@ import { piCli } from "./pi.js";
 
 export type DescriptorSet = Partial<Record<HarnessName, HarnessDescriptor>>;
 
-export const defaultDescriptors = (): DescriptorSet => ({
+const SHARED_DESCRIPTORS: DescriptorSet = {
   claude: claudeCode,
   codex: codexCli,
   pi: piCli,
   muse: museCode,
-});
+};
+
+export const defaultDescriptors = (): DescriptorSet => SHARED_DESCRIPTORS;
 
 /** Tracks which descriptors were produced by an override file and what their
  * matcher counts are, so the execution layer can emit `matcherOverrides` on

package/src/knowledge/pi.ts

@@ -154,6 +154,7 @@ export const piCli: HarnessDescriptor = deepFreeze({
         },
       },
     },
+    access: { kind: "tool-preset", render: { kind: "flag-value", flag: "--tools" } },
   },
   // Phase 0 fixtures: pi-both-tool-flags.md. Both list flags legal at once;
   // exclude subtracts from include. --tools is strict over BUILT-INS but
@@ -166,13 +167,13 @@ export const piCli: HarnessDescriptor = deepFreeze({
     includeIsStrictAllowlist: true,
     composable: true,
     builtins: [
-      { name: "read", defaultEnabled: true },
-      { name: "bash", defaultEnabled: true },
-      { name: "edit", defaultEnabled: true },
-      { name: "write", defaultEnabled: true },
-      { name: "grep", defaultEnabled: false },
-      { name: "find", defaultEnabled: false },
-      { name: "ls", defaultEnabled: false },
+      { name: "read", defaultEnabled: true, canonical: "read" },
+      { name: "bash", defaultEnabled: true, canonical: "shell" },
+      { name: "edit", defaultEnabled: true, canonical: "edit" },
+      { name: "write", defaultEnabled: true, canonical: "write" },
+      { name: "grep", defaultEnabled: false, canonical: "grep" },
+      { name: "find", defaultEnabled: false, canonical: "glob" },
+      { name: "ls", defaultEnabled: false, canonical: "list" },
     ],
     categories: [],
     denySemantics: "remove-from-set",