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

package/src/cli/args.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import type { DiscoveryOptions, TurnOptions } from "../interpretation/argv.js";
+import { isQuestionMode, QUESTION_MODES } from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 
 export type ParsedPromptSource =
@@ -49,7 +50,6 @@ export const parseEnvEntries = (
     if (eq === -1) {
       throw new ArgvRefusalError({
         issue: "invalid-env",
-        harness: "claude",
         supported: ["KEY=VAL"],
         detail: entry,
       });
@@ -59,7 +59,6 @@ export const parseEnvEntries = (
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || value.includes("\0") || key.includes("\0")) {
       throw new ArgvRefusalError({
         issue: "invalid-env",
-        harness: "claude",
         supported: ["keys must match ^[A-Za-z_][A-Za-z0-9_]*$ and contain no NUL"],
         detail: entry,
       });
@@ -82,7 +81,6 @@ export const resolvePrompt = (args: {
   if (count === 0) {
     throw new ArgvRefusalError({
       issue: "invalid-option-value",
-      harness: "claude",
       supported: ["provide prompt via positional, --prompt, or --prompt-file"],
       detail: "missing prompt",
     });
@@ -90,7 +88,6 @@ export const resolvePrompt = (args: {
   if (count > 1) {
     throw new ArgvRefusalError({
       issue: "invalid-option-value",
-      harness: "claude",
       supported: ["use one of positional, --prompt, or --prompt-file"],
       detail: "mutual exclusion",
     });
@@ -122,7 +119,6 @@ export const resolvePromptAsync = async (args: {
   if (count === 0) {
     throw new ArgvRefusalError({
       issue: "invalid-option-value",
-      harness: "claude",
       supported: ["provide prompt via positional, --prompt, or --prompt-file"],
       detail: "missing prompt",
     });
@@ -130,7 +126,6 @@ export const resolvePromptAsync = async (args: {
   if (count > 1) {
     throw new ArgvRefusalError({
       issue: "invalid-option-value",
-      harness: "claude",
       supported: ["use one of positional, --prompt, or --prompt-file"],
       detail: "mutual exclusion",
     });
@@ -148,15 +143,21 @@ export const resolvePromptAsync = async (args: {
   return { prompt: content, source: "prompt-file" };
 };
 
+/** Parsed turn options plus the skill names as typed, which the command
+ * resolves against the registry before they become a turn option. */
+export type ParsedTurnOptions = TurnOptions & { readonly skillNames?: readonly string[] };
+
 /**
  * Build TurnOptions from parsed flag values. Shared between run and inspect --argv.
  */
-export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions => {
+export const parseTurnOptions = (values: Record<string, unknown>): ParsedTurnOptions => {
   const opts: Record<string, unknown> = {};
 
+  if (values.isolation !== undefined) opts.isolation = values.isolation;
   if (values.model !== undefined) opts.model = values.model;
   if (values.effort !== undefined) opts.effort = values.effort;
   if (values.sandbox !== undefined) opts.sandbox = values.sandbox;
+  if (values["context-window"] !== undefined) opts.contextWindow = Number(values["context-window"]);
   if (values.provider !== undefined) opts.provider = values.provider;
   if (values.tools !== undefined) {
     const raw = String(values.tools);
@@ -167,9 +168,10 @@ export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions =
     opts.excludeTools = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim());
   }
   if (values.skills !== undefined) {
+    // Names as typed; the command resolves them against the registry and
+    // builds the skills turn option (picks plus known names) from them.
     const raw = String(values.skills);
-    (opts as Record<string, unknown>).skills =
-      raw.length === 0 ? [] : raw.split(",").map((s) => s.trim());
+    opts.skillNames = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim());
   }
   if (values.autonomy === true) opts.autonomy = true;
   else if (values["no-autonomy"] === true) opts.autonomy = false;
@@ -181,16 +183,15 @@ export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions =
   else if (values["no-shell"] === true) opts.shell = false;
   if (values.questions !== undefined) {
     const v = String(values.questions);
-    if (!["ask", "assume", "none"].includes(v)) {
+    if (!isQuestionMode(v)) {
       throw new ArgvRefusalError({
         issue: "invalid-option-value",
-        harness: "claude",
         option: "questions",
-        supported: ["ask", "assume", "none"],
+        supported: [...QUESTION_MODES],
         detail: v,
       });
     }
-    (opts as Record<string, unknown>).questions = v;
+    opts.questions = v;
   }
   if (values["system-prompt"] !== undefined) opts.systemPrompt = String(values["system-prompt"]);
   if (values["append-system-prompt"] !== undefined)
@@ -201,7 +202,6 @@ export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions =
     if (!Number.isFinite(n)) {
       throw new ArgvRefusalError({
         issue: "invalid-option-value",
-        harness: "claude",
         option: "maxSteps",
         supported: ["integer 1-10000"],
         detail: String(values["max-steps"]),
@@ -234,7 +234,22 @@ export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions =
   if (values.access !== undefined) opts.access = String(values.access);
 
   // prompt will be set by caller after resolvePrompt
-  return opts as unknown as TurnOptions;
+  return opts as unknown as ParsedTurnOptions;
+};
+
+/** `--resume` and `--session-id` are aliases for one session id; both at
+ * once refuses. The one check every command calls (run, inspect, session). */
+export const resumeIdOf = (values: Record<string, unknown>): string | undefined => {
+  if (values.resume !== undefined && values["session-id"] !== undefined) {
+    throw new ArgvRefusalError({
+      issue: "mutually-exclusive-options",
+      supported: ["--resume or --session-id, not both (--session-id is an alias for --resume)"],
+      detail: "both --resume and --session-id given",
+    });
+  }
+  if (values.resume !== undefined) return String(values.resume);
+  if (values["session-id"] !== undefined) return String(values["session-id"]);
+  return undefined;
 };
 
 export const parseRunExtra = (
@@ -256,8 +271,7 @@ export const parseRunExtra = (
     if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) {
       throw new ArgvRefusalError({
         issue: "invalid-option-value",
-        harness: "claude",
-        option: "maxSteps",
+        option: "timeout",
         supported: ["whole seconds, >= 0 (0 disables)"],
         detail: String(values.timeout),
       });
@@ -265,16 +279,8 @@ export const parseRunExtra = (
     extra.timeoutSeconds = n;
   }
   if (values.cwd !== undefined) extra.cwd = String(values.cwd);
-  if (values.resume !== undefined && values["session-id"] !== undefined) {
-    throw new ArgvRefusalError({
-      issue: "mutually-exclusive-options",
-      harness: "claude",
-      supported: ["--resume or --session-id, not both (--session-id is an alias for --resume)"],
-      detail: "both --resume and --session-id given",
-    });
-  }
-  if (values.resume !== undefined) extra.resume = String(values.resume);
-  if (values["session-id"] !== undefined) extra.resume = String(values["session-id"]);
+  const resume = resumeIdOf(values);
+  if (resume !== undefined) extra.resume = resume;
   if (values.env !== undefined) {
     // parseArgs with multiple:true gives string[] ; else string
     const list = values.env as string | string[];
@@ -294,6 +300,7 @@ const KNOWN_FLAGS = new Set([
   "--model",
   "--effort",
   "--sandbox",
+  "--context-window",
   "--provider",
   "--tools",
   "--exclude-tools",
@@ -308,6 +315,7 @@ const KNOWN_FLAGS = new Set([
   "--system-prompt",
   "--append-system-prompt",
   "--max-steps",
+  "--isolation",
   "--no-tools",
   "--no-instruction-files",
   "--no-extensions",
@@ -328,11 +336,13 @@ const KNOWN_FLAGS = new Set([
 ]);
 
 const FLAGS_WITH_VALUE = new Set([
+  "--isolation",
   "--prompt",
   "--prompt-file",
   "--model",
   "--effort",
   "--sandbox",
+  "--context-window",
   "--provider",
   "--tools",
   "--exclude-tools",
@@ -448,6 +458,7 @@ export const parseCommonFlags = (
       model: { type: "string" as const },
       effort: { type: "string" as const },
       sandbox: { type: "string" as const },
+      "context-window": { type: "string" as const },
       provider: { type: "string" as const },
       tools: { type: "string" as const },
       "exclude-tools": { type: "string" as const },
@@ -462,6 +473,7 @@ export const parseCommonFlags = (
       "system-prompt": { type: "string" as const },
       "append-system-prompt": { type: "string" as const },
       "max-steps": { type: "string" as const },
+      isolation: { type: "string" as const },
       access: { type: "string" as const },
       "no-tools": { type: "boolean" as const },
       "no-instruction-files": { type: "boolean" as const },

package/src/cli/check.ts

@@ -12,7 +12,10 @@ interface Row {
   status: VersionStatus;
 }
 
-const npmLatest = async (pkg: string): Promise<string | null> => {
+/** The latest published version of an npm package, or null when the
+ * registry cannot be reached. One owner; the version-check script imports
+ * it (RFC-02 change 12). */
+export const npmLatest = async (pkg: string): Promise<string | null> => {
   try {
     const res = await fetch(`https://registry.npmjs.org/${pkg}`, {
       headers: { accept: "application/vnd.npm.install-v1+json" },
@@ -27,7 +30,9 @@ const npmLatest = async (pkg: string): Promise<string | null> => {
   }
 };
 
-const installedVersion = (bin: string): string | null => {
+/** The locally installed CLI's version from `<bin> --version`, or null
+ * when the binary is absent or reports none. */
+export const installedVersion = (bin: string): string | null => {
   try {
     const out = execFileSync(bin, ["--version"], { encoding: "utf8", timeout: 10_000 });
     const match = out.match(/\d+\.\d+\.\d+(?:[.+-][0-9A-Za-z.-]+)?/);
@@ -37,7 +42,9 @@ const installedVersion = (bin: string): string | null => {
   }
 };
 
-const resolveLatest = async (
+/** Where a descriptor's latest version is found, per its versionSource:
+ * the npm registry, or the installed binary. */
+export const resolveLatest = async (
   h: HarnessDescriptor,
 ): Promise<{ latest: string | null; source: string }> => {
   if (h.versionSource.kind === "npm") {

package/src/cli/config.ts

@@ -20,8 +20,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { TurnOptions } from "../interpretation/argv.js";
-import { TOOL_SELECTOR } from "../interpretation/tool-selection.js";
-import { validateAccess } from "../interpretation/vocabulary.js";
+import { isQuestionMode, QUESTION_MODES } from "../interpretation/question.js";
+import type { ConfigTier } from "../interpretation/resolve-options.js";
+import { CLEAN_SELECTOR, validateAccess } from "../interpretation/vocabulary.js";
 import { HARNESS_NAMES } from "../knowledge/descriptor.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 
@@ -63,11 +64,14 @@ type MutableTurnOptions = {
   [K in keyof TurnOptions]?: TurnOptions[K];
 };
 
+// Isolation is invocation-only: a config must not silently change native auth
+// or disable all tools for unrelated turns.
 const KNOWN_KEYS = new Set([
   "effort",
   "model",
   "provider",
   "sandbox",
+  "contextWindow",
   "tools",
   "excludeTools",
   "autonomy",
@@ -88,11 +92,10 @@ const KNOWN_KEYS = new Set([
 
 const LIST_KEYS = new Set(["tools", "excludeTools"]);
 const BOOL_KEYS = new Set(["autonomy", "write", "shell"]);
-const QUESTIONS_VALUES = new Set(["ask", "assume", "none"]);
 
 /** Parse + validate config text. Throws ConfigError with the offending key
  * named on any violation - never warns and continues. */
-export const parseUserConfig = (text: string): Partial<TurnOptions> => {
+export const parseUserConfig = (text: string): ConfigTier => {
   let raw: unknown;
   try {
     raw = JSON.parse(text);
@@ -126,7 +129,7 @@ export const parseUserConfig = (text: string): Partial<TurnOptions> => {
         );
       }
       const toolMapObj = value as Record<string, unknown>;
-      const SEL = TOOL_SELECTOR;
+      const SEL = CLEAN_SELECTOR;
       const descSet = defaultDescriptors();
       const harnessNames = HARNESS_NAMES as readonly string[];
       for (const [harness, inner] of Object.entries(toolMapObj)) {
@@ -228,9 +231,9 @@ export const parseUserConfig = (text: string): Partial<TurnOptions> => {
       continue;
     }
     if (key === "questions") {
-      if (typeof value !== "string" || !QUESTIONS_VALUES.has(value)) {
+      if (typeof value !== "string" || !isQuestionMode(value)) {
         throw new ConfigError(
-          `config key ${JSON.stringify(key)} must be one of ${[...QUESTIONS_VALUES].join(", ")}`,
+          `config key ${JSON.stringify(key)} must be one of ${QUESTION_MODES.join(", ")}`,
         );
       }
       (out as Record<string, unknown>).questions = value;
@@ -250,24 +253,24 @@ export const parseUserConfig = (text: string): Partial<TurnOptions> => {
     }
     (out as Record<string, unknown>)[key] = value;
   }
-  return out as Partial<TurnOptions>;
+  return out as ConfigTier;
 };
 
 /** Load the user config if the file exists; absent file is an empty config
  * (no tiers engaged), unreadable or invalid file is a hard error. */
-export const loadUserConfig = (): { config: Partial<TurnOptions>; path: string } | null =>
+export const loadUserConfig = (): { config: ConfigTier; path: string } | null =>
   loadConfigAt(userConfigPath());
 
 /** Load the project config (git-root auto-discovery, ratified A). */
 export const loadProjectConfig = (
   startDir?: string,
-): { config: Partial<TurnOptions>; path: string } | null => {
+): { config: ConfigTier; path: string } | null => {
   const path = projectConfigPath(startDir);
   if (path === null) return null;
   return loadConfigAt(path);
 };
 
-const loadConfigAt = (path: string): { config: Partial<TurnOptions>; path: string } | null => {
+const loadConfigAt = (path: string): { config: ConfigTier; path: string } | null => {
   let text: string;
   try {
     text = readFileSync(path, "utf8");

package/src/cli/exit-codes.ts

@@ -9,5 +9,3 @@ export const exitCodeForCause = (cause: ExitCause): number => {
   // All non-clean causes are failures that should be exit 1, except refusal is already handled separately
   return EXIT_FAILURE;
 };
-
-export const exitCodeForRefusal = (): number => EXIT_REFUSAL;

package/src/cli/help.ts

@@ -31,6 +31,8 @@ Options:
   --model <id>              Model id (validated per harness)
   --effort <value>          Effort level (validated per harness/model)
   --sandbox <value>         Sandbox mode (codex only)
+  --context-window <tokens> Context window (codex, integer 1-272000;
+                            launch default 272000; config: contextWindow)
   --provider <value>        Provider (pi only)
   --tools <a,b>             Tool grant allowlist - canonical names (read, write,
                             edit, shell, grep, glob, list, web-fetch,
@@ -70,11 +72,14 @@ Options:
   --max-steps <n>           Max steps (muse, 1-10000)
   --timeout <seconds>       Wall-clock budget for the run (all harnesses,
                             hcn-enforced; 0 disables; no default)
+  --isolation <tool-free>   Fresh tool-free turn (claude); no resume, tools,
+                            skills, access, autonomy, discovery, or native passthrough.
+                            Uses bare mode; native authentication must support it.
   --no-tools                Disable tools discovery facet
   --no-instruction-files    Disable instructionFiles discovery facet
   --no-extensions           Disable extensions discovery facet
   --skills <a,b>            Skill allowlist (names resolved against $HCN_SKILLS_ROOT
-                            or ~/.agents/skills; pi loads, claude narrows)
+                            or ~/.agents/skills; pi loads, claude and codex narrow)
   --no-skills               Disable skills discovery facet
   --cwd <path>              Working directory for spawn
   --env KEY=VAL             Environment (repeatable; KEY= deletes)
@@ -99,7 +104,8 @@ Defaults with no flags:
   git root) > user config (~/.config/hcn/config.json) > built-in profile
   > harness default. The profile pins: effort medium, sandbox
   workspace-write (codex only; other harnesses report divergence),
-  discovery on, autonomy off, write/shell on. timeout, max-steps and
+  context window 272000 (codex only; divergence elsewhere), discovery on,
+  autonomy off, write/shell on. timeout, max-steps and
   access have no default; harness default applies (access write emits
   nothing on claude/pi/muse, --sandbox workspace-write on codex via
   profile). toolMap is config-only (no flag) - canonical -> native
@@ -171,6 +177,7 @@ Options:
   --model <id>              Model
   --effort <value>          Effort
   --sandbox <value>         Sandbox
+  --context-window <tokens> Context window (codex, integer 1-272000)
   --provider <value>        Provider
   --tools <a,b>             Tools - canonical names (read, write, edit,
                             shell, grep, glob, list, web-fetch,
@@ -182,6 +189,7 @@ Options:
   --questions <ask|assume|none>
                             (accepted; renders nothing - rides the run prompt)
   --max-steps <n>
+  --isolation <tool-free> (fresh claude turn only)
   --no-tools, --no-instruction-files, --no-extensions, --no-skills
   --questions <ask|assume|none>
                             Accepted; renders nothing in argv (the mode

package/src/cli/index.ts

@@ -2,10 +2,12 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { HARNESS_NAMES } from "../knowledge/descriptor.js";
 import { TOP_LEVEL_HELP } from "./help.js";
 import { getVersion } from "./version.js";
 
-const SUPPORTED = ["claude", "codex", "pi", "muse"] as const;
+/** The one harness list, read from the descriptor vocabulary. */
+const SUPPORTED: readonly string[] = HARNESS_NAMES;
 
 // Prevent EPIPE crashes when piped to head/grep -q (e.g., hcn ls | head, hcn run --json | head)
 process.stdout.on("error", (err) => {