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

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",