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

package/src/interpretation/refusal.ts

@@ -17,19 +17,32 @@ export const REFUSAL_ISSUES = deepFreeze([
   "unknown-model",
   "invalid-env",
   "invalid-tool-grant",
+  "unknown-tool-name",
+  "mutually-exclusive-options",
   "prompt-flag-injection",
   "no-autonomy-mode",
   "no-session-mode",
 ] as const);
 export type RefusalIssue = (typeof REFUSAL_ISSUES)[number];
 
+/** The option a refusal names: turn-option spec keys (descriptor tables)
+ * plus the tool-list dimensions and autonomy, which render via dedicated
+ * descriptor fields rather than a spec table. Kept closed so consumers can
+ * branch on it without a default arm. */
+export type RefusalOption =
+  | TurnOptionKey
+  | "tools"
+  | "excludeTools"
+  | "autonomy"
+  | `discovery.${string}`;
+
 /** One helper builds the message from the structured fields so message and
  * fields cannot drift. Every message names an alternative, not only a
  * negation, so an agent can pivot without reading the descriptor. */
 export const buildRefusalMessage = (
   issue: RefusalIssue,
   harness: HarnessName,
-  option?: TurnOptionKey,
+  option?: RefusalOption,
   facet?: DiscoveryFacet,
   supported: readonly string[] = [],
   detail?: string,
@@ -66,6 +79,10 @@ export const buildRefusalMessage = (
       return `invalid env key or value for ${harness}${detailSuffix}; ${supportedStr} - keys must match ^[A-Za-z_][A-Za-z0-9_]*$ and contain no NUL`;
     case "invalid-tool-grant":
       return `tool grant for ${harness} contains an empty entry or a comma; a blank tool flag value grants nothing detectable, and a comma inside one name silently splits the grant; ${supportedStr} - provide comma-free, non-empty tool names as separate entries`;
+    case "unknown-tool-name":
+      return `${harness} cannot compute a tool complement around an unknown name${detailSuffix}; ${supportedStr} - exclude only curated names, or pass the unknown name through an include list instead`;
+    case "mutually-exclusive-options":
+      return `${harness} cannot combine${optionPart}${detailSuffix}; ${supportedStr} - pass exactly one of them`;
     case "prompt-flag-injection":
       return `positional prompt may not start with '-'; it would be parsed as a flag by ${harness}${detailSuffix}; ${supportedStr} - remove leading '-' or prefix with a space`;
     case "no-autonomy-mode":
@@ -83,15 +100,25 @@ export const buildRefusalMessage = (
 export class ArgvRefusalError extends Error {
   readonly issue: RefusalIssue;
   readonly harness: HarnessName;
-  readonly option?: TurnOptionKey;
+  readonly option?: RefusalOption;
   readonly facet?: DiscoveryFacet;
   readonly supported: readonly string[];
+  /** D7: which harnesses DO express the refused option, native spellings
+   * included. Derived by the raise site from descriptors - absent when the
+   * refusing layer has no descriptor set in scope. */
+  readonly supportedBy?: ReadonlyArray<{ harness: string; spelling: string }>;
+  /** D8: nearest-alternative suggestion for the CURRENT harness - keeps a
+   * scanning agent on its chosen harness instead of switching. Curatorial
+   * data set at the raise site; absent when no hint exists. */
+  readonly hint?: string;
   constructor(args: {
     readonly issue: RefusalIssue;
     readonly harness: HarnessName;
-    readonly option?: TurnOptionKey;
+    readonly option?: RefusalOption;
     readonly facet?: DiscoveryFacet;
     readonly supported?: readonly string[];
+    readonly supportedBy?: ReadonlyArray<{ harness: string; spelling: string }>;
+    readonly hint?: string;
     readonly detail?: string;
     readonly message?: string;
   }) {
@@ -112,5 +139,7 @@ export class ArgvRefusalError extends Error {
     this.option = args.option;
     this.facet = args.facet;
     this.supported = args.supported ?? [];
+    this.supportedBy = args.supportedBy;
+    this.hint = args.hint;
   }
 }

package/src/interpretation/resolve-options.ts

@@ -0,0 +1,190 @@
+/**
+ * Option resolution: the precedence chain args > user config > built-in
+ * profile, plus provenance. Pure - the config FILE is read by the CLI layer
+ * and passed in as data; this layer only decides what wins.
+ *
+ * Launch-only: callers apply resolved options on launch, never resume (a
+ * resumed session keeps its session's settings - same rule the codex
+ * sandbox default already follows).
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { DEFAULT_TURN_PROFILE, type ProfileKey } from "../knowledge/profile.js";
+import type { TurnOptions } from "./argv.js";
+
+export type ProvenanceTier = "arg" | "project-config" | "user-config" | "profile" | "harness";
+
+export interface ProvenanceEntry {
+  readonly key: string;
+  readonly value: unknown;
+  readonly tier: ProvenanceTier;
+}
+
+/** D5: the project floor caps arg grants; exceeding it refuses naming both
+ * sets. Structured-first: fields, not prose parsing. */
+export class FloorExceededError extends Error {
+  readonly harness: string;
+  readonly excess: readonly string[];
+  readonly floor: readonly string[];
+  constructor(harness: string, excess: readonly string[], floor: readonly string[]) {
+    super(
+      `tool grant exceeds the project floor: ${JSON.stringify(excess)} not in floor ${JSON.stringify(floor)} - request a grant within the floor or raise the floor in the project config`,
+    );
+    this.name = "FloorExceededError";
+    this.harness = harness;
+    this.excess = excess;
+    this.floor = floor;
+  }
+}
+
+export interface ResolvedOptions {
+  readonly options: TurnOptions;
+  readonly provenance: readonly ProvenanceEntry[];
+  /** Profile dimensions this harness cannot express (skip-and-report,
+   * never refuse): rendered as divergence, not failure. */
+  readonly unrenderable: readonly string[];
+}
+
+/** Expressibility per profile dimension. Dimensions whose "on" state is
+ * the harness's own default (discovery all-on) or whose "off" state emits
+ * nothing (autonomy false) are expressible EVERYWHERE - the profile value
+ * resolves to "emit nothing," which every harness can do. Divergence is
+ * reserved for dimensions that would emit a flag the harness lacks. */
+const EXPRESSIBLE: Readonly<Record<ProfileKey, (h: HarnessDescriptor) => boolean>> = {
+  effort: (h) => h.turnOptions.effort !== undefined,
+  sandbox: (h) => h.turnOptions.sandbox !== undefined,
+  discovery: () => true,
+  autonomy: () => true,
+};
+
+export interface ConfigTiers {
+  /** ~/.config/hcn/config.json (XDG) - machine-wide defaults. */
+  readonly user?: Readonly<Partial<TurnOptions>>;
+  /** <git-root>/.hcn/config.json - auto-discovered (ratified A), the ALL-
+   * OFF tier; its `tools` key is both the default grant and the FLOOR: an
+   * arg grant exceeding it refuses, naming both sets (D5). */
+  readonly project?: Readonly<Partial<TurnOptions>>;
+}
+
+/** Merge semantics (gap 1, resolved): config keys are scalars and lists in
+ * schema v1 - there is nothing to deep-merge INTO - so precedence is whole-
+ * key replacement: arg > project > user > profile. A future nested key
+ * (per-harness sections) ships with schema v2 and its own merge rule. */
+const effectiveConfig = (tiers: ConfigTiers): Readonly<Partial<TurnOptions>> => ({
+  ...(tiers.user ?? {}),
+  ...(tiers.project ?? {}),
+});
+
+/** Resolve the effective options for a LAUNCH. `args` is what the caller
+ * passed explicitly (highest tier); `userConfig` the parsed config file;
+ * the profile is the floor. Keys absent everywhere defer to the harness
+ * and are reported with tier "harness" only when something (config or
+ * profile) attempted them - a truly untouched dimension is nobody's
+ * business and appears in provenance as tier "harness" with no value. */
+/** A discovery value emits nothing when every facet is true (on). */
+const emitsNothing = (value: unknown): boolean =>
+  typeof value === "object" &&
+  value !== null &&
+  Object.values(value as Record<string, unknown>).every((v) => v === true);
+
+export const resolveEffectiveOptions = (
+  h: HarnessDescriptor,
+  args: TurnOptions,
+  tiers: ConfigTiers = {},
+): ResolvedOptions => {
+  const provenance: ProvenanceEntry[] = [];
+  const unrenderable: string[] = [];
+  const config = effectiveConfig(tiers);
+  const sourceTier = (key: string): ProvenanceTier | undefined => {
+    if (tiers.project?.[key as keyof TurnOptions] !== undefined) return "project-config";
+    if (tiers.user?.[key as keyof TurnOptions] !== undefined) return "user-config";
+    return undefined;
+  };
+
+  // D5 toolset expansion: a bare --tools name matching a configured
+  // toolset resolves to its list BEFORE the floor check, so a named set
+  // within the floor passes and one exceeding it refuses naming the set's
+  // members. Project toolsets win name collisions over user toolsets.
+  const toolsets = {
+    ...((tiers.user as { toolsets?: Record<string, string[]> } | undefined)?.toolsets ?? {}),
+    ...((tiers.project as { toolsets?: Record<string, string[]> } | undefined)?.toolsets ?? {}),
+  };
+  let effectiveArgs = args;
+  if (
+    args.tools !== undefined &&
+    args.tools.length === 1 &&
+    toolsets[args.tools[0] as string] !== undefined
+  ) {
+    effectiveArgs = { ...args, tools: toolsets[args.tools[0] as string] };
+    provenance.push({
+      key: "tools",
+      value: effectiveArgs.tools,
+      tier: "arg",
+    });
+  }
+  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.
+  const floor = tiers.project?.tools;
+  if (floor !== undefined && effectiveArgs.tools !== undefined) {
+    const floorSet = new Set(floor);
+    const excess = effectiveArgs.tools.filter((t) => !floorSet.has(t));
+    if (excess.length > 0) {
+      throw new FloorExceededError(h.name, excess, [...floor]);
+    }
+  }
+
+  // Profile is the floor: apply only where nothing above it set the key.
+  for (const [key, value] of Object.entries(DEFAULT_TURN_PROFILE)) {
+    const argsSet = effectiveArgs[key as keyof TurnOptions] !== undefined;
+    const tier = sourceTier(key);
+    if (argsSet) {
+      provenance.push({ key, value: effectiveArgs[key as keyof TurnOptions], tier: "arg" });
+      continue;
+    }
+    if (tier !== undefined) {
+      provenance.push({ key, value: config[key as keyof TurnOptions], tier });
+      resolved[key] = config[key as keyof TurnOptions];
+      continue;
+    }
+    const expressible = EXPRESSIBLE[key as ProfileKey]?.(h) ?? false;
+    if (!expressible) {
+      // Skip-and-report: a profile default this harness cannot express is
+      // reported divergence, never a refusal and never silence.
+      unrenderable.push(key);
+      provenance.push({ key, value, tier: "harness" });
+      continue;
+    }
+    // Dimensions whose value reduces to "emit nothing" (autonomy false,
+    // discovery all-on) stay ABSENT from the resolved options - the
+    // harness's default already satisfies the profile, and emitting
+    // explicit on-flags would change resume grammar and add breakage
+    // surface for no semantic gain. Provenance still records the tier.
+    if ((key === "autonomy" && value === false) || (key === "discovery" && emitsNothing(value))) {
+      provenance.push({ key, value, tier: "profile" });
+      continue;
+    }
+    resolved[key] = value;
+    provenance.push({ key, value, tier: "profile" });
+  }
+
+  // Config keys outside the profile surface pass through at their own tier
+  // (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 in DEFAULT_TURN_PROFILE) continue;
+    if (effectiveArgs[key as keyof TurnOptions] !== undefined) {
+      provenance.push({ key, value: effectiveArgs[key as keyof TurnOptions], tier: "arg" });
+      continue;
+    }
+    resolved[key] = value;
+    const tier = sourceTier(key) ?? "user-config";
+    provenance.push({ key, value, tier });
+  }
+
+  return {
+    options: resolved as unknown as TurnOptions,
+    provenance,
+    unrenderable,
+  };
+};

package/src/interpretation/support.ts

@@ -0,0 +1,119 @@
+/**
+ * Cross-harness support derivation: pure functions that answer "which
+ * harnesses express this option, and under what native spelling" from the
+ * descriptor set. Phase 3 (D7): refusal diagnostics derive support lists at
+ * runtime instead of hardcoding them, so a descriptor edit can never leave
+ * a refusal message stale. The autonomy refusal in argv.ts was the
+ * counter-pattern - a hardcoded flag array that drifts on descriptor
+ * change.
+ *
+ * Interpretation-layer pure function; takes the descriptor set as an
+ * argument rather than importing the defaults, so override sets work.
+ */
+
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import type { DescriptorSet } from "../knowledge/overrides.js";
+import type { RefusalOption } from "./refusal.js";
+
+export interface SupportEntry {
+  readonly harness: string;
+  /** The native spelling a caller would use directly on that harness. */
+  readonly spelling: string;
+}
+
+const spellingOf = (h: HarnessDescriptor, option: RefusalOption): string | null => {
+  switch (option) {
+    case "tools":
+      return h.tools.includeFlag;
+    case "excludeTools":
+      return h.tools.excludeFlag;
+    case "autonomy":
+      return h.autonomy?.flag ?? null;
+    case "effort":
+    case "sandbox":
+    case "provider":
+    case "write":
+    case "shell":
+    case "maxSteps":
+    case "discovery": {
+      const spec = h.turnOptions[option];
+      if (spec === undefined) return null;
+      const rawRender =
+        spec.kind === "discovery"
+          ? (
+              Object.values(spec.facets)[0] as
+                | { render?: { flag?: string; flags?: string[] } }
+                | undefined
+            )?.render
+          : (spec as { render?: { flag?: string; flags?: string[] } }).render;
+      if (rawRender === undefined) return null;
+      // flag-value/config-kv carry `flag`; flag-list carries `flags` - the
+      // first entry is the spelling a caller would type.
+      return rawRender.flag ?? rawRender.flags?.[0] ?? null;
+    }
+    default:
+      return null;
+  }
+};
+
+/** Every harness in the set that can express `option`, with its native
+ * spelling. Ordered by the set's insertion order (defaults: claude, codex,
+ * pi, muse) so output is stable across calls. */
+export const supportedBy = (set: DescriptorSet, option: RefusalOption): readonly SupportEntry[] => {
+  const out: SupportEntry[] = [];
+  for (const h of Object.values(set)) {
+    if (h === undefined) continue;
+    const spelling = spellingOf(h, option);
+    if (spelling !== null) out.push({ harness: h.name, 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
+ * knows - those keep the plain unknown-flag error. */
+export const recognizeNativeSpelling = (
+  set: DescriptorSet,
+  flag: string,
+): { readonly option: RefusalOption; readonly entries: readonly SupportEntry[] } | null => {
+  const normalized = flag.toLowerCase();
+  const candidates: RefusalOption[] = [
+    "tools",
+    "excludeTools",
+    "autonomy",
+    "effort",
+    "sandbox",
+    "provider",
+    "write",
+    "shell",
+    "maxSteps",
+  ];
+  for (const option of candidates) {
+    const entries = supportedBy(set, option).filter((e) => e.spelling.toLowerCase() === normalized);
+    if (entries.length > 0) return { option, entries };
+  }
+  // Discovery facets: single-dash spellings (pi -nt/-nc/-ne/-ns) and
+  // claude's --setting-sources. Facet spellings map to the facet name so
+  // the redirect can name the normalized spelling.
+  const FACET_KEYS = ["tools", "instructionFiles", "extensions", "skills"] as const;
+  for (const facet of FACET_KEYS) {
+    const entries: SupportEntry[] = [];
+    for (const h of Object.values(set)) {
+      if (h === undefined) continue;
+      const spec = h.turnOptions.discovery;
+      if (spec === undefined || spec.kind !== "discovery") continue;
+      const facetSpec = spec.facets[facet];
+      if (facetSpec === undefined) continue;
+      const render = facetSpec.render as { flag?: string; flags?: string[] };
+      const spelling = render.flag ?? render.flags?.[0];
+      if (spelling !== undefined && spelling.toLowerCase() === normalized) {
+        entries.push({ harness: h.name, spelling });
+      }
+    }
+    if (entries.length > 0) {
+      return { option: `discovery.${facet}` as RefusalOption, entries };
+    }
+  }
+  return null;
+};

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,43 @@ 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.
+  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,23 @@ 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.
+  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",
+  },
 });