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

package/src/interpretation/tool-selection.ts

@@ -1,73 +1,89 @@
 /**
- * Tool-selection rendering: turns normalized include/exclude lists into the
- * per-harness argv tokens, per decisions D1-D3 and the Phase 0 evidence.
- *
- * Semantics:
- * - include: exact allowlist over the descriptor's curated names. pi's flag
- *   is strict over built-ins, rendered directly. claude's include flag only
- *   pre-approves without restricting the visible set, so an exact allowlist
- *   on claude renders as a deny-complement (all known minus included).
- * - exclude: the complement of the named tools over all descriptor-known
- *   names (D2). pi's native exclude subtracts from its default set (4
- *   tools), so a D2 exclude renders as a computed include list there.
- * - mutual exclusion (D1): both flags in one call refuse.
- * - extensible rule (D3): curated names validate and map; unknown
- *   clean-selector names pass through and are reported as unmapped so
- *   provenance can surface them.
+ * Tool-selection rendering with canonical vocabulary.
  */
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
+import { hintFor } from "./hints.js";
 import { ArgvRefusalError } from "./refusal.js";
-import { supportedBy } from "./support.js";
+import { supportedBy, supportedByCanonical } from "./support.js";
+import {
+  allCanonicalNames,
+  canonicalTable,
+  hasCounterpart,
+  NATIVE_PREFIX,
+  nativeFor,
+  parseToolSelector,
+  READ_PRESET,
+  validateCanonicalList,
+} from "./tool-vocabulary.js";
 
 export const TOOL_SELECTOR = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,127}$/;
 
 export interface ToolSelection {
   readonly include?: readonly string[];
   readonly exclude?: readonly string[];
+  readonly toolMap?: Readonly<Record<string, string>>;
 }
 
 export interface RenderedToolSelection {
   readonly tokens: readonly string[];
-  readonly unmapped: readonly string[];
+  readonly passthrough: readonly string[];
 }
 
-const validateNames = (h: HarnessDescriptor, names: readonly string[]): string[] => {
-  for (const name of names) {
-    if (name.trim() === "" || name.includes(",")) {
-      throw new ArgvRefusalError({
-        issue: "invalid-tool-grant",
-        harness: h.name,
-        supported: ["non-empty, comma-free tool names"],
-        detail: `tools=${JSON.stringify(names)}`,
-      });
-    }
-    if (!TOOL_SELECTOR.test(name)) {
-      throw new ArgvRefusalError({
-        issue: "invalid-tool-grant",
-        harness: h.name,
-        supported: [`must match ${TOOL_SELECTOR.source}`],
-        detail: name,
-      });
-    }
+const validateInnerName = (h: HarnessDescriptor, name: string, raw: readonly string[]): void => {
+  if (name.trim() === "" || name.includes(",")) {
+    throw new ArgvRefusalError({
+      issue: "invalid-tool-grant",
+      harness: h.name,
+      supported: ["non-empty, comma-free tool names"],
+      detail: `tools=${JSON.stringify(raw)}`,
+    });
+  }
+  if (!TOOL_SELECTOR.test(name)) {
+    throw new ArgvRefusalError({
+      issue: "invalid-tool-grant",
+      harness: h.name,
+      supported: [`must match ${TOOL_SELECTOR.source}`],
+      detail: name,
+    });
   }
-  return [...names];
 };
 
-/** Curated-name mapping plus extensible pass-through; returns the effective
- * names and which of them the descriptor could not vouch for. */
-const resolveNames = (
+const categoriesFor = (
   h: HarnessDescriptor,
-  names: readonly string[],
-): { mapped: string[]; unmapped: string[] } => {
-  const known = new Set(h.tools.builtins.map((t) => t.name));
-  const mapped: string[] = [];
-  const unmapped: string[] = [];
-  for (const name of names) {
-    if (known.has(name)) mapped.push(name);
-    else unmapped.push(name);
+  canonicals: readonly string[],
+  table: ReturnType<typeof canonicalTable>,
+): Set<string> => {
+  const cats = new Set<string>();
+  for (const c of canonicals) {
+    const val = table[c]?.[h.name];
+    if (val?.kind === "category") cats.add(val.key);
   }
-  return { mapped, unmapped };
+  return cats;
+};
+
+export const renderAccessPreset = (
+  h: HarnessDescriptor,
+  access: "read" | "write",
+  opts: { toolMap?: Readonly<Record<string, string>> } = {},
+): string[] => {
+  if (access === "write") return [];
+  // read preset
+  const filtered = (READ_PRESET as readonly string[]).filter((c) => {
+    if (opts.toolMap?.[c] !== undefined) return true;
+    const table = canonicalTable(defaultDescriptors());
+    return table[c]?.[h.name] !== undefined;
+  });
+  if (filtered.length === 0) return [];
+  // For tool-preset harnesses, render via tool-selection include
+  const spec = h.turnOptions.access;
+  if (spec && spec.kind === "tool-preset") {
+    const rendered = renderToolSelection(h, { include: filtered, toolMap: opts.toolMap });
+    return [...rendered.tokens];
+  }
+  // For flag-value / flag-list-by-value harnesses, caller should handle via spec mapping;
+  // we return empty here so turn-options can map via spec values.
+  return [];
 };
 
 export const renderToolSelection = (
@@ -77,7 +93,6 @@ export const renderToolSelection = (
   const hasInclude = selection.include !== undefined;
   const hasExclude = selection.exclude !== undefined;
 
-  // D1: mutual exclusivity, structured refusal.
   if (hasInclude && hasExclude) {
     throw new ArgvRefusalError({
       issue: "mutually-exclusive-options",
@@ -87,31 +102,116 @@ export const renderToolSelection = (
       detail: "mutual exclusion",
     });
   }
-  if (!hasInclude && !hasExclude) return { tokens: [], unmapped: [] };
+  if (!hasInclude && !hasExclude) return { tokens: [], passthrough: [] };
+
+  const set = defaultDescriptors();
+  const table = canonicalTable(set);
+  const toolMap = selection.toolMap ?? {};
+  const allCanonical = allCanonicalNames(set, {
+    [h.name]: toolMap as unknown as Record<string, string>,
+  } as unknown as import("./tool-vocabulary.js").ToolMap);
+
+  const splitSelection = (
+    names: readonly string[],
+  ): { canonical: string[]; passthrough: string[] } => {
+    const canonical: string[] = [];
+    const passthrough: string[] = [];
+    const setForValidate = new Set(allCanonical);
+    for (const raw of names) {
+      const parsed = parseToolSelector(raw);
+      if (parsed.kind === "native") {
+        validateInnerName(h, parsed.name, names);
+        passthrough.push(parsed.name);
+        continue;
+      }
+      validateInnerName(h, parsed.name, names);
+      if (!setForValidate.has(parsed.name)) {
+        throw new ArgvRefusalError({
+          issue: "unknown-tool-name",
+          harness: h.name,
+          option: "tools",
+          supported: [...allCanonical],
+          hint: "use native:<name> for an extension or MCP tool",
+          detail: `unknown tool name(s) ${parsed.name}`,
+        });
+      }
+      canonical.push(parsed.name);
+    }
+    return { canonical, passthrough };
+  };
+
+  const isCodexShape = h.tools.includeFlag === null && h.tools.categories.length === 0;
+  const isCategoryShape = h.tools.includeFlag === null && h.tools.categories.length > 0;
 
-  if (h.tools.includeFlag === null || h.tools.excludeFlag === null) {
-    const option = hasInclude ? "tools" : "excludeTools";
-    const by = supportedBy(defaultDescriptors(), option);
+  if (isCodexShape) {
     throw new ArgvRefusalError({
       issue: "unsupported-option",
       harness: h.name,
-      option,
+      option: hasInclude ? "tools" : "excludeTools",
       supported: ["per-tool name lists"],
-      supportedBy: by,
+      supportedBy: supportedBy(set, hasInclude ? "tools" : "excludeTools"),
       hint:
-        h.name === "codex"
-          ? "nearest control on codex: category switches via config keys (features.shell_tool, web_search) or sandbox modes - see `hcn inspect codex`"
-          : "nearest control on muse: category switches (--disable-write, --disable-shell, --disable-web-tools) gate tool execution per session",
+        hintFor(h.name, hasInclude ? "tools" : "excludeTools") ??
+        "nearest control on codex: category switches via config keys (features.shell_tool, web_search) or sandbox modes - see `hcn inspect codex`",
     });
   }
+  if (isCategoryShape) {
+    const names = hasInclude ? selection.include! : selection.exclude!;
+    const { canonical, passthrough } = splitSelection(names);
+
+    if (hasExclude) {
+      // one helper replaces the three no-counterpart loops
+      for (const c of canonical) {
+        const has = toolMap[c] !== undefined || table[c]?.[h.name] !== undefined;
+        if (!has) {
+          throw new ArgvRefusalError({
+            issue: "unsupported-option",
+            harness: h.name,
+            option: "excludeTools",
+            supported: ["per-tool name lists"],
+            supportedBy: supportedByCanonical(set, c),
+            hint: hintFor(h.name, "excludeTools"),
+          });
+        }
+      }
+      const cats = categoriesFor(h, canonical, table);
+      const tokens: string[] = [];
+      for (const cat of h.tools.categories) {
+        if (cats.has(cat.key) && cat.disableFlag) tokens.push(cat.disableFlag);
+      }
+      return { tokens, passthrough };
+    }
+
+    for (const c of canonical) {
+      const has = toolMap[c] !== undefined || table[c]?.[h.name] !== undefined;
+      if (!has) {
+        throw new ArgvRefusalError({
+          issue: "unsupported-option",
+          harness: h.name,
+          option: "tools",
+          supported: ["per-tool name lists"],
+          supportedBy: supportedByCanonical(set, c),
+          hint: hintFor(h.name, "tools"),
+        });
+      }
+    }
+    if (canonical.length === 0) {
+      const tokens = h.tools.categories.map((c) => c.disableFlag).filter((f): f is string => !!f);
+      return { tokens, passthrough };
+    }
+    const grantedCats = categoriesFor(h, canonical, table);
+    const tokens: string[] = [];
+    for (const cat of h.tools.categories) {
+      if (!grantedCats.has(cat.key) && cat.disableFlag) tokens.push(cat.disableFlag);
+    }
+    return { tokens, passthrough };
+  }
 
+  // From here: h has list flags (claude, pi)
   if (hasInclude) {
-    const names = validateNames(h, selection.include!);
+    const names = selection.include!;
     if (names.length === 0) {
-      // Empty include list = deny everything. On pi --tools "" has no
-      // defined meaning, so refuse; on claude emit the deny complement
-      // without an empty include token.
-      if (h.tools.includeIsStrictAllowlist || h.tools.excludeFlag === null) {
+      if (h.tools.includeIsStrictAllowlist) {
         throw new ArgvRefusalError({
           issue: "invalid-tool-grant",
           harness: h.name,
@@ -121,66 +221,90 @@ export const renderToolSelection = (
         });
       }
       const known = h.tools.builtins.map((t) => t.name);
-      return { tokens: [h.tools.excludeFlag, known.join(",")], unmapped: [] };
+      return { tokens: [h.tools.excludeFlag!, known.join(",")], passthrough: [] };
     }
-    const { mapped, unmapped } = resolveNames(h, names);
-    if (!h.tools.includeIsStrictAllowlist) {
-      if (mapped.length === 0 && unmapped.length > 0) {
+    const { canonical, passthrough } = splitSelection(names);
+    for (const c of canonical) {
+      const has = toolMap[c] !== undefined || table[c]?.[h.name] !== undefined;
+      if (!has) {
         throw new ArgvRefusalError({
-          issue: "unknown-tool-name",
+          issue: "unsupported-option",
           harness: h.name,
           option: "tools",
-          supported: [`known tool names: ${h.tools.builtins.map((t) => t.name).join(", ")}`],
-          detail: `unknown tool name(s) ${unmapped.join(", ")}`,
+          supported: ["per-tool name lists"],
+          supportedBy: supportedByCanonical(set, c),
+          hint: `add toolMap.${h.name}.${c} to ~/.config/hcn/config.json or pass native:${c}`,
         });
       }
-      // claude: exact allowlist must reshape the visible set via the deny
-      // complement (probe 2b). The include flag also carries the granted
-      // names (curated + pass-throughs) so they skip approval prompts;
-      // unmapped names ride along - the deny complement is computed over
-      // curated names only, so an extension tool in an include is granted,
-      // never denied.
+    }
+    const mapped: string[] = [];
+    for (const c of canonical) {
+      let n: string | null = toolMap[c] ?? null;
+      if (n === null) {
+        const entry = table[c]?.[h.name];
+        if (entry?.kind === "builtin") n = entry.native;
+      }
+      if (n) mapped.push(n);
+    }
+    if (!h.tools.includeIsStrictAllowlist) {
+      // claude's include flag pre-approves without restricting, so an exact allowlist renders as the deny complement
       const known = h.tools.builtins.map((t) => t.name);
       const excluded = known.filter((n) => !mapped.includes(n));
-      const tokens: string[] = [h.tools.includeFlag!, [...mapped, ...unmapped].join(",")];
-      tokens.push(h.tools.excludeFlag!, excluded.join(","));
-      return { tokens, unmapped };
+      const tokens: string[] = [h.tools.includeFlag!, [...mapped, ...passthrough].join(",")];
+      // only add exclude if needed? original pushed exclude even when? Keep original behavior: push excludeFlag excluded
+      if (excluded.length > 0 || passthrough.length > 0) {
+        tokens.push(h.tools.excludeFlag!, excluded.join(","));
+      } else {
+        // when all tools included, exclude nothing? but keep token? original pushed exclude always
+        tokens.push(h.tools.excludeFlag!, excluded.join(","));
+      }
+      return { tokens, passthrough };
     }
-    // pi: strict over built-ins, direct include; unmapped (extension/MCP)
-    // names ride along in the same list - pi governs them too.
-    return { tokens: [h.tools.includeFlag!, [...mapped, ...unmapped].join(",")], unmapped };
+    return {
+      tokens: [h.tools.includeFlag!, [...mapped, ...passthrough].join(",")],
+      passthrough,
+    };
   }
 
-  // exclude (D2): all descriptor-known names minus the excluded ones.
-  const names = validateNames(h, selection.exclude!);
-  const { mapped, unmapped: excludedUnmapped } = resolveNames(h, names);
-  if (excludedUnmapped.length > 0) {
-    // Excluding a name the descriptor does not know: permitted (it may be a
-    // runtime-registered tool), rendered natively where the harness's deny
-    // list can carry it; on claude only, since its include path consumes
-    // unknown names without effect (silent-acceptance hazard).
+  // exclude
+  const names = selection.exclude!;
+  const { canonical, passthrough: excludedPassthrough } = splitSelection(names);
+  for (const c of canonical) {
+    const has = toolMap[c] !== undefined || table[c]?.[h.name] !== undefined;
+    if (!has) {
+      throw new ArgvRefusalError({
+        issue: "unsupported-option",
+        harness: h.name,
+        option: "excludeTools",
+        supported: ["per-tool name lists"],
+        supportedBy: supportedByCanonical(set, c),
+        hint: `add toolMap.${h.name}.${c} to ~/.config/hcn/config.json or pass native:${c}`,
+      });
+    }
+  }
+  if (excludedPassthrough.length > 0) {
     if (!h.tools.includeIsStrictAllowlist) {
-      const tokens = [h.tools.excludeFlag!, [...mapped, ...excludedUnmapped].join(",")];
-      return { tokens, unmapped: excludedUnmapped };
+      const mapped = canonical.map(
+        (c) => toolMap[c] ?? (table[c]?.[h.name] as { native: string } | undefined)?.native ?? c,
+      );
+      const tokens = [h.tools.excludeFlag!, [...mapped, ...excludedPassthrough].join(",")];
+      return { tokens, passthrough: excludedPassthrough };
     }
-    // pi: a D2 exclude renders as a computed include (its native exclude
-    // subtracts from the default set, which cannot express "all minus X"
-    // when off-by-default tools are involved). An unknown excluded name
-    // cannot be complemented - refuse rather than silently grant it.
     throw new ArgvRefusalError({
       issue: "unknown-tool-name",
       harness: h.name,
       option: "excludeTools",
       supported: [`known tool names: ${h.tools.builtins.map((t) => t.name).join(", ")}`],
-      detail: `cannot exclude unknown name(s) ${excludedUnmapped.join(", ")}: the complement cannot be computed`,
+      detail: `cannot exclude unknown name(s) ${excludedPassthrough.join(", ")}: the complement cannot be computed`,
     });
   }
+  const mapped = canonical
+    .map((c) => toolMap[c] ?? (table[c]?.[h.name] as { native: string } | undefined)?.native ?? "")
+    .filter(Boolean);
   const known = h.tools.builtins.filter((t) => !mapped.includes(t.name));
   const kept = known.map((t) => t.name);
   if (!h.tools.includeIsStrictAllowlist) {
-    // claude: deny list IS the complement expression.
-    return { tokens: [h.tools.excludeFlag!, mapped.join(",")], unmapped: [] };
+    return { tokens: [h.tools.excludeFlag!, mapped.join(",")], passthrough: [] };
   }
-  // pi: computed include over every known name minus the excluded.
-  return { tokens: [h.tools.includeFlag!, kept.join(",")], unmapped: [] };
+  return { tokens: [h.tools.includeFlag!, kept.join(",")], passthrough: [] };
 };

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)}`,
+      });
+    }
+  }
+};