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

package/src/interpretation/resolve-options.ts

@@ -11,8 +11,10 @@ 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 { assertIsolationCombination, ISOLATION_OVERRIDES } from "./isolation.js";
+import type { QuestionMode } from "./question.js";
 import { ArgvRefusalError } from "./refusal.js";
-import type { ToolMap } from "./tool-vocabulary.js";
+import type { ToolMapConfig } from "./tool-vocabulary.js";
 import { allCanonicalNames, mergeToolMaps, validateCanonicalList } from "./tool-vocabulary.js";
 import { validateAccess } from "./vocabulary.js";
 
@@ -55,6 +57,7 @@ export interface ResolvedOptions {
  * 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>> = {
+  contextWindow: (h) => h.turnOptions.contextWindow !== undefined,
   effort: (h) => h.turnOptions.effort !== undefined,
   sandbox: (h) => h.turnOptions.sandbox !== undefined,
   discovery: () => true,
@@ -64,20 +67,71 @@ const EXPRESSIBLE: Readonly<Record<ProfileKey, (h: HarnessDescriptor) => boolean
   tools: (h) => h.tools.includeFlag !== null || h.tools.excludeFlag !== null,
 };
 
+/** What one parsed config file carries: the turn options it may set, plus
+ * the keys that are not turn options - named toolsets, the raw toolMap
+ * (harness -> canonical -> native, merged into the one ToolMap shape
+ * here), and the wall-clock timeout. */
+export type ConfigTier = Readonly<Omit<Partial<TurnOptions>, "toolMap">> & {
+  readonly toolMap?: ToolMapConfig;
+  readonly toolsets?: Readonly<Record<string, readonly string[]>>;
+  readonly timeout?: number;
+};
+
 export interface ConfigTiers {
   /** ~/.config/hcn/config.json (XDG) - machine-wide defaults. */
-  readonly user?: Readonly<Partial<TurnOptions>>;
+  readonly user?: ConfigTier;
   /** <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>>;
+  readonly project?: ConfigTier;
+}
+
+/** Where a resolved behaviour value came from; `default` is hcn's own. */
+export type BehaviorTier = "arg" | "project-config" | "user-config" | "default";
+
+/** The hcn-owned behaviour instructions a run resolves on every path,
+ * launch, resume, and session alike (RFC-02 change 6): question mode,
+ * which rides the prompt rather than the argv, and the wall-clock
+ * timeout hcn enforces itself. Neither is a turn option, so the
+ * launch-only turn-option resolver never sees them. */
+export interface ResolvedBehavior {
+  readonly questions: { readonly value: QuestionMode; readonly tier: BehaviorTier };
+  readonly timeoutSeconds: { readonly value: number | undefined; readonly tier: BehaviorTier };
 }
 
+/** Precedence arg > project > user > default, with the tier the
+ * provenance line prints. Timeout 0 is an explicit disable. */
+export const resolveBehavior = (
+  args: { readonly questions?: QuestionMode; readonly timeoutSeconds?: number },
+  tiers: ConfigTiers,
+): ResolvedBehavior => {
+  const pick = <T>(
+    arg: T | undefined,
+    project: T | undefined,
+    user: T | undefined,
+    fallback: T,
+  ): { readonly value: T; readonly tier: BehaviorTier } => {
+    if (arg !== undefined) return { value: arg, tier: "arg" };
+    if (project !== undefined) return { value: project, tier: "project-config" };
+    if (user !== undefined) return { value: user, tier: "user-config" };
+    return { value: fallback, tier: "default" };
+  };
+  return {
+    questions: pick(args.questions, tiers.project?.questions, tiers.user?.questions, "ask"),
+    timeoutSeconds: pick(
+      args.timeoutSeconds,
+      tiers.project?.timeout,
+      tiers.user?.timeout,
+      undefined,
+    ),
+  };
+};
+
 /** 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>> => ({
+const effectiveConfig = (tiers: ConfigTiers): ConfigTier => ({
   ...(tiers.user ?? {}),
   ...(tiers.project ?? {}),
 });
@@ -99,10 +153,17 @@ export const resolveEffectiveOptions = (
   args: TurnOptions,
   tiers: ConfigTiers = {},
 ): ResolvedOptions => {
+  assertIsolationCombination(h, args);
   const provenance: ProvenanceEntry[] = [];
+  if (args.isolation !== undefined)
+    provenance.push({ key: "isolation", value: args.isolation, tier: "arg" });
   const unrenderable: string[] = [];
-  const config = effectiveConfig(tiers);
+  const config = { ...effectiveConfig(tiers) };
+  if (args.isolation !== undefined) {
+    for (const key of ISOLATION_OVERRIDES) delete config[key];
+  }
   const sourceTier = (key: string): ProvenanceTier | undefined => {
+    if (config[key as keyof TurnOptions] === undefined) return 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;
@@ -112,9 +173,9 @@ export const resolveEffectiveOptions = (
   // 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 ?? {}),
+  const toolsets: Record<string, readonly string[]> = {
+    ...(tiers.user?.toolsets ?? {}),
+    ...(tiers.project?.toolsets ?? {}),
   };
   let effectiveArgs = args;
   if (
@@ -144,17 +205,22 @@ export const resolveEffectiveOptions = (
       });
     }
   }
-  // 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) {
+  // The access preset displaces the turn option its spec claims (codex:
+  // sandbox). An explicit value of that option alongside access refuses;
+  // the profile default yields silently in the profile loop below. Read
+  // from the descriptor, so no harness name appears here.
+  const accessSpec = h.turnOptions.access;
+  const claimed = accessSpec?.kind === "access" ? accessSpec.claims : undefined;
+  if (claimed !== undefined && resolved.access !== undefined) {
+    const hasExplicit =
+      effectiveArgs[claimed as keyof TurnOptions] !== undefined ||
+      sourceTier(claimed) !== undefined;
+    if (hasExplicit) {
       throw new ArgvRefusalError({
         issue: "mutually-exclusive-options",
         harness: h.name,
         option: "access",
-        supported: ["--access or --sandbox, not both on codex"],
+        supported: [`--access or --${claimed}, not both on ${h.name}`],
         detail: "mutual exclusion",
       });
     }
@@ -176,20 +242,14 @@ export const resolveEffectiveOptions = (
     }
   }
 
-  // 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 });
+  // toolMap merge per harness per canonical (project > user). The merged
+  // shape is the one shape past this point (RFC-02 change 8).
+  const mergedToolMap = mergeToolMaps({
+    user: tiers.user?.toolMap,
+    project: tiers.project?.toolMap,
+  });
   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;
+    resolved.toolMap = mergedToolMap;
     const harnessMap = mergedToolMap[h.name];
     if (harnessMap) {
       for (const [canonical, entry] of Object.entries(harnessMap)) {
@@ -214,7 +274,7 @@ export const resolveEffectiveOptions = (
   let allCanonical: readonly string[] | undefined;
   const getAllCanonical = (): readonly string[] => {
     if (allCanonical) return allCanonical;
-    allCanonical = allCanonicalNames(defaultDescriptors(), mergedToolMap as unknown as ToolMap);
+    allCanonical = allCanonicalNames(defaultDescriptors(), mergedToolMap);
     return allCanonical;
   };
   if (needsCanonical) {
@@ -236,6 +296,10 @@ export const resolveEffectiveOptions = (
 
   // Profile is the floor: apply only where nothing above it set the key.
   for (const [key, value] of Object.entries(DEFAULT_TURN_PROFILE)) {
+    if (args.isolation !== undefined && ISOLATION_OVERRIDES.some((owned) => owned === key)) {
+      provenance.push({ key, value: "disabled (tool-free isolation)", tier: "arg" });
+      continue;
+    }
     const argsSet = effectiveArgs[key as keyof TurnOptions] !== undefined;
     const tier = sourceTier(key);
     if (argsSet) {
@@ -263,8 +327,8 @@ export const resolveEffectiveOptions = (
       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) {
+    // The claimed option's profile default yields to a set access preset.
+    if (key === claimed && resolved.access !== undefined) {
       provenance.push({ key, value: `${String(value)} (access)`, tier: "harness" });
       continue;
     }
@@ -280,8 +344,9 @@ export const resolveEffectiveOptions = (
       // must not have the profile grant switch them back on (pi reads
       // --tools as an enabling allowlist). The tier that turned tools off
       // owns the skip.
-      const toolsOff = (o: Partial<TurnOptions> | undefined): boolean =>
-        o?.discovery?.tools === false;
+      const toolsOff = (
+        o: { readonly discovery?: TurnOptions["discovery"] } | undefined,
+      ): boolean => o?.discovery?.tools === false;
       const offTier: ProvenanceTier | undefined = toolsOff(effectiveArgs)
         ? "arg"
         : toolsOff(tiers.project)

package/src/interpretation/session-input.ts

@@ -1,6 +1,9 @@
 /**
  * Pure validation and encoding for descriptor-declared persistent-session
- * input. This module owns supported wire records, not process I/O.
+ * input, and the decoding of the session records the runner cannot read
+ * without harness knowledge. This module owns the wire records and their
+ * field names (ADR 0005, RFC-02 change 4); the execution layer branches
+ * on the closed kinds it returns and holds no field name of its own.
  */
 import type {
   HarnessDescriptor,
@@ -8,7 +11,7 @@ import type {
   SessionInputKind,
 } from "../knowledge/descriptor.js";
 import { SESSION_INPUT_KINDS } from "../knowledge/descriptor.js";
-import { asRecord } from "./shape.js";
+import { asRecord, readPath } from "./shape.js";
 
 export type SessionInputIssue = "missing-session-input-contract" | "unsupported-session-input-kind";
 
@@ -19,6 +22,11 @@ export class SessionInputRefusalError extends Error {
   }
 }
 
+/** The marker ids hcn stamps on the rpc commands it writes, so their
+ * responses cannot be confused with anything user-visible. */
+export const IDENTITY_PROBE_ID = "hcn-identity";
+export const SEND_ID = "hcn-send";
+
 const isSessionInputKind = (value: unknown): value is SessionInputKind =>
   SESSION_INPUT_KINDS.some((kind) => kind === value);
 
@@ -43,8 +51,83 @@ export const encodeSessionInput = (input: SessionInputContract, text: string): s
       })}\n`;
     case "pi-rpc-prompt":
       // Verified against pi 0.84.2 rpc (spike fixtures): a prompt command
-      // while idle; hcn never writes mid-run (it queues sends itself), so
-      // no streamingBehavior field is ever needed.
-      return `${JSON.stringify({ id: "hcn-send", type: "prompt", message: text })}\n`;
+      // while idle. hcn keeps no queue (ADR 0007) and writes a send when it
+      // arrives; pi refuses a bare prompt mid-run with success:false (spike
+      // fixture 05), so a mid-turn send would need streamingBehavior - a
+      // pending change, not expressed here yet.
+      return `${JSON.stringify({ id: SEND_ID, type: "prompt", message: text })}\n`;
+  }
+};
+
+/** The record the runner writes at spawn to learn the session id, or null
+ * when the harness announces identity on its stream unprompted. pi rpc is
+ * identity-silent at startup (spike fixtures); the response echoes the
+ * marker id. */
+export const encodeIdentityProbe = (h: HarnessDescriptor): string | null => {
+  const mode = h.sessionMode;
+  if (mode === null || mode.identityProbe === null) return null;
+  switch (mode.input.kind) {
+    case "pi-rpc-prompt":
+      return `${JSON.stringify({ id: IDENTITY_PROBE_ID, type: mode.identityProbe.command })}\n`;
+    case "claude-sdk-user-message":
+      return null;
+  }
+};
+
+/** What one parsed stdout record means to a session, as a closed kind. */
+export type SessionRecord =
+  /** The identity probe answered with the session id. */
+  | { readonly kind: "identity"; readonly sessionId: string }
+  /** The identity probe answered without an id - surfaced, never silent. */
+  | { readonly kind: "probe-failed"; readonly message: string }
+  /** An rpc command hcn wrote was refused by the harness. */
+  | { readonly kind: "command-failed"; readonly message: string }
+  /** Protocol bookkeeping with nothing to surface. */
+  | { readonly kind: "ignored" }
+  /** The record that delimits a turn, with the harness's own error flag. */
+  | { readonly kind: "turn-end"; readonly isError: boolean }
+  /** Anything else: content for the stream decoder. */
+  | { readonly kind: "content" };
+
+const matchesTurnEnd = (
+  record: Record<string, unknown>,
+  spec: Readonly<Record<string, string>>,
+): boolean => Object.entries(spec).every(([key, expected]) => record[key] === expected);
+
+export const decodeSessionRecord = (
+  h: HarnessDescriptor,
+  parsed: Record<string, unknown>,
+): SessionRecord => {
+  const mode = h.sessionMode;
+  if (mode === null) return { kind: "content" };
+  if (mode.input.kind === "pi-rpc-prompt" && parsed.type === "response") {
+    const probe = mode.identityProbe;
+    if (
+      probe !== null &&
+      parsed.id === IDENTITY_PROBE_ID &&
+      parsed.command === probe.command &&
+      parsed.success === true
+    ) {
+      const announced = readPath(parsed, probe.responseIdField);
+      return typeof announced === "string"
+        ? { kind: "identity", sessionId: announced }
+        : { kind: "probe-failed", message: "identity probe response carried no sessionId" };
+    }
+    // A failed command is a surfaced error, never a silent drop (spike:
+    // mid-stream prompts fail with success:false naming the remedy).
+    if (parsed.success === false) {
+      return {
+        kind: "command-failed",
+        message: `rpc command failed: ${JSON.stringify(parsed.command)} - ${JSON.stringify(parsed.error ?? "unknown error")}`,
+      };
+    }
+    return { kind: "ignored" };
+  }
+  if (matchesTurnEnd(parsed, mode.turnEnd)) {
+    // claude's result record carries is_error; pi's agent_settled has no
+    // error flag of its own.
+    const isError = mode.input.kind === "claude-sdk-user-message" && parsed.is_error === true;
+    return { kind: "turn-end", isError };
   }
+  return { kind: "content" };
 };

package/src/interpretation/shape.ts

@@ -7,6 +7,16 @@
 export const asRecord = (value: unknown): Record<string, unknown> | null =>
   typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
 
+export const readPath = (record: Record<string, unknown>, path: string): unknown => {
+  let cursor: unknown = record;
+  for (const segment of path.split(".")) {
+    const inner = asRecord(cursor);
+    if (inner === null) return undefined;
+    cursor = inner[segment];
+  }
+  return cursor;
+};
+
 /**
  * Split a command line into shell words: whitespace separates, single or
  * double quotes group (so a flag inside quoted prompt text stays part of

package/src/interpretation/skills-selection.ts

@@ -1,27 +1,36 @@
 /**
- * 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.
+ * Caller-directed skills allowlist rendering (issue #38), descriptor-driven
+ * (RFC-02 change 2). The delegating agent picks the subset from its own
+ * registry; the CLI supplies the resolved picks and the registry's known
+ * names; this module turns them into per-harness argv tokens by reading
+ * the descriptor's `skills` field:
  *
- * - 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: per-skill disable via config-kv array `-c
- *   skills.config=[{path="...", enabled=false}]` for every known skill
- *   except the picks (complement-off, same inversion as claude). Uses
- *   `path` selector rather than `name` because a skill's frontmatter
- *   `name` need not equal its directory basename, and `path` is exact.
- *   The path for skill <n> under root <root> is <root>/<n>/SKILL.md.
- *   No global `skills.enabled` switch exists. Requires the known set
- *   and the resolved picks (root derived from picks via dirname).
- * - muse: refuse (structural) with the standard hint shape.
+ * - a load flag (pi): the discovery.skills facet off, then one load per
+ *   pick - the allowlist is exact, only the caller's picks load.
+ * - overrides via settings (claude): no per-skill load flag; the registry
+ *   is already present, so the allowlist renders as the complement OFF -
+ *   `--settings '{"skillOverrides":{"<name>":"off",...}}'` for every known
+ *   skill except the picks.
+ * - overrides via a config array (codex): the complement OFF through
+ *   `-c skills.config=[{path="...", enabled=false}]`. Uses the `path`
+ *   selector because a skill's frontmatter `name` need not equal its
+ *   directory basename. The path for skill <n> under root <root> is
+ *   <root>/<n>/SKILL.md, the root taken from the picks (all share one).
+ * - null (muse): refuse, with the support list derived like every other
+ *   refusal's.
  */
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { tokensFor } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
 import { ArgvRefusalError } from "./refusal.js";
+import { supportedBy } from "./support.js";
+
+/** The skills turn option: the caller's resolved picks (absolute paths)
+ * and every skill name in the registry they came from. */
+export interface SkillsSelection {
+  readonly picks: readonly string[];
+  readonly known: readonly string[];
+}
 
 export const basenameOf = (p: string): string => {
   const i = p.lastIndexOf("/");
@@ -33,11 +42,32 @@ const dirnameOf = (p: string): string => {
   return i === -1 ? "" : p.slice(0, i);
 };
 
+/** The known names that are not picks, in registry order. */
+const complementOf = (skills: SkillsSelection): readonly string[] => {
+  const picks = new Set(skills.picks.map(basenameOf));
+  return skills.known.filter((name) => !picks.has(name));
+};
+
+const settingsOverrides = (skills: SkillsSelection): readonly string[] => {
+  const offs: Record<string, string> = {};
+  for (const name of complementOf(skills)) offs[name] = "off";
+  return ["--settings", JSON.stringify({ skillOverrides: offs })];
+};
+
+const configSkillsArray = (skills: SkillsSelection): readonly string[] => {
+  const root = skills.picks.length > 0 ? dirnameOf(skills.picks[0] as string) : "";
+  const entries = complementOf(skills).map((name) => {
+    const path = root ? `${root}/${name}/SKILL.md` : `${name}/SKILL.md`;
+    return `{path=${JSON.stringify(path)}, enabled=false}`;
+  });
+  return entries.length === 0 ? [] : ["-c", `skills.config=[${entries.join(", ")}]`];
+};
+
 export const renderSkillsSelection = (
   h: HarnessDescriptor,
-  skills: readonly string[],
+  skills: SkillsSelection,
 ): readonly string[] => {
-  if (skills.length === 0) return [];
+  if (skills.picks.length === 0) return [];
 
   if (h.skills === null) {
     throw new ArgvRefusalError({
@@ -45,67 +75,33 @@ export const renderSkillsSelection = (
       harness: h.name,
       option: "skills",
       supported: ["caller-directed skill sets"],
-      supportedBy: [
-        { harness: "pi", spelling: "--skill" },
-        { harness: "claude", spelling: "skillOverrides" },
-        { harness: "codex", spelling: "-c skills.config" },
-      ],
+      supportedBy: supportedBy(defaultDescriptors(), "skills"),
       hint: "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);
+    // Discovery off so ONLY the picks load; the off spelling is the
+    // descriptor's own discovery.skills facet render.
+    const facet =
+      h.turnOptions.discovery?.kind === "discovery"
+        ? h.turnOptions.discovery.facets.skills
+        : undefined;
+    const tokens: string[] = facet === undefined ? [] : [...tokensFor(facet.render)];
+    for (const path of skills.picks) tokens.push(h.skills.loadFlag, path);
     return tokens;
   }
 
-  // claude and codex: complement-off via CLI layer (settings JSON / config
-  // array). The descriptor-level render returns [] and tokens append in
-  // stream-turn / CLI.
-  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];
-};
-
-/** Codex complement form: every known skill except the picks gets
- * `{path="<root>/<name>/SKILL.md>", enabled=false}` via `-c
- * skills.config=[...]`. Uses `path` (exact) over `name` because
- * frontmatter name may diverge from directory basename. Root is derived
- * from the picks' dirname (all picks share the same root); if picks is
- * empty the complement cannot be rooted and we return [] (caller picks
- * nothing - no integration point needs this, and the CLI layer never
- * calls with empty picks). Empty complement returns [] (no flag). */
-export const codexSkillConfigArg = (
-  knownSkills: readonly string[],
-  pickedPaths: readonly string[],
-): string[] => {
-  const picks = new Set(pickedPaths.map(basenameOf));
-  // Derive root from first pick's dirname; all picks are under same root
-  // (skills-root guarantees this). Fall back to "" if no picks.
-  const root = pickedPaths.length > 0 ? dirnameOf(pickedPaths[0] as string) : "";
-  const entries: string[] = [];
-  for (const name of knownSkills) {
-    if (!picks.has(name)) {
-      const absPath = root ? `${root}/${name}/SKILL.md` : `${name}/SKILL.md`;
-      entries.push(`{path=${JSON.stringify(absPath)}, enabled=false}`);
+  switch (h.skills.overridesVia) {
+    case "settings-skilloverrides":
+      return settingsOverrides(skills);
+    case "config-skills-array":
+      return configSkillsArray(skills);
+    case null:
+      return [];
+    default: {
+      const exhaustive: never = h.skills.overridesVia;
+      return exhaustive;
     }
   }
-  if (entries.length === 0) return [];
-  return ["-c", `skills.config=[${entries.join(", ")}]`];
 };

package/src/interpretation/support.ts

@@ -27,21 +27,34 @@ 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;
+      if (spec === undefined || spec.kind !== "access") return null;
+      const read = spec.renders.read;
+      if (read === "tool-preset") return h.tools.includeFlag ?? h.tools.excludeFlag ?? null;
+      if (read === null) return null;
+      return read.render.kind === "flag-list" ? (read.render.flags[0] ?? null) : read.render.flag;
     }
     case "tools":
       return h.tools.includeFlag;
     case "excludeTools":
       return h.tools.excludeFlag;
+    case "skills": {
+      if (h.skills === null) return null;
+      if (h.skills.loadFlag !== null) return h.skills.loadFlag;
+      switch (h.skills.overridesVia) {
+        case "settings-skilloverrides":
+          return "skillOverrides";
+        case "config-skills-array":
+          return "-c skills.config";
+        default:
+          return null;
+      }
+    }
     case "autonomy":
       return h.autonomy?.flag ?? null;
+    case "isolation":
     case "effort":
     case "sandbox":
+    case "contextWindow":
     case "provider":
     case "write":
     case "shell":
@@ -112,8 +125,10 @@ export const recognizeNativeSpelling = (
     "tools",
     "excludeTools",
     "autonomy",
+    "isolation",
     "effort",
     "sandbox",
+    "contextWindow",
     "provider",
     "write",
     "shell",