@dungle-scrubs/harness-cli-normalizer 0.6.0 → 0.6.1

package/src/interpretation/tool-selection.ts

@@ -1,5 +1,8 @@
 /**
- * Tool-selection rendering with canonical vocabulary.
+ * Tool-selection rendering with canonical vocabulary. The descriptor's
+ * denySemantics says which shape a harness has; the toolMap helpers in
+ * tool-vocabulary.ts own the counterpart and native-name rules (RFC-02
+ * changes 7 and 8) - nothing here restates them.
  */
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
@@ -10,19 +13,17 @@ import {
   allCanonicalNames,
   canonicalTable,
   hasCounterpart,
-  NATIVE_PREFIX,
   nativeFor,
   parseToolSelector,
-  READ_PRESET,
-  validateCanonicalList,
+  type ToolMap,
 } from "./tool-vocabulary.js";
-
-export const TOOL_SELECTOR = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,127}$/;
+import { CLEAN_SELECTOR } from "./vocabulary.js";
 
 export interface ToolSelection {
   readonly include?: readonly string[];
   readonly exclude?: readonly string[];
-  readonly toolMap?: Readonly<Record<string, string>>;
+  /** The merged toolMap, every harness; the renderer reads its own entry. */
+  readonly toolMap?: ToolMap;
 }
 
 export interface RenderedToolSelection {
@@ -39,11 +40,11 @@ const validateInnerName = (h: HarnessDescriptor, name: string, raw: readonly str
       detail: `tools=${JSON.stringify(raw)}`,
     });
   }
-  if (!TOOL_SELECTOR.test(name)) {
+  if (!CLEAN_SELECTOR.test(name)) {
     throw new ArgvRefusalError({
       issue: "invalid-tool-grant",
       harness: h.name,
-      supported: [`must match ${TOOL_SELECTOR.source}`],
+      supported: [`must match ${CLEAN_SELECTOR.source}`],
       detail: name,
     });
   }
@@ -62,30 +63,6 @@ const categoriesFor = (
   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 = (
   h: HarnessDescriptor,
   selection: ToolSelection,
@@ -106,10 +83,11 @@ export const renderToolSelection = (
 
   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 toolMap = selection.toolMap;
+  // Names this harness's own toolMap entry adds count as canonical here;
+  // another harness's entries do not make a name expressible on this one.
+  const own = toolMap?.[h.name];
+  const allCanonical = allCanonicalNames(set, own === undefined ? undefined : { [h.name]: own });
 
   const splitSelection = (
     names: readonly string[],
@@ -140,10 +118,31 @@ export const renderToolSelection = (
     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;
+  /** Refuse the first canonical this harness cannot express. */
+  const requireCounterparts = (
+    canonical: readonly string[],
+    option: "tools" | "excludeTools",
+    hint: (c: string) => string | undefined,
+  ): void => {
+    for (const c of canonical) {
+      if (hasCounterpart(table, c, h.name, toolMap)) continue;
+      throw new ArgvRefusalError({
+        issue: "unsupported-option",
+        harness: h.name,
+        option,
+        supported: ["per-tool name lists"],
+        supportedBy: supportedByCanonical(set, c),
+        hint: hint(c),
+      });
+    }
+  };
+
+  // The descriptor says how a deny lands (RFC-02 change 7): no lists at
+  // all (codex), a policy gate over category switches (muse), or removal
+  // from the name list (claude, pi). Nothing here re-derives that shape.
+  const semantics = h.tools.denySemantics;
 
-  if (isCodexShape) {
+  if (semantics === "no-lists") {
     throw new ArgvRefusalError({
       issue: "unsupported-option",
       harness: h.name,
@@ -155,25 +154,12 @@ export const renderToolSelection = (
         "nearest control on codex: category switches via config keys (features.shell_tool, web_search) or sandbox modes - see `hcn inspect codex`",
     });
   }
-  if (isCategoryShape) {
+  if (semantics === "policy-gate") {
     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"),
-          });
-        }
-      }
+      requireCounterparts(canonical, "excludeTools", () => hintFor(h.name, "excludeTools"));
       const cats = categoriesFor(h, canonical, table);
       const tokens: string[] = [];
       for (const cat of h.tools.categories) {
@@ -182,19 +168,7 @@ export const renderToolSelection = (
       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"),
-        });
-      }
-    }
+    requireCounterparts(canonical, "tools", () => 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 };
@@ -207,7 +181,14 @@ export const renderToolSelection = (
     return { tokens, passthrough };
   }
 
-  // From here: h has list flags (claude, pi)
+  // From here: remove-from-set, the harness has name-list flags (claude, pi)
+  const toolMapHint = (c: string): string =>
+    `add toolMap.${h.name}.${c} to ~/.config/hcn/config.json or pass native:${c}`;
+  const nativeNames = (canonical: readonly string[]): string[] =>
+    canonical
+      .map((c) => nativeFor(table, c, h.name, toolMap))
+      .filter((n): n is string => n !== null);
+
   if (hasInclude) {
     const names = selection.include!;
     if (names.length === 0) {
@@ -224,41 +205,23 @@ export const renderToolSelection = (
       return { tokens: [h.tools.excludeFlag!, known.join(",")], passthrough: [] };
     }
     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: "unsupported-option",
-          harness: h.name,
-          option: "tools",
-          supported: ["per-tool name lists"],
-          supportedBy: supportedByCanonical(set, c),
-          hint: `add toolMap.${h.name}.${c} to ~/.config/hcn/config.json or pass native:${c}`,
-        });
-      }
-    }
-    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);
-    }
+    requireCounterparts(canonical, "tools", toolMapHint);
+    const mapped = nativeNames(canonical);
     if (!h.tools.includeIsStrictAllowlist) {
-      // claude's include flag pre-approves without restricting, so an exact allowlist renders as the deny complement
+      // claude's include flag pre-approves without restricting, so an exact
+      // allowlist renders as the deny complement - always, even when the
+      // complement is empty.
       const known = h.tools.builtins.map((t) => t.name);
       const excluded = known.filter((n) => !mapped.includes(n));
-      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 };
+      return {
+        tokens: [
+          h.tools.includeFlag!,
+          [...mapped, ...passthrough].join(","),
+          h.tools.excludeFlag!,
+          excluded.join(","),
+        ],
+        passthrough,
+      };
     }
     return {
       tokens: [h.tools.includeFlag!, [...mapped, ...passthrough].join(",")],
@@ -269,24 +232,10 @@ export const renderToolSelection = (
   // 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}`,
-      });
-    }
-  }
+  requireCounterparts(canonical, "excludeTools", toolMapHint);
+  const mapped = nativeNames(canonical);
   if (excludedPassthrough.length > 0) {
     if (!h.tools.includeIsStrictAllowlist) {
-      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 };
     }
@@ -298,11 +247,7 @@ export const renderToolSelection = (
       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);
+  const kept = h.tools.builtins.filter((t) => !mapped.includes(t.name)).map((t) => t.name);
   if (!h.tools.includeIsStrictAllowlist) {
     return { tokens: [h.tools.excludeFlag!, mapped.join(",")], passthrough: [] };
   }

package/src/interpretation/tool-vocabulary.ts

@@ -1,3 +1,13 @@
+/**
+ * The canonical tool vocabulary and the toolMap that extends it.
+ *
+ * One toolMap shape (RFC-02 change 8): a config file carries the raw
+ * shape, harness -> canonical -> native, and `mergeToolMaps` folds the
+ * tiers into the one shape everything downstream reads, harness ->
+ * canonical -> the native name plus the tier that set it. Tool selection
+ * and the access preset call `hasCounterpart` and `nativeFor` instead of
+ * restating them.
+ */
 import type { DescriptorSet } from "../knowledge/overrides.js";
 import { ArgvRefusalError } from "./refusal.js";
 
@@ -16,20 +26,27 @@ export const parseToolSelector = (raw: string): ParsedSelector =>
     ? { kind: "native", name: raw.slice(NATIVE_PREFIX.length) }
     : { kind: "canonical", name: raw };
 
-export type ToolMap = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** The raw shape a config file carries: harness -> canonical -> native. */
+export type ToolMapConfig = 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 }>>>
->;
+export interface ToolMapEntry {
+  readonly native: string;
+  readonly tier: ToolMapTier;
+}
+
+/** The one shape past the merge: harness -> canonical -> native plus the
+ * tier that set it. Carried on the turn options and read by every
+ * consumer. */
+export type ToolMap = Readonly<Record<string, Readonly<Record<string, ToolMapEntry>>>>;
 
 /** 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 }>> = {};
+  readonly user?: ToolMapConfig;
+  readonly project?: ToolMapConfig;
+}): ToolMap => {
+  const merged: Record<string, Record<string, ToolMapEntry>> = {};
   const harnesses = new Set<string>([
     ...Object.keys(tiers.user ?? {}),
     ...Object.keys(tiers.project ?? {}),
@@ -41,12 +58,14 @@ export const mergeToolMaps = (tiers: {
       ...Object.keys(userEntries),
       ...Object.keys(projectEntries),
     ]);
-    const perHarness: Record<string, { native: string; tier: ToolMapTier }> = {};
+    const perHarness: Record<string, ToolMapEntry> = {};
     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" };
+      const project = projectEntries[c];
+      const user = userEntries[c];
+      if (project !== undefined) {
+        perHarness[c] = { native: project, tier: "project-config" };
+      } else if (user !== undefined) {
+        perHarness[c] = { native: user, tier: "user-config" };
       }
     }
     if (Object.keys(perHarness).length > 0) {
@@ -99,65 +118,41 @@ export const canonicalTable = (set: DescriptorSet): CanonicalTable => {
   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[] => {
+/** Every canonical name: the descriptors' plus every name a toolMap adds. */
+export const allCanonicalNames = (set: DescriptorSet, toolMap?: ToolMap): readonly string[] => {
   const base = canonicalNames(set);
-  const extra = toolMap
-    ? Object.values(toolMap).flatMap((m) => Object.keys(m as Record<string, unknown>))
-    : [];
+  const extra = toolMap ? Object.values(toolMap).flatMap((m) => Object.keys(m)) : [];
   return [...new Set([...base, ...extra])].sort();
 };
 
+/** Whether `harnessName` can express `canonical`: through its toolMap
+ * entry, a built-in, or a category. */
 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;
-};
+  toolMap?: ToolMap,
+): boolean =>
+  toolMap?.[harnessName]?.[canonical] !== undefined ||
+  table[canonical]?.[harnessName] !== undefined;
 
+/** The native name `harnessName` lists `canonical` under: the toolMap
+ * entry wins, then the built-in; a category has no name-list spelling. */
 export const nativeFor = (
   table: CanonicalTable,
   canonical: string,
   harnessName: string,
-  toolMap?: MergedToolMap | ToolMap,
+  toolMap?: 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;
+  const mapped = toolMap?.[harnessName]?.[canonical];
+  if (mapped !== undefined) return mapped.native;
+  const entry = table[canonical]?.[harnessName];
+  return entry?.kind === "builtin" ? entry.native : null;
 };
 
 export const validateCanonicalList = (