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

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

@@ -1,9 +1,9 @@
 /**
  * The claude-code descriptor: facts about the `claude` CLI as data, verified
- * against claude 2.1.229 and the 00-chat-substrate spike evidence (A-001,
+ * against claude 2.1.233 and the 00-chat-substrate spike evidence (A-001,
  * A-002, A-005). No process logic lives here.
  *
- * Discovery: claude 2.1.229 has no isolated instruction-file toggle.
+ * Discovery: claude 2.1.233 has no isolated instruction-file toggle.
  * `--bare` would stop `CLAUDE.md` discovery, but it also skips hooks, LSP,
  * plugin sync, auto-memory and keychain reads, and forces auth to
  * `ANTHROPIC_API_KEY` / `apiKeyHelper` (OAuth never read) - so a caller
@@ -21,7 +21,7 @@ import { SHARED_AUTH_MATCHERS, SHARED_LIMIT_MATCHERS } from "./matchers.js";
 export const claudeCode: HarnessDescriptor = deepFreeze({
   name: "claude",
   bin: "claude",
-  verifiedAgainst: "2.1.229",
+  verifiedAgainst: "2.1.233",
   versionSource: { kind: "npm", package: "@anthropic-ai/claude-code" },
   launch: {
     baseFlags: ["-p"],
@@ -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",
+  },
 });

package/src/knowledge/descriptor.ts

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

package/src/knowledge/muse.ts

@@ -14,6 +14,9 @@ export const museCode: HarnessDescriptor = deepFreeze({
   name: "muse",
   bin: "muse",
   verifiedAgainst: "0.1.0",
+  // No npm package - `hcn check` falls back to `muse --version` locally and
+  // is skipped in CI where the binary is absent, so this harness is exempt
+  // from automated drift detection (see README Version-pinning and drift).
   versionSource: { kind: "installed" },
   launch: {
     // exec --json emits the payload_type/stream records the runner decodes
@@ -107,4 +110,23 @@ export const museCode: HarnessDescriptor = deepFreeze({
       render: { kind: "flag-value", flag: "--max-model-steps" },
     },
   },
+  // Phase 0 fixtures: muse-category-flags.md. No name lists; category
+  // switches are enforcement gates - tools stay listed in the catalog but
+  // calls are denied per session policy (unlike claude's set removal).
+  // Tool names follow muse.<name> (write_file, edit_file, bash, bash_input,
+  // add_memory, edit_memory, web_search). --disable-web-tools has no
+  // normalized turnOption yet - candidate for a web toggle or passthrough.
+  tools: {
+    includeFlag: null,
+    excludeFlag: null,
+    includeIsStrictAllowlist: false,
+    composable: false,
+    builtins: [],
+    categories: [
+      { key: "write", disableFlag: "--disable-write", configKey: null },
+      { key: "shell", disableFlag: "--disable-shell", configKey: null },
+      { key: "web", disableFlag: "--disable-web-tools", configKey: null },
+    ],
+    denySemantics: "policy-gate",
+  },
 });

package/src/knowledge/pi.ts

@@ -1,6 +1,6 @@
 /**
  * The pi descriptor: facts about the `pi` CLI as data, verified against
- * pi 0.84.1. Descriptor groundwork only (D-003). The load-bearing scars:
+ * pi 0.84.2. Descriptor groundwork only (D-003). The load-bearing scars:
  * pi reads stdin even in -p mode (a backgrounded call without `< /dev/null`
  * hangs forever), it auto-discovers instruction files/skills/extensions
  * unless disabled, and its model registry is runtime-extensible (D-008) -
@@ -12,11 +12,13 @@ import { SHARED_AUTH_MATCHERS, SHARED_LIMIT_MATCHERS } from "./matchers.js";
 export const piCli: HarnessDescriptor = deepFreeze({
   name: "pi",
   bin: "pi",
-  verifiedAgainst: "0.84.1",
+  verifiedAgainst: "0.84.2",
   versionSource: { kind: "npm", package: "@earendil-works/pi-coding-agent" },
   launch: {
     // -p --mode json: bare -p prints plain text; --mode json emits the
-    // structured v3 records the runner decodes (verified 0.84.1).
+    // structured v3 records the runner decodes (verified 0.84.2; 0.84.2
+    // additionally nests a usage object inside message_update alongside
+    // assistantMessageEvent - additive, decoder unaffected).
     baseFlags: ["-p", "--mode", "json"],
     subcommands: [],
     promptStyle: "positional",
@@ -35,14 +37,14 @@ export const piCli: HarnessDescriptor = deepFreeze({
     onMissing: "create",
     extraFlags: ["-p", "--mode", "json"],
   },
-  // --mode rpc exists on 0.84.1 but its session semantics are unverified
+  // --mode rpc exists on 0.84.2 but its session semantics are unverified
   // against a live run; per the truthfulness rule it stays null until a
   // spike proves the contract (the claude slice is the proven vertical -
   // D-003).
   sessionMode: null,
   output: {
     // pi -p prints plain text; --mode json emits structured v3 records
-    // INCLUDING assistantMessageEvent text_delta tokens (verified 0.84.1),
+    // INCLUDING assistantMessageEvent text_delta tokens (verified 0.84.2),
     // so this invocation is token-granular, not merely message.
     pins: [{ flags: ["--mode", "json"], granularity: "token" }],
     floor: "none",
@@ -68,7 +70,7 @@ export const piCli: HarnessDescriptor = deepFreeze({
     extensible: true,
   },
   store: {
-    // Verified on pi 0.84.1: ~/.pi/sessions/<slug>/<ISO-stamp>_<uuid>.jsonl
+    // Verified on pi 0.84.2: ~/.pi/sessions/<slug>/<ISO-stamp>_<uuid>.jsonl
     // where the slug is the cwd dash-flattened and dash-wrapped, dots
     // preserved (--Users-kevin-dev-x--). The stamp needs a store scan, so
     // the template names the per-cwd directory.
@@ -116,4 +118,25 @@ export const piCli: HarnessDescriptor = deepFreeze({
       },
     },
   },
+  // Phase 0 fixtures: pi-both-tool-flags.md. Both list flags legal at once;
+  // exclude subtracts from include. --tools is strict over BUILT-INS but
+  // does not strip MCP/extension registrations (additive over them);
+  // -nbt (built-ins only off) exists but has no normalized spelling yet.
+  tools: {
+    includeFlag: "--tools",
+    excludeFlag: "--exclude-tools",
+    includeIsStrictAllowlist: true,
+    composable: true,
+    builtins: [
+      { name: "read", defaultEnabled: true },
+      { name: "bash", defaultEnabled: true },
+      { name: "edit", defaultEnabled: true },
+      { name: "write", defaultEnabled: true },
+      { name: "grep", defaultEnabled: false },
+      { name: "find", defaultEnabled: false },
+      { name: "ls", defaultEnabled: false },
+    ],
+    categories: [],
+    denySemantics: "remove-from-set",
+  },
 });

package/src/knowledge/profile.ts

@@ -0,0 +1,33 @@
+/**
+ * The built-in default turn profile: hcn's curated defaults for a bare run,
+ * decided in review (2026-08-18) and applied LAUNCH-ONLY, before user config
+ * and args. Every entry here is a ratified dimension; unratified dimensions
+ * stay absent and defer to the harness.
+ *
+ * effort: "medium" - the only value present in all four effort ladders
+ * (claude/pi/muse/codex-per-model). Live probe on claude 2.1.233 showed the
+ * internal default is above medium and nondeterministic (599-1482 thinking
+ * tokens on identical tasks vs 436 at medium); pinning makes bare runs
+ * cheaper on claude, uniform everywhere, and knowable from the outside.
+ */
+import { deepFreeze } from "./descriptor.js";
+
+export const DEFAULT_TURN_PROFILE = deepFreeze({
+  effort: "medium",
+  // codex-only (the only harness with a sandbox dimension). Promotes the
+  // descriptor's implicit workspace-write default into the visible
+  // profile tier. On the other three the dimension is unrenderable and
+  // reports as divergence.
+  sandbox: "workspace-write",
+  // Ratified: discovery fully ON. The harnesses' bare runs already
+  // discover instruction files, skills, and extensions; the profile makes
+  // that a stated contract. The off-spellings exist per harness
+  // (-ns/-nc/-ne on pi, --setting-sources on claude) for callers who want
+  // less.
+  discovery: { tools: true, instructionFiles: true, extensions: true, skills: true },
+  // Ratified: autonomy OFF. No bare run is unattended; --autonomy or a
+  // config must say so deliberately.
+  autonomy: false,
+} as const);
+
+export type ProfileKey = keyof typeof DEFAULT_TURN_PROFILE;

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

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

package/dist/index.js.map

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

package/src/index.ts

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