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

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

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: [] };
 };