@dungle-scrubs/harness-cli-normalizer 0.3.1 → 0.4.1

package/src/interpretation/tool-selection.ts

@@ -0,0 +1,161 @@
+/**
+ * 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.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
+import { ArgvRefusalError } from "./refusal.js";
+import { supportedBy } from "./support.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[];
+}
+
+export interface RenderedToolSelection {
+  readonly tokens: readonly string[];
+  readonly unmapped: 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,
+      });
+    }
+  }
+  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 = (
+  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);
+  }
+  return { mapped, unmapped };
+};
+
+export const renderToolSelection = (
+  h: HarnessDescriptor,
+  selection: ToolSelection,
+): RenderedToolSelection => {
+  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",
+      harness: h.name,
+      option: "tools",
+      supported: ["--tools (exact allowlist) or --exclude-tools (complement), never both"],
+      detail: "mutual exclusion",
+    });
+  }
+  if (!hasInclude && !hasExclude) return { tokens: [], unmapped: [] };
+
+  if (h.tools.includeFlag === null || h.tools.excludeFlag === null) {
+    const option = hasInclude ? "tools" : "excludeTools";
+    const by = supportedBy(defaultDescriptors(), option);
+    throw new ArgvRefusalError({
+      issue: "unsupported-option",
+      harness: h.name,
+      option,
+      supported: ["per-tool name lists"],
+      supportedBy: by,
+      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",
+    });
+  }
+
+  if (hasInclude) {
+    const names = validateNames(h, selection.include!);
+    const { mapped, unmapped } = resolveNames(h, names);
+    if (!h.tools.includeIsStrictAllowlist) {
+      // 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 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 };
+    }
+    // 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 };
+  }
+
+  // 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).
+    if (!h.tools.includeIsStrictAllowlist) {
+      const tokens = [h.tools.excludeFlag!, [...mapped, ...excludedUnmapped].join(",")];
+      return { tokens, unmapped: excludedUnmapped };
+    }
+    // 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`,
+    });
+  }
+  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: [] };
+  }
+  // pi: computed include over every known name minus the excluded.
+  return { tokens: [h.tools.includeFlag!, kept.join(",")], unmapped: [] };
+};

package/src/interpretation/turn-options.ts

@@ -12,6 +12,7 @@
 import type { HarnessDescriptor, OptionRender, SpecBase } from "../knowledge/descriptor.js";
 import { DISCOVERY_FACETS, resolveRender, TURN_OPTION_KEYS } from "../knowledge/descriptor.js";
 import type { DiscoveryOptions, TurnOptions } from "./argv.js";
+import { hintFor } from "./hints.js";
 import { ArgvRefusalError } from "./refusal.js";
 import { CLEAN_SELECTOR, resolveModel, validateEffort } from "./vocabulary.js";
 
@@ -62,6 +63,7 @@ export const renderTurnOptions = (
           option: "discovery",
           supported: Object.keys(h.turnOptions).length ? Object.keys(h.turnOptions) : ["(none)"],
           detail: String(requested[0]),
+          hint: hintFor(h.name, `discovery.${String(requested[0])}`),
         });
       }
       if (spec.kind !== "discovery") {
@@ -109,6 +111,7 @@ export const renderTurnOptions = (
               option: "discovery",
               facet,
               supported: supportedFacets.length ? supportedFacets : ["(none)"],
+              hint: hintFor(h.name, `discovery.${facet}`),
             });
           }
           continue;
@@ -199,6 +202,7 @@ export const renderTurnOptions = (
         option: key,
         supported: Object.keys(h.turnOptions).length ? Object.keys(h.turnOptions) : ["(none)"],
         detail: String(raw),
+        hint: hintFor(h.name, key),
       });
     }
 

package/src/knowledge/claude-code.ts

@@ -145,10 +145,44 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
           render: { kind: "flag-list", flags: ["--setting-sources", "project"] },
         },
         skills: {
+          // Phase 0 (claude-tool-interplay.md probe 4): --disable-slash-commands
+          // removes the Skill tool AND all skills listing - verified a full
+          // skills-off switch, not just command dispatch. --setting-sources
+          // project stays the extensions-facet spelling (settings scope).
           polarity: "disables",
-          render: { kind: "flag-list", flags: ["--setting-sources", "project"] },
+          render: { kind: "flag-list", flags: ["--disable-slash-commands"] },
         },
       },
     },
   },
+  // Phase 0 fixtures: claude-tool-interplay.md. include is a permission
+  // grant (Bash, Edit stay visible under --allowedTools Read); only the
+  // disallow flag reshapes the model-visible set. Both flags together
+  // compose, deny winning on overlap. Patterns (Bash(git *)) valid in both
+  // lists; unknown PATTERN spellings warn on stderr, unknown exact names
+  // are the silent-acceptance hazard the curated vocabulary guards.
+  skills: { loadFlag: null, overridesVia: "settings-skilloverrides" },
+  tools: {
+    includeFlag: "--allowedTools",
+    excludeFlag: "--disallowedTools",
+    includeIsStrictAllowlist: false,
+    composable: true,
+    builtins: [
+      { name: "Bash", defaultEnabled: true },
+      { name: "Edit", defaultEnabled: true },
+      { name: "Glob", defaultEnabled: true },
+      { name: "Grep", defaultEnabled: true },
+      { name: "Read", defaultEnabled: true },
+      { name: "Write", defaultEnabled: true },
+      { name: "WebFetch", defaultEnabled: true },
+      { name: "WebSearch", defaultEnabled: true },
+      { name: "Monitor", defaultEnabled: true },
+      { name: "Task", defaultEnabled: true },
+      { name: "Skill", defaultEnabled: true },
+      { name: "NotebookEdit", defaultEnabled: true },
+      { name: "LSP", defaultEnabled: true },
+    ],
+    categories: [],
+    denySemantics: "remove-from-set",
+  },
 });

package/src/knowledge/codex.ts

@@ -114,4 +114,24 @@ export const codexCli: HarnessDescriptor = deepFreeze({
       resumeRender: null,
     },
   },
+  // Phase 0 fixtures: codex-tool-surface.md. No name lists anywhere -
+  // not on the CLI, not in config.toml. Control is feature booleans
+  // (reachable per-call via -c key=value / --enable/--disable FEATURE),
+  // sandbox, and approval policy. MCP servers do have per-tool keys
+  // (mcp_servers.<id>.tools.<tool>) but built-ins do not.
+  skills: null,
+  tools: {
+    includeFlag: null,
+    excludeFlag: null,
+    includeIsStrictAllowlist: false,
+    composable: false,
+    builtins: [],
+    categories: [
+      { key: "shell", disableFlag: null, configKey: "features.shell_tool" },
+      { key: "exec", disableFlag: null, configKey: "features.unified_exec" },
+      { key: "web", disableFlag: null, configKey: "web_search" },
+      { key: "view-image", disableFlag: null, configKey: "tools.view_image" },
+    ],
+    denySemantics: "no-lists",
+  },
 });

package/src/knowledge/descriptor.ts

@@ -340,4 +340,43 @@ export interface HarnessDescriptor {
    * harness; a call passing them must refuse. Discovery is a table of
    * per-facet specs rather than a single flag. */
   readonly turnOptions: Readonly<Partial<Record<TurnOptionKey, TurnOptionSpec>>>;
+  /** Tool-selection surface, grounded in test/fixtures/phase0/ evidence.
+   * `includeFlag`/`excludeFlag` are the per-tool NAME-LIST flags (null when
+   * the harness has none - codex/muse). `includeIsStrictAllowlist` records
+   * the claude asymmetry: claude's include flag pre-approves without
+   * restricting the visible set, so an exact allowlist must render as a
+   * disallow-complement there; pi's include IS strict (over built-ins).
+   * `composable`: both flags legal at once (pi: exclude subtracts from
+   * include). `builtins`: curated names + default-enabled state - grep/find/
+   * ls ship off on pi, everything ships on elsewhere. `categories`:
+   * non-list switches (muse disable flags, codex config booleans).
+   * `denySemantics`: whether a deny removes the tool from the model-visible
+   * set (claude/pi), policy-gates execution while the tool stays listed
+   * (muse), or there are no lists to deny with (codex). Extension and MCP
+   * tools register at runtime and are NEVER enumerated here - name
+   * validation is a default, not a refusal authority (same stance as the
+   * pi model registry, D-008). */
+  /** Caller-directed skills allowlist surface (issue #38). pi: repeatable
+   * load flag. claude: per-name "off" overrides via settings JSON.
+   * codex/muse: null (structural gap - trust/config scoped only). */
+  readonly skills: {
+    readonly loadFlag: string | null;
+    readonly overridesVia: "settings-skilloverrides" | null;
+  } | null;
+  readonly tools: {
+    readonly includeFlag: string | null;
+    readonly excludeFlag: string | null;
+    readonly includeIsStrictAllowlist: boolean;
+    readonly composable: boolean;
+    readonly builtins: ReadonlyArray<{
+      readonly name: string;
+      readonly defaultEnabled: boolean;
+    }>;
+    readonly categories: ReadonlyArray<{
+      readonly key: "shell" | "write" | "web" | "exec" | "view-image";
+      readonly disableFlag: string | null;
+      readonly configKey: string | null;
+    }>;
+    readonly denySemantics: "remove-from-set" | "policy-gate" | "no-lists";
+  };
 }

package/src/knowledge/muse.ts

@@ -110,4 +110,24 @@ export const museCode: HarnessDescriptor = deepFreeze({
       render: { kind: "flag-value", flag: "--max-model-steps" },
     },
   },
+  // Phase 0 fixtures: muse-category-flags.md. No name lists; category
+  // switches are enforcement gates - tools stay listed in the catalog but
+  // calls are denied per session policy (unlike claude's set removal).
+  // Tool names follow muse.<name> (write_file, edit_file, bash, bash_input,
+  // add_memory, edit_memory, web_search). --disable-web-tools has no
+  // normalized turnOption yet - candidate for a web toggle or passthrough.
+  skills: null,
+  tools: {
+    includeFlag: null,
+    excludeFlag: null,
+    includeIsStrictAllowlist: false,
+    composable: false,
+    builtins: [],
+    categories: [
+      { key: "write", disableFlag: "--disable-write", configKey: null },
+      { key: "shell", disableFlag: "--disable-shell", configKey: null },
+      { key: "web", disableFlag: "--disable-web-tools", configKey: null },
+    ],
+    denySemantics: "policy-gate",
+  },
 });

package/src/knowledge/pi.ts

@@ -118,4 +118,26 @@ export const piCli: HarnessDescriptor = deepFreeze({
       },
     },
   },
+  // Phase 0 fixtures: pi-both-tool-flags.md. Both list flags legal at once;
+  // exclude subtracts from include. --tools is strict over BUILT-INS but
+  // does not strip MCP/extension registrations (additive over them);
+  // -nbt (built-ins only off) exists but has no normalized spelling yet.
+  skills: { loadFlag: "--skill", overridesVia: null },
+  tools: {
+    includeFlag: "--tools",
+    excludeFlag: "--exclude-tools",
+    includeIsStrictAllowlist: true,
+    composable: true,
+    builtins: [
+      { name: "read", defaultEnabled: true },
+      { name: "bash", defaultEnabled: true },
+      { name: "edit", defaultEnabled: true },
+      { name: "write", defaultEnabled: true },
+      { name: "grep", defaultEnabled: false },
+      { name: "find", defaultEnabled: false },
+      { name: "ls", defaultEnabled: false },
+    ],
+    categories: [],
+    denySemantics: "remove-from-set",
+  },
 });

package/src/knowledge/profile.ts

@@ -0,0 +1,53 @@
+/**
+ * The built-in default turn profile: hcn's curated defaults for a bare run,
+ * decided in review (2026-08-18) and applied LAUNCH-ONLY, before user config
+ * and args. Every entry here is a ratified dimension; unratified dimensions
+ * stay absent and defer to the harness.
+ *
+ * effort: "medium" - the only value present in all four effort ladders
+ * (claude/pi/muse/codex-per-model). Live probe on claude 2.1.233 showed the
+ * internal default is above medium and nondeterministic (599-1482 thinking
+ * tokens on identical tasks vs 436 at medium); pinning makes bare runs
+ * cheaper on claude, uniform everywhere, and knowable from the outside.
+ */
+import { deepFreeze } from "./descriptor.js";
+
+export const DEFAULT_TURN_PROFILE = deepFreeze({
+  effort: "medium",
+  // codex-only (the only harness with a sandbox dimension). Promotes the
+  // descriptor's implicit workspace-write default into the visible
+  // profile tier. On the other three the dimension is unrenderable and
+  // reports as divergence.
+  sandbox: "workspace-write",
+  // Ratified: discovery fully ON. The harnesses' bare runs already
+  // discover instruction files, skills, and extensions; the profile makes
+  // that a stated contract. The off-spellings exist per harness
+  // (-ns/-nc/-ne on pi, --setting-sources on claude) for callers who want
+  // less.
+  discovery: { tools: true, instructionFiles: true, extensions: true, skills: true },
+  // Ratified: autonomy OFF. No bare run is unattended; --autonomy or a
+  // config must say so deliberately.
+  autonomy: false,
+  // D9/D10, ratified round 2: write and shell ON - names current
+  // behavior (emit-nothing on claude/codex/pi; muse omits its disable
+  // flags). Completes the "what can a bare run do to the machine" row of
+  // provenance.
+  write: true,
+  shell: true,
+  // D13, ratified: equivalent-as-possible tool defaults. The marker
+  // expands per descriptor at resolve time - pi gains its dormant
+  // grep/find/ls; claude emits nothing (already everything); codex/muse
+  // report divergence (no list surface). Project floors narrow it by
+  // the normal precedence chain.
+  tools: "all-known",
+  // Model is PERMANENTLY out of profile scope (ratified round 2): no
+  // cross-harness model namespace exists, pi's registry is
+  // runtime-extensible and environment-dependent, and per-harness config
+  // already covers "claude on X, pi on Y". Do not add a model entry.
+  // timeout and maxSteps are likewise opt-in-only dimensions (D11/D12):
+  // no harness ships a wall-clock cap, one prompt expands into an
+  // unbounded turn loop, and a fixed default kills legitimate work. They
+  // live in args/config only, never here.
+} as const);
+
+export type ProfileKey = keyof typeof DEFAULT_TURN_PROFILE;

package/dist/index.d.ts

@@ -1,8 +0,0 @@
-/**
- * Public package surface. The three architectural layers remain available as
- * explicit subpath exports for consumers that want the narrowest dependency.
- */
-export * from "./execution/index.js";
-export * from "./interpretation/index.js";
-export * from "./knowledge/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,8 +0,0 @@
-/**
- * Public package surface. The three architectural layers remain available as
- * explicit subpath exports for consumers that want the narrowest dependency.
- */
-export * from "./execution/index.js";
-export * from "./interpretation/index.js";
-export * from "./knowledge/index.js";
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC"}

package/src/index.ts

@@ -1,7 +0,0 @@
-/**
- * Public package surface. The three architectural layers remain available as
- * explicit subpath exports for consumers that want the narrowest dependency.
- */
-export * from "./execution/index.js";
-export * from "./interpretation/index.js";
-export * from "./knowledge/index.js";