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

package/src/cli/refuse.ts

@@ -0,0 +1,50 @@
+import { failureFromRejected } from "../execution/failure.js";
+import type { ArgvRefusalError, RefusalIssue } from "../interpretation/refusal.js";
+import { writeEventNdjson } from "./render.js";
+
+export interface Refusal {
+  readonly message: string;
+  readonly issue: RefusalIssue;
+  readonly option?: ArgvRefusalError["option"];
+  readonly facet?: ArgvRefusalError["facet"];
+  readonly supported?: readonly string[];
+  readonly supportedBy?: ArgvRefusalError["supportedBy"];
+  readonly hint?: string;
+  readonly trailer?: readonly string[];
+}
+
+export const refusalOf = (err: ArgvRefusalError): Refusal => ({
+  message: err.message,
+  issue: err.issue,
+  option: err.option,
+  facet: err.facet,
+  supported: err.supported,
+  supportedBy: err.supportedBy,
+  hint: err.hint,
+});
+
+export const refuse = (r: Refusal, json: boolean): void => {
+  process.stderr.write(`${r.message}\n`);
+  if (r.hint) process.stderr.write(`hint: ${r.hint}\n`);
+  if (r.supportedBy?.length) {
+    process.stderr.write(
+      `supported on: ${r.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+    );
+  }
+  if (r.supported?.length) process.stderr.write(`supported: ${r.supported.join(", ")}\n`);
+  for (const line of r.trailer ?? []) process.stderr.write(`${line}\n`);
+  if (json) {
+    const summary = failureFromRejected({
+      issue: r.issue,
+      option: r.option,
+      facet: r.facet,
+      supported: r.supported,
+      supportedBy: r.supportedBy,
+      hint: r.hint,
+      detail: r.message,
+    });
+    writeEventNdjson({ kind: "failure", ...summary });
+    writeEventNdjson({ kind: "done", exitCode: null, cause: "failed", failure: summary });
+  }
+  process.exitCode = 2;
+};

package/src/cli/resume-guard.ts

@@ -0,0 +1,35 @@
+import { existsSync, realpathSync } from "node:fs";
+import { storePath } from "../interpretation/store.js";
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+
+export interface ResumeStoreCheck {
+  /** The store path hcn expects for this cwd and id, or null when the
+   * descriptor cannot compute one. */
+  readonly path: string | null;
+  readonly exists: boolean;
+}
+
+/** Where a harness that creates sessions on an unknown id (pi, muse) would
+ * have filed this session. The cwd is resolved to its real path first: the
+ * harness slugs the directory it actually ran in, and on macOS a temp
+ * directory reached through /var is really under /private/var - slugging
+ * the unresolved path refused valid resumes. */
+export const resumeStore = (
+  h: HarnessDescriptor,
+  opts: { readonly cwd: string; readonly home: string; readonly sessionId: string },
+): ResumeStoreCheck => {
+  let cwd = opts.cwd;
+  try {
+    cwd = realpathSync.native(opts.cwd);
+  } catch {
+    // A cwd that does not exist yet resolves to itself; the harness will
+    // create it and slug whatever it created.
+  }
+  let path: string | null = null;
+  try {
+    path = storePath(h, { home: opts.home, cwd, sessionId: opts.sessionId });
+  } catch {
+    path = null;
+  }
+  return { path, exists: path !== null && existsSync(path) };
+};

package/src/cli/run.ts

@@ -1,71 +1,17 @@
-import { existsSync } from "node:fs";
 import type { HarnessEvent } from "../execution/events.js";
-import { failureFromRejected } from "../execution/failure.js";
 import { nodeRunnerDeps } from "../execution/node-deps.js";
 import { KILL_GRACE_MS, redactArgv, streamTurn } from "../execution/stream-turn.js";
 import { buildLaunchArgv, buildResumeArgv } from "../interpretation/argv.js";
 import { composeEscalatedPrompt } from "../interpretation/question.js";
-import type { RefusalIssue } from "../interpretation/refusal.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 import { FloorExceededError, resolveEffectiveOptions } from "../interpretation/resolve-options.js";
-import { storePath } from "../interpretation/store.js";
 import { recognizeNativeSpelling, supportedBy } from "../interpretation/support.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { parseRunExtra, parseTurnOptions, resolvePromptAsync } from "./args.js";
+import { refusalOf, refuse } from "./refuse.js";
 import { createRenderState, renderEvent, writeEventNdjson } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
-
-/** One shape for every hcn-side refusal. Stderr keeps the prose (message,
- * hint, support lists, usage pointer); under --json the same fields also
- * ride stdout as a `failure` event plus a `done`, so a stream reader never
- * meets an empty stream on exit 2. */
-interface Refusal {
-  readonly message: string;
-  readonly issue: RefusalIssue;
-  readonly option?: ArgvRefusalError["option"];
-  readonly facet?: ArgvRefusalError["facet"];
-  readonly supported?: readonly string[];
-  readonly supportedBy?: ArgvRefusalError["supportedBy"];
-  readonly hint?: string;
-  /** Plain stderr lines written after the structured ones. */
-  readonly trailer?: readonly string[];
-}
-
-const refusalOf = (err: ArgvRefusalError): Refusal => ({
-  message: err.message,
-  issue: err.issue,
-  option: err.option,
-  facet: err.facet,
-  supported: err.supported,
-  supportedBy: err.supportedBy,
-  hint: err.hint,
-});
-
-const refuse = (r: Refusal, json: boolean): void => {
-  process.stderr.write(`${r.message}\n`);
-  if (r.hint) process.stderr.write(`hint: ${r.hint}\n`);
-  if (r.supportedBy?.length) {
-    process.stderr.write(
-      `supported on: ${r.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
-    );
-  }
-  if (r.supported?.length) process.stderr.write(`supported: ${r.supported.join(", ")}\n`);
-  for (const line of r.trailer ?? []) process.stderr.write(`${line}\n`);
-  if (json) {
-    const summary = failureFromRejected({
-      issue: r.issue,
-      option: r.option,
-      facet: r.facet,
-      supported: r.supported,
-      supportedBy: r.supportedBy,
-      hint: r.hint,
-      detail: r.message,
-    });
-    writeEventNdjson({ kind: "failure", ...summary });
-    writeEventNdjson({ kind: "done", exitCode: null, cause: "failed", failure: summary });
-  }
-  process.exitCode = 2;
-};
+import { resumeStore } from "./resume-guard.js";
 
 export const run = async (harnessName: string, rawArgs: string[]): Promise<void> => {
   const h = resolveHarness(harnessName);
@@ -295,6 +241,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
         refuse({ message: resErr.message, issue: "invalid-tool-grant" }, wantJson);
         return;
       }
+      if (resErr instanceof ArgvRefusalError) {
+        refuse(refusalOf(resErr), wantJson);
+        return;
+      }
       throw resErr;
     }
     const { provenance, unrenderable } = resolved;
@@ -408,12 +358,12 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     // all refuses inside buildLaunchArgv below, so a throw here is left
     // to that path.
     const grant = (fullOpts.resume ? turnOpts : effectiveTurnOpts).tools;
-    if (grant !== undefined && grant.length > 0 && !h.tools.includeIsStrictAllowlist) {
+    if (grant !== undefined && grant.length > 0) {
       try {
         const { renderToolSelection } = await import("../interpretation/tool-selection.js");
-        const { unmapped } = renderToolSelection(h, { include: [...grant] });
-        if (unmapped.length > 0) {
-          process.stderr.write(`provenance: unmapped tools = ${JSON.stringify(unmapped)}\n`);
+        const { passthrough } = renderToolSelection(h, { include: [...grant] });
+        if (passthrough.length > 0) {
+          process.stderr.write(`provenance: native tools = ${JSON.stringify(passthrough)}\n`);
         }
       } catch {
         // refused below with the structured message
@@ -426,17 +376,12 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   // the session store path does not exist; where the path cannot be
   // computed, the runner's pre-spawn warning is the only guard.
   if (fullOpts.resume !== undefined && h.resume.onMissing === "create") {
-    let path: string | null = null;
-    try {
-      path = storePath(h, {
-        home: process.env.HOME ?? process.env.USERPROFILE ?? "",
-        cwd: extra.cwd ?? process.cwd(),
-        sessionId: fullOpts.resume,
-      });
-    } catch {
-      path = null;
-    }
-    if (path !== null && !existsSync(path)) {
+    const { path, exists } = resumeStore(h, {
+      home: process.env.HOME ?? process.env.USERPROFILE ?? "",
+      cwd: extra.cwd ?? process.cwd(),
+      sessionId: fullOpts.resume,
+    });
+    if (path !== null && !exists) {
       refuse(
         {
           message: `no ${h.name} session ${fullOpts.resume} found at ${path}`,

package/src/interpretation/argv.ts

@@ -83,6 +83,9 @@ export interface TurnOptions {
   readonly escalateQuestions?: boolean;
   /** Internal: set by CLI when prompt came from --prompt/--prompt-file to bypass leading '-' guard */
   readonly __explicitPrompt?: boolean;
+  /** toolMap extensible vocabulary per harness (issue toolMap) */
+  readonly toolMap?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  readonly access?: "read" | "write";
 }
 
 export interface ResumeOptions extends TurnOptions {
@@ -124,9 +127,11 @@ const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
     tail.push(h.autonomy.flag);
   }
   if (opts.tools !== undefined || opts.excludeTools !== undefined) {
+    const perHarnessMap = opts.toolMap?.[h.name];
     const rendered = renderToolSelection(h, {
       include: opts.tools,
       exclude: opts.excludeTools,
+      toolMap: perHarnessMap,
     });
     tail.push(...rendered.tokens);
   }

package/src/interpretation/hints.ts

@@ -27,6 +27,10 @@ const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFr
       "claude has no isolated instruction-file toggle; --setting-sources project isolates from user-level settings but also skips hooks, LSP and keychain reads - weigh that before using it as an approximation",
   },
   codex: {
+    tools:
+      "codex has no per-tool name lists; use --sandbox read-only for a read-only grant or category switches via config keys (features.shell_tool, web_search)",
+    excludeTools:
+      "codex has no per-tool name lists; use category switches via config keys (features.shell_tool) or --sandbox modes",
     write:
       "codex has no write toggle; use --sandbox read-only (config: sandbox_mode) so shell commands cannot write either",
     // issue #48: the append half has no codex spelling.
@@ -58,6 +62,10 @@ const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFr
       "pi has no step cap flag; bound the work in the prompt or impose a wall-clock timeout at the caller",
   },
   muse: {
+    tools:
+      "muse has no per-tool name lists; gate execution with --disable-write, --disable-shell, --disable-web-tools - there is no allowlist",
+    excludeTools:
+      "muse has no per-tool name lists; gate execution with --disable-write, --disable-shell, --disable-web-tools category switches",
     sandbox:
       "muse's sandbox is on by default and not selectable per-call; --disable-sandbox exists to turn it OFF, and exposure can be tuned with --disable-write, --disable-shell, --disable-web-tools - there is no mode selector",
     provider:

package/src/interpretation/resolve-options.ts

@@ -8,8 +8,13 @@
  * sandbox default already follows).
  */
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
 import { DEFAULT_TURN_PROFILE, type ProfileKey } from "../knowledge/profile.js";
 import type { TurnOptions } from "./argv.js";
+import { ArgvRefusalError } from "./refusal.js";
+import type { ToolMap } from "./tool-vocabulary.js";
+import { allCanonicalNames, mergeToolMaps, validateCanonicalList } from "./tool-vocabulary.js";
+import { validateAccess } from "./vocabulary.js";
 
 export type ProvenanceTier = "arg" | "project-config" | "user-config" | "profile" | "harness";
 
@@ -126,8 +131,100 @@ export const resolveEffectiveOptions = (
   }
   const resolved: Record<string, unknown> = { ...effectiveArgs };
 
-  // D5 floor: a project toolset floor caps any arg grant; exceeding it is
-  // a structured refusal naming both sets - never a silent clamp.
+  // Validate access value before exclusivity so invalid reports invalid-option-value, not mutual exclusion.
+  if (resolved.access !== undefined) {
+    const v = validateAccess(String(resolved.access));
+    if (!v.ok) {
+      throw new ArgvRefusalError({
+        issue: "invalid-option-value",
+        harness: h.name,
+        option: "access",
+        supported: ["read", "write"],
+        detail: String(resolved.access),
+      });
+    }
+  }
+  // Access exclusivity on codex: explicit --sandbox together with --access refuses.
+  // Profile sandbox yields to access - only explicit sandbox counts.
+  if (h.name === "codex" && resolved.access !== undefined) {
+    const hasExplicitSandbox =
+      effectiveArgs.sandbox !== undefined || sourceTier("sandbox") !== undefined;
+    if (hasExplicitSandbox) {
+      throw new ArgvRefusalError({
+        issue: "mutually-exclusive-options",
+        harness: h.name,
+        option: "access",
+        supported: ["--access or --sandbox, not both on codex"],
+        detail: "mutual exclusion",
+      });
+    }
+  }
+  // Access vs tools exclusivity: only explicit tools/excludeTools from args or config, never profile-derived.
+  if (resolved.access !== undefined) {
+    const explicitTools = effectiveArgs.tools !== undefined || sourceTier("tools") !== undefined;
+    const explicitExclude =
+      (effectiveArgs as unknown as Record<string, unknown>).excludeTools !== undefined ||
+      sourceTier("excludeTools") !== undefined;
+    if (explicitTools || explicitExclude) {
+      throw new ArgvRefusalError({
+        issue: "mutually-exclusive-options",
+        harness: h.name,
+        option: "access",
+        supported: ["--access is a preset allowlist, not a filter over --tools/--exclude-tools"],
+        detail: "mutual exclusion",
+      });
+    }
+  }
+
+  // toolMap merge per harness per canonical (project > user)
+  const rawToolMapUser = (tiers.user as { toolMap?: ToolMap } | undefined)?.toolMap;
+  const rawToolMapProject = (tiers.project as { toolMap?: ToolMap } | undefined)?.toolMap;
+  const mergedToolMap = mergeToolMaps({ user: rawToolMapUser, project: rawToolMapProject });
+  if (Object.keys(mergedToolMap).length > 0) {
+    // Convert mergedToolMap to legacy shape for resolved.toolMap consumers
+    const legacy: Record<string, Record<string, string>> = {};
+    for (const [harness, per] of Object.entries(mergedToolMap)) {
+      legacy[harness] = {};
+      for (const [canon, entry] of Object.entries(per as Record<string, { native: string }>)) {
+        legacy[harness]![canon] = entry.native;
+      }
+    }
+    resolved.toolMap = legacy as unknown as typeof resolved.toolMap;
+    const harnessMap = mergedToolMap[h.name];
+    if (harnessMap) {
+      for (const [canonical, entry] of Object.entries(harnessMap)) {
+        provenance.push({
+          key: `tools.${canonical}`,
+          value: entry.native,
+          tier: entry.tier as ProvenanceTier,
+        });
+      }
+    }
+  }
+
+  // Lazy allCanonical build only when tools context present
+  const needsCanonical =
+    tiers.project?.tools !== undefined ||
+    tiers.user?.tools !== undefined ||
+    effectiveArgs.tools !== undefined ||
+    (effectiveArgs as unknown as Record<string, unknown>).excludeTools !== undefined ||
+    Object.keys(toolsets).length > 0 ||
+    tiers.project?.toolMap !== undefined ||
+    tiers.user?.toolMap !== undefined;
+  let allCanonical: readonly string[] | undefined;
+  const getAllCanonical = (): readonly string[] => {
+    if (allCanonical) return allCanonical;
+    allCanonical = allCanonicalNames(defaultDescriptors(), mergedToolMap as unknown as ToolMap);
+    return allCanonical;
+  };
+  if (needsCanonical) {
+    const ac = getAllCanonical();
+    validateCanonicalList(tiers.project?.tools as readonly string[] | undefined, ac, h.name);
+    validateCanonicalList(tiers.user?.tools as readonly string[] | undefined, ac, h.name);
+    for (const set of Object.values(toolsets)) {
+      validateCanonicalList(set as readonly string[], ac, h.name);
+    }
+  }
   const floor = tiers.project?.tools;
   if (floor !== undefined && effectiveArgs.tools !== undefined) {
     const floorSet = new Set(floor);
@@ -158,6 +255,19 @@ export const resolveEffectiveOptions = (
       provenance.push({ key, value, tier: "harness" });
       continue;
     }
+    // When access is set, skip the all-known expansion (access is a preset allowlist, not a filter).
+    // Same shape as --no-tools skip; provenance owned by tier that set access.
+    if (key === "tools" && value === "all-known" && resolved.access !== undefined) {
+      const accessTier: ProvenanceTier =
+        effectiveArgs.access !== undefined ? "arg" : (sourceTier("access") ?? "user-config");
+      provenance.push({ key, value: "none (access preset)", tier: accessTier });
+      continue;
+    }
+    // Profile sandbox yields to access - when access is set, drop profile sandbox.
+    if (key === "sandbox" && resolved.access !== undefined) {
+      provenance.push({ key, value: `${String(value)} (access)`, tier: "harness" });
+      continue;
+    }
     // D13: the tools marker expands per descriptor. On a harness whose
     // default is already everything (claude), expansion emits nothing -
     // the emit-nothing rule, recorded in provenance. On a harness with
@@ -186,7 +296,9 @@ export const resolveEffectiveOptions = (
         provenance.push({ key, value: "all known (already default)", tier: "profile" });
         continue;
       }
-      const expanded = h.tools.builtins.map((t) => t.name);
+      const expanded = h.tools.builtins
+        .filter((t) => t.canonical !== null)
+        .map((t) => t.canonical as string);
       resolved[key] = expanded;
       provenance.push({ key, value: expanded, tier: "profile" });
       continue;
@@ -213,6 +325,7 @@ export const resolveEffectiveOptions = (
   // (validated later by the same renderers as args).
   for (const [key, value] of Object.entries(config)) {
     if (key === "toolsets") continue; // expanded into args above, never a turn option
+    if (key === "toolMap") continue; // per-canonical provenance already emitted
     if (key in DEFAULT_TURN_PROFILE) continue;
     if (effectiveArgs[key as keyof TurnOptions] !== undefined) {
       provenance.push({ key, value: effectiveArgs[key as keyof TurnOptions], tier: "arg" });
@@ -223,6 +336,19 @@ export const resolveEffectiveOptions = (
     provenance.push({ key, value, tier });
   }
 
+  // Access divergence / fixup
+  if (resolved.access !== undefined && h.turnOptions.access === undefined) {
+    unrenderable.push("access");
+    for (let i = provenance.length - 1; i >= 0; i--)
+      if (provenance[i]?.key === "access") provenance.splice(i, 1);
+    provenance.push({ key: "access", value: resolved.access as string, tier: "harness" });
+    delete (resolved as Record<string, unknown>).access;
+  } else if (resolved.access !== undefined && !provenance.some((p) => p.key === "access")) {
+    const tier: ProvenanceTier =
+      effectiveArgs.access !== undefined ? "arg" : (sourceTier("access") ?? "user-config");
+    provenance.push({ key: "access", value: resolved.access as string, tier });
+  }
+
   return {
     options: resolved as unknown as TurnOptions,
     provenance,

package/src/interpretation/support.ts

@@ -14,6 +14,8 @@
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 import type { DescriptorSet } from "../knowledge/overrides.js";
 import type { RefusalOption } from "./refusal.js";
+import type { VocabularyEntry } from "./tool-vocabulary.js";
+import { canonicalTable } from "./tool-vocabulary.js";
 
 export interface SupportEntry {
   readonly harness: string;
@@ -23,6 +25,15 @@ export interface SupportEntry {
 
 const spellingOf = (h: HarnessDescriptor, option: RefusalOption): string | null => {
   switch (option) {
+    case "access": {
+      const spec = h.turnOptions.access;
+      if (spec === undefined) return null;
+      if (spec.kind === "flag-value") return spec.flag;
+      if (spec.kind === "flag-list-by-value") return Object.values(spec.flags)[0]?.[0] ?? null;
+      if (spec.kind === "tool-preset")
+        return h.tools.includeFlag ?? h.tools.excludeFlag ?? "--sandbox";
+      return null;
+    }
     case "tools":
       return h.tools.includeFlag;
     case "excludeTools":
@@ -69,6 +80,25 @@ export const supportedBy = (set: DescriptorSet, option: RefusalOption): readonly
   return out;
 };
 
+export const supportedByCanonical = (
+  set: DescriptorSet,
+  canonical: string,
+): readonly SupportEntry[] => {
+  const table = canonicalTable(set);
+  const entry = table[canonical];
+  if (!entry) return [];
+  const out: SupportEntry[] = [];
+  for (const [har, val] of Object.entries(entry)) {
+    if (val === undefined) continue;
+    const spelling =
+      (val as VocabularyEntry).kind === "builtin"
+        ? (val as { kind: "builtin"; native: string }).native
+        : (val as { kind: "category"; key: string }).key;
+    out.push({ harness: har, spelling });
+  }
+  return out;
+};
+
 /** Reverse lookup for native-spelling recognition (D7 part B): given a raw
  * flag token a caller typed, find the option it belongs to and which
  * harnesses spell it that way. Returns null for tokens no descriptor