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

package/src/interpretation/hints.ts

@@ -0,0 +1,99 @@
+/**
+ * Curated refusal hints (D8), confirmed in review 2026-08-18
+ * (test/fixtures/phase0/hints-confirmed.md is the durable record). A hint
+ * is the nearest-alternative control for the CURRENT harness, shown before
+ * the cross-harness support list so a scanning caller meets the
+ * stay-on-harness suggestion first. Wording is locked verbatim; unit tests
+ * pin every string.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import type { RefusalOption } from "./refusal.js";
+
+const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFreezeSafe({
+  claude: {
+    sandbox:
+      "claude has no sandbox modes; approximate with a per-tool allowlist (--tools Read,Bash) or --disallowedTools to keep tools out, and run untrusted work in a disposable directory or container",
+    write:
+      "claude has no write toggle; keep the Write tool out with --tools that omits it, or --disallowedTools Write for the deny-complement spelling",
+    shell:
+      "claude has no shell toggle; disallow the Bash tool (--tools without Bash, or --disallowedTools Bash) and note Monitor can still run commands in headless runs",
+    maxSteps:
+      "claude has no step cap flag; bound the work in the prompt (task size, 'stop after N operations') or impose a wall-clock timeout at the caller",
+    provider:
+      "claude routes models through Anthropic only (Bedrock/Vertex via settings); use --model to pick within it - there is no separate provider selector",
+    "discovery.tools":
+      "claude has no tools-discovery toggle (tools are always compiled in); shape the tool set with --tools/--disallowedTools instead",
+    "discovery.instructionFiles":
+      "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: {
+    write:
+      "codex has no write toggle; use --sandbox read-only (config: sandbox_mode) so shell commands cannot write either",
+    shell:
+      "codex has no shell toggle; disable the shell tool via config (-c features.shell_tool=false) or use --sandbox read-only",
+    maxSteps:
+      "codex has no step cap flag; bound via sandbox policy and a caller-side timeout, or prompt-level limits",
+    provider:
+      "codex routes models through OpenAI (or --oss for local); use --model to pick within it - there is no separate provider selector",
+    "discovery.tools":
+      "codex has no tools-discovery toggle; disable tool classes via config keys (features.shell_tool, web_search) instead",
+    "discovery.instructionFiles":
+      "codex always loads AGENTS.md hierarchy; no per-call toggle exists - keep the files out of the tree or work from a directory without them",
+    "discovery.extensions":
+      "codex loads MCP servers and plugins from config; disable per-server with -c or codex mcp remove rather than a call-time toggle",
+    "discovery.skills":
+      "codex discovers skills from its skills directory; no call-time toggle - remove or move the skill files instead",
+  },
+  pi: {
+    sandbox:
+      "pi has no sandbox dimension; approximate with a minimal tool grant (--tools read,grep,find,ls) so the run cannot write or execute, or sandbox the process yourself (container, VM)",
+    write:
+      "pi has no write toggle; grant without the write tool (--tools read,bash,edit) or use --exclude-tools write",
+    shell:
+      "pi has no shell toggle; grant without the bash tool (--tools read,edit,write) or use --exclude-tools bash",
+    maxSteps:
+      "pi has no step cap flag; bound the work in the prompt or impose a wall-clock timeout at the caller",
+  },
+  muse: {
+    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:
+      "muse routes models through its own API; use --model to pick within it - there is no separate provider selector",
+    "discovery.tools":
+      "muse has no tools-discovery toggle; gate execution with --disable-write/--disable-shell/--disable-web-tools",
+    "discovery.instructionFiles":
+      "muse loads rules per workspace trust; --no-foreign-personal-context excludes foreign personal rules, and withholding --trust-workspace keeps workspace rules unloaded",
+    "discovery.skills":
+      "muse scopes skills by trust like rules; --no-foreign-personal-context drops foreign skills and untrusted workspaces stay unloaded - there is no unconditional skills-off switch",
+  },
+});
+
+/** deepFreeze without importing the descriptor's (which carries extra
+ * machinery); structure is plain JSON so Object.freeze all the way down. */
+function deepFreezeSafe<T>(value: T): T {
+  if (typeof value === "object" && value !== null) {
+    for (const v of Object.values(value as Record<string, unknown>)) deepFreezeSafe(v);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** The confirmed hint for a refused option on a harness, or undefined. */
+export const hintFor = (harness: string, option: RefusalOption): string | undefined =>
+  HINTS[harness]?.[option];
+
+/** All hints - for the unit test that pins every string against the
+ * evidence file's count. */
+export const allHints = (): ReadonlyArray<{ harness: string; option: string; text: string }> => {
+  const out: { harness: string; option: string; text: string }[] = [];
+  for (const [harness, table] of Object.entries(HINTS)) {
+    for (const [option, text] of Object.entries(table)) out.push({ harness, option, text });
+  }
+  return out;
+};
+
+/** Convenience for raise sites that already hold the descriptor. */
+export const hintForDescriptor = (
+  h: HarnessDescriptor,
+  option: RefusalOption,
+): string | undefined => hintFor(h.name, option);

package/src/interpretation/refusal.ts

@@ -17,19 +17,33 @@ 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"
+  | "skills"
+  | "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 +80,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 +101,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 +140,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,214 @@
+/**
+ * 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,
+  write: () => true,
+  shell: () => true,
+  tools: (h) => h.tools.includeFlag !== null || h.tools.excludeFlag !== null,
+};
+
+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;
+    }
+    // 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
+    // dormant built-ins (pi), it becomes the enabling include list.
+    if (key === "tools" && value === "all-known") {
+      const enabled = h.tools.builtins.filter((t) => t.defaultEnabled).length;
+      const all = h.tools.builtins.length;
+      if (enabled === all) {
+        provenance.push({ key, value: "all known (already default)", tier: "profile" });
+        continue;
+      }
+      const expanded = h.tools.builtins.map((t) => t.name);
+      resolved[key] = expanded;
+      provenance.push({ key, value: expanded, tier: "profile" });
+      continue;
+    }
+    // Dimensions whose value reduces to "emit nothing" (autonomy false,
+    // discovery all-on, write/shell true) 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)) ||
+      ((key === "write" || key === "shell") && value === true)
+    ) {
+      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/skills-selection.ts

@@ -0,0 +1,73 @@
+/**
+ * Caller-directed skills allowlist rendering (issue #38). The delegating
+ * agent picks the subset from its own registry; this module turns the
+ * resolved paths into per-harness argv tokens.
+ *
+ * - pi: `-ns` (discovery off) + one `--skill <path>` per entry - the
+ *   allowlist is exact: only the caller's picks load.
+ * - claude: no per-skill load flag; the registry is already present via
+ *   the personal skills dir, so the allowlist renders as the complement
+ *   OFF - `--settings '{"skillOverrides":{"<name>":"off",...}}'` for every
+ *   known skill except the picks. Known set comes from the caller's root
+ *   listing (same source that resolved the names).
+ * - codex/muse: refuse (structural) with the standard hint shape.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { ArgvRefusalError } from "./refusal.js";
+
+export const basenameOf = (p: string): string => {
+  const i = p.lastIndexOf("/");
+  return i === -1 ? p : p.slice(i + 1);
+};
+
+export const renderSkillsSelection = (
+  h: HarnessDescriptor,
+  skills: readonly string[],
+): readonly string[] => {
+  if (skills.length === 0) return [];
+
+  if (h.skills === null) {
+    throw new ArgvRefusalError({
+      issue: "unsupported-option",
+      harness: h.name,
+      option: "skills",
+      supported: ["caller-directed skill sets"],
+      supportedBy: [
+        { harness: "pi", spelling: "--skill" },
+        { harness: "claude", spelling: "skillOverrides" },
+      ],
+      hint:
+        h.name === "codex"
+          ? "codex discovers skills from its own directory with no call-time surface - stage the skills into $CODEX_HOME/skills or pass their content in the prompt"
+          : "muse scopes skills by workspace trust with no per-skill surface - include the skill content in the prompt or use --trust-workspace for the whole registry",
+    });
+  }
+
+  if (h.skills.loadFlag !== null) {
+    // pi: discovery off so ONLY the picks load.
+    const tokens: string[] = ["-ns"];
+    for (const path of skills) tokens.push(h.skills.loadFlag, path);
+    return tokens;
+  }
+
+  // claude: complement-off via settings JSON. Names are the skill dir
+  // basenames; unknown names in knownSkills would be turned off
+  // pointlessly, so the caller passes exactly the known set.
+  return [];
+};
+
+/** The claude complement form, given the full known registry: every known
+ * name except the picks gets "off". Exported for the CLI layer, which owns
+ * the registry listing (an fs read - never in interpretation). */
+export const claudeSkillOverridesArg = (
+  knownSkills: readonly string[],
+  pickedPaths: readonly string[],
+): string[] => {
+  const picks = new Set(pickedPaths.map(basenameOf));
+  const offs: Record<string, string> = {};
+  for (const name of knownSkills) {
+    if (!picks.has(name)) offs[name] = "off";
+  }
+  const json = JSON.stringify({ skillOverrides: offs });
+  return ["--settings", json];
+};

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;
+};