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

package/dist/knowledge/profile.d.ts

@@ -8,6 +8,9 @@ export declare const DEFAULT_TURN_PROFILE: {
         readonly skills: true;
     };
     readonly autonomy: false;
+    readonly write: true;
+    readonly shell: true;
+    readonly tools: "all-known";
 };
 export type ProfileKey = keyof typeof DEFAULT_TURN_PROFILE;
 //# sourceMappingURL=profile.d.ts.map

package/dist/knowledge/profile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/knowledge/profile.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,oBAAoB;qBACvB,QAAQ;sBAKP,iBAAiB;;iBAMb,KAAK;iBAAQ,gBAAgB;iBAAQ,UAAU;iBAAQ,MAAM;;;CAIjE,CAAC;AAEZ,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,oBAAoB,CAAC"}
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/knowledge/profile.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,oBAAoB;qBACvB,QAAQ;sBAKP,iBAAiB;;iBAMb,KAAK;iBAAQ,gBAAgB;iBAAQ,UAAU;iBAAQ,MAAM;;;;;oBAenE,WAAW;CAST,CAAC;AAEZ,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,oBAAoB,CAAC"}

package/dist/knowledge/profile.js

@@ -27,5 +27,25 @@ export const DEFAULT_TURN_PROFILE = deepFreeze({
     // Ratified: autonomy OFF. No bare run is unattended; --autonomy or a
     // config must say so deliberately.
     autonomy: false,
+    // D9/D10, ratified round 2: write and shell ON - names current
+    // behavior (emit-nothing on claude/codex/pi; muse omits its disable
+    // flags). Completes the "what can a bare run do to the machine" row of
+    // provenance.
+    write: true,
+    shell: true,
+    // D13, ratified: equivalent-as-possible tool defaults. The marker
+    // expands per descriptor at resolve time - pi gains its dormant
+    // grep/find/ls; claude emits nothing (already everything); codex/muse
+    // report divergence (no list surface). Project floors narrow it by
+    // the normal precedence chain.
+    tools: "all-known",
+    // Model is PERMANENTLY out of profile scope (ratified round 2): no
+    // cross-harness model namespace exists, pi's registry is
+    // runtime-extensible and environment-dependent, and per-harness config
+    // already covers "claude on X, pi on Y". Do not add a model entry.
+    // timeout and maxSteps are likewise opt-in-only dimensions (D11/D12):
+    // no harness ships a wall-clock cap, one prompt expands into an
+    // unbounded turn loop, and a fixed default kills legitimate work. They
+    // live in args/config only, never here.
 });
 //# sourceMappingURL=profile.js.map

package/dist/knowledge/profile.js.map

@@ -1 +1 @@
-{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../src/knowledge/profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;IAC7C,MAAM,EAAE,QAAQ;IAChB,uEAAuE;IACvE,iEAAiE;IACjE,qEAAqE;IACrE,yBAAyB;IACzB,OAAO,EAAE,iBAAiB;IAC1B,iEAAiE;IACjE,wEAAwE;IACxE,8DAA8D;IAC9D,wEAAwE;IACxE,QAAQ;IACR,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IAClF,qEAAqE;IACrE,mCAAmC;IACnC,QAAQ,EAAE,KAAK;CACP,CAAC,CAAC"}
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../src/knowledge/profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;IAC7C,MAAM,EAAE,QAAQ;IAChB,uEAAuE;IACvE,iEAAiE;IACjE,qEAAqE;IACrE,yBAAyB;IACzB,OAAO,EAAE,iBAAiB;IAC1B,iEAAiE;IACjE,wEAAwE;IACxE,8DAA8D;IAC9D,wEAAwE;IACxE,QAAQ;IACR,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IAClF,qEAAqE;IACrE,mCAAmC;IACnC,QAAQ,EAAE,KAAK;IACf,+DAA+D;IAC/D,oEAAoE;IACpE,uEAAuE;IACvE,cAAc;IACd,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,IAAI;IACX,kEAAkE;IAClE,gEAAgE;IAChE,sEAAsE;IACtE,mEAAmE;IACnE,+BAA+B;IAC/B,KAAK,EAAE,WAAW;IAClB,mEAAmE;IACnE,yDAAyD;IACzD,uEAAuE;IACvE,mEAAmE;IACnE,sEAAsE;IACtE,gEAAgE;IAChE,uEAAuE;IACvE,wCAAwC;CAChC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dungle-scrubs/harness-cli-normalizer",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "One stable CLI to four coding-agent harnesses: normalized flags, defaults, and events.",
   "license": "MIT",
   "author": "Kevin Frilot",

package/src/cli/args.ts

@@ -166,6 +166,11 @@ export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions =
     const raw = String(values["exclude-tools"]);
     opts.excludeTools = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim());
   }
+  if (values.skills !== undefined) {
+    const raw = String(values.skills);
+    (opts as Record<string, unknown>).skills =
+      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;
   else if (values.autonomy === false) opts.autonomy = false; // for completeness
@@ -216,8 +221,31 @@ export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions =
 
 export const parseRunExtra = (
   values: Record<string, unknown>,
-): { cwd?: string; env?: Record<string, string>; resume?: string } => {
-  const extra: { cwd?: string; env?: Record<string, string>; resume?: string } = {};
+): {
+  cwd?: string;
+  env?: Record<string, string>;
+  resume?: string;
+  timeoutSeconds?: number;
+} => {
+  const extra: {
+    cwd?: string;
+    env?: Record<string, string>;
+    resume?: string;
+    timeoutSeconds?: number;
+  } = {};
+  if (values.timeout !== undefined) {
+    const n = Number(values.timeout);
+    if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) {
+      throw new ArgvRefusalError({
+        issue: "invalid-option-value",
+        harness: "claude",
+        option: "maxSteps",
+        supported: ["whole seconds, >= 0 (0 disables)"],
+        detail: String(values.timeout),
+      });
+    }
+    extra.timeoutSeconds = n;
+  }
   if (values.cwd !== undefined) extra.cwd = String(values.cwd);
   if (values.resume !== undefined) extra.resume = String(values.resume);
   if (values["session-id"] !== undefined) extra.resume = String(values["session-id"]);
@@ -280,6 +308,7 @@ const FLAGS_WITH_VALUE = new Set([
   "--env",
   "--resume",
   "--session-id",
+  "--timeout",
 ]);
 
 export const detectPositionalPromptInjection = (argv: string[]): string | null => {
@@ -385,6 +414,7 @@ export const parseCommonFlags = (
       provider: { type: "string" as const },
       tools: { type: "string" as const },
       "exclude-tools": { type: "string" as const },
+      skills: { type: "string" as const },
       autonomy: { type: "boolean" as const },
       "no-autonomy": { type: "boolean" as const },
       write: { type: "boolean" as const },
@@ -400,6 +430,7 @@ export const parseCommonFlags = (
       env: { type: "string" as const, multiple: true },
       resume: { type: "string" as const },
       "session-id": { type: "string" as const },
+      timeout: { type: "string" as const },
       json: { type: "boolean" as const },
       argv: { type: "boolean" as const },
       help: { type: "boolean" as const },

package/src/cli/config.ts

@@ -65,6 +65,7 @@ const KNOWN_KEYS = new Set([
   "shell",
   "maxSteps",
   "toolsets",
+  "timeout",
 ]);
 
 const LIST_KEYS = new Set(["tools", "excludeTools"]);
@@ -115,6 +116,15 @@ export const parseUserConfig = (text: string): Partial<TurnOptions> => {
       (out as Record<string, unknown>)[key] = value;
       continue;
     }
+    if (key === "timeout") {
+      if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new ConfigError(
+          'config key "timeout" must be a whole number of seconds, >= 0 (0 disables)',
+        );
+      }
+      (out as Record<string, unknown>)[key] = value;
+      continue;
+    }
     if (LIST_KEYS.has(key)) {
       if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
         throw new ConfigError(`config key ${JSON.stringify(key)} must be an array of strings`);

package/src/cli/help.ts

@@ -32,7 +32,10 @@ Options:
   --effort <value>          Effort level (validated per harness/model)
   --sandbox <value>         Sandbox mode (codex only)
   --provider <value>        Provider (pi only)
-  --tools <a,b>             Tool grants (claude only, comma-separated)
+  --tools <a,b>             Tool grant allowlist (claude, pi; a bare name
+                            matching a configured toolset expands to it)
+  --exclude-tools <a,b>     Complement over known tools (claude, pi;
+                            mutually exclusive with --tools)
   --autonomy                Enable autonomy flag (claude/codex/muse)
   --no-autonomy             Disable autonomy
   --write                   Enable write (muse)
@@ -40,6 +43,8 @@ Options:
   --shell                   Enable shell (muse)
   --no-shell                Disable shell
   --max-steps <n>           Max steps (muse, 1-10000)
+  --timeout <seconds>       Wall-clock budget for the run (all harnesses,
+                            hcn-enforced; 0 disables; no default)
   --no-tools                Disable tools discovery facet
   --no-instruction-files    Disable instructionFiles discovery facet
   --no-extensions           Disable extensions discovery facet
@@ -47,9 +52,20 @@ Options:
   --cwd <path>              Working directory for spawn
   --env KEY=VAL             Environment (repeatable; KEY= deletes)
   --resume <uuid>           Resume session id (UUID)
+  --                        Passthrough: native harness args verbatim
+                            (failures surface as labeled native errors)
   --json                    NDJSON HarnessEvent to stdout
   -h, --help                Show help
   -V, --version             Show version
+
+Defaults with no flags:
+  Every launch resolves args > project config (.hcn/config.json at the
+  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 and max-steps have
+  no default. Provenance prints to stderr on every run; see
+  'hcn inspect <harness>' for the resolved argv of a bare run.
 `;
 
 export const SESSION_HELP = `hcn session - Interactive session (Claude-only)

package/src/cli/run.ts

@@ -186,16 +186,42 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
 
   const isExplicit = promptSource !== "positional";
 
+  // issue #38: resolve --skills names against the caller's registry root,
+  // then hand the harness its native rendering (pi loads; claude narrows).
+  const rawSkills = (turnOpts as unknown as { skills?: string[] }).skills;
+  if (rawSkills !== undefined && rawSkills.length > 0) {
+    try {
+      const { resolveSkillNames, listKnownSkills } = await import("./skills-root.js");
+      const resolvedSkills = resolveSkillNames(rawSkills);
+      const claudeTokens: string[] = [];
+      if (h.name === "claude") {
+        const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
+        claudeTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+      }
+      (turnOpts as unknown as Record<string, unknown>).skills = resolvedSkills;
+      (turnOpts as unknown as Record<string, unknown>).__claudeSkillTokens = claudeTokens;
+    } catch (err) {
+      if (err instanceof ArgvRefusalError) {
+        process.stderr.write(`${err.message}\n`);
+        if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+        process.exitCode = 2;
+        return;
+      }
+      throw err;
+    }
+  }
+
   // Defaults profile + user config: LAUNCH-ONLY. A resumed session keeps
   // its own settings; the resolver never runs on resume paths.
   let resolvedProvenance: readonly ProvenanceEntry[] = [];
   let resolvedUnrenderable: readonly string[] = [];
   let effectiveTurnOpts: ReturnType<typeof parseTurnOptions> = turnOpts;
+  const resolvedTiers: {
+    user?: Partial<ReturnType<typeof parseTurnOptions>>;
+    project?: Partial<ReturnType<typeof parseTurnOptions>>;
+  } = {};
   if (extra.resume === undefined) {
-    const tiers: {
-      user?: Partial<ReturnType<typeof parseTurnOptions>>;
-      project?: Partial<ReturnType<typeof parseTurnOptions>>;
-    } = {};
+    const tiers = resolvedTiers;
     const { loadUserConfig, loadProjectConfig, ConfigError } = await import("./config.js");
     try {
       const loaded = loadUserConfig();
@@ -277,6 +303,11 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
         prompt,
         __explicitPrompt: isExplicit,
       } as never);
+      const claudeSkillTokens = (effectiveTurnOpts as unknown as { __claudeSkillTokens?: string[] })
+        .__claudeSkillTokens;
+      if (claudeSkillTokens !== undefined && claudeSkillTokens.length > 0) {
+        preArgv.push(...claudeSkillTokens);
+      }
     }
     _validated = true;
   } catch (err) {
@@ -311,7 +342,17 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   // Delete HERDR_ENV before spawn
   delete (process.env as Record<string, string | undefined>).HERDR_ENV;
 
-  const deps = nodeRunnerDeps();
+  // D11: opt-in wall-clock budget. Precedence arg > project > user (no
+  // profile entry by ratification). 0 = explicit disable.
+  const timeoutSeconds =
+    extra.timeoutSeconds !== undefined
+      ? extra.timeoutSeconds
+      : ((resolvedTiers?.project as { timeout?: number } | undefined)?.timeout ??
+        (resolvedTiers?.user as { timeout?: number } | undefined)?.timeout);
+  const deps =
+    timeoutSeconds !== undefined && timeoutSeconds > 0
+      ? nodeRunnerDeps({ turnTimeoutMs: timeoutSeconds * 1000 })
+      : nodeRunnerDeps();
 
   // Signal handling
   const _currentProc: { signal: (sig: "SIGTERM" | "SIGKILL") => void } | null = null;

package/src/cli/skills-root.ts

@@ -0,0 +1,47 @@
+/**
+ * Skills registry resolution (issue #38): --skills names resolve against
+ * the caller's deployed root. The delegating agent's judgment picked the
+ * names; this only maps them to paths and refuses unknowns loudly -
+ * a typo silently loading nothing is the failure this prevents.
+ *
+ * Root: $HCN_SKILLS_ROOT, else ~/.agents/skills (the deployed shared
+ * registry; ~/.claude/skills symlinks to it, so claude's complement
+ * narrowing and pi's loads see the same set).
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ArgvRefusalError } from "../interpretation/refusal.js";
+
+export const skillsRoot = (): string =>
+  process.env.HCN_SKILLS_ROOT ?? join(homedir(), ".agents", "skills");
+
+const skillDir = (root: string, name: string): string => join(root, name);
+
+export const listKnownSkills = (): string[] => {
+  const root = skillsRoot();
+  if (!existsSync(root)) return [];
+  return readdirSync(root).filter((n) => {
+    try {
+      return statSync(skillDir(root, n)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+};
+
+export const resolveSkillNames = (names: readonly string[]): string[] => {
+  const root = skillsRoot();
+  const known = new Set(listKnownSkills());
+  const unknown = names.filter((n) => !known.has(n));
+  if (unknown.length > 0) {
+    throw new ArgvRefusalError({
+      issue: "unknown-tool-name",
+      harness: "claude",
+      option: "skills",
+      supported: known.size > 0 ? [[...known].join(", ")] : ["(registry is empty)"],
+      detail: `unknown skill name(s): ${unknown.join(", ")}`,
+    });
+  }
+  return names.map((n) => skillDir(root, n));
+};

package/src/execution/failure.ts

@@ -31,6 +31,7 @@ export const FAILURE_CLASSES = Object.freeze([
   "transport",
   "rejected",
   "native",
+  "timeout",
 ] as const);
 export type FailureClass = (typeof FAILURE_CLASSES)[number];
 
@@ -56,7 +57,7 @@ export interface FailureSummary {
 }
 
 export const retryableOf = (cls: FailureClass): boolean =>
-  cls !== "task" && cls !== "budget" && cls !== "rejected" && cls !== "native";
+  cls !== "task" && cls !== "budget" && cls !== "rejected" && cls !== "native" && cls !== "timeout";
 
 const messageFor = (cls: FailureClass, detail?: string): string => {
   switch (cls) {
@@ -76,6 +77,11 @@ const messageFor = (cls: FailureClass, detail?: string): string => {
       return `Transport failure${detail ? ` (${detail})` : ""} - retry or route to another provider`;
     case "rejected":
       return `Request rejected${detail ? ` (${detail})` : ""} - change options or harness`;
+    case "timeout":
+      // D11: hcn's wall-clock budget expired and the run was killed. The
+      // caller chose this number (arg or config); retrying unchanged will
+      // hit the same wall - retry only with a raised budget.
+      return `Timeout: run exceeded its wall-clock budget and was killed (SIGTERM, then SIGKILL after grace) - raise --timeout for this workload or split the task`;
     case "native":
       // D6: labeled NATIVE so it can never be confused with an hcn error.
       // The harness's own message follows verbatim; the process exit code
@@ -86,7 +92,14 @@ const messageFor = (cls: FailureClass, detail?: string): string => {
     default:
       return `Failure${detail ? ` (${detail})` : ""}`;
   }
-}; /** D6: a failure that belongs to the harness, not hcn. Carries the
+}; /** D11: the run outlived its caller-set wall-clock budget. */
+export const failureFromTimeout = (): FailureSummary => ({
+  class: "timeout",
+  retryable: false,
+  message: messageFor("timeout"),
+});
+
+/** D6: a failure that belongs to the harness, not hcn. Carries the
  * native stderr verbatim and the native exit code as data. */
 export const failureFromNative = (
   nativeExitCode: number | null,
@@ -173,6 +186,7 @@ const PRECEDENCE: Record<FailureClass, number> = {
   budget: 3,
   task: 3,
   transport: 4,
+  timeout: 3,
   // rejected stands alone (checked before precedence applies); native is
   // terminal-by-classification, never reduced into anything else.
   rejected: 0,

package/src/execution/stream-turn.ts

@@ -30,6 +30,7 @@ import {
   failureFromLimit,
   failureFromNative,
   failureFromRejected,
+  failureFromTimeout,
   failureFromTransport,
   reduceFailures,
 } from "./failure.js";
@@ -152,6 +153,13 @@ export async function* streamTurn(
     if (opts.passthrough !== undefined && opts.passthrough.length > 0) {
       argv = [...argv, "--", ...opts.passthrough];
     }
+    // issue #38: claude renders the skills allowlist as settings JSON at
+    // the argv tail (the complement-off form).
+    const claudeSkillTokens = (opts as unknown as { __claudeSkillTokens?: string[] })
+      .__claudeSkillTokens;
+    if (claudeSkillTokens !== undefined && claudeSkillTokens.length > 0) {
+      argv = [...argv, ...claudeSkillTokens];
+    }
     granularity = streamingGranularityOf(h, argv);
   } catch (e) {
     if (e instanceof ArgvRefusalError) {
@@ -434,7 +442,12 @@ export async function* streamTurn(
     }
     // Stall watchdog also implies a transport failure if not already present
     if (killedByWatchdog && failures.length === 0) {
-      const f = failureFromTransport(`stalled: ${watchdogReason ?? "inactivity"}`);
+      // D11: a wall-clock deadline kill is a timeout, not a stall - the
+      // run was not necessarily silent, it simply outlived its budget.
+      const f =
+        watchdogReason === "turn-deadline"
+          ? failureFromTimeout()
+          : failureFromTransport(`stalled: ${watchdogReason ?? "inactivity"}`);
       failures.push(f);
       yield { kind: "failure", ...f };
     }
@@ -442,7 +455,9 @@ export async function* streamTurn(
     let cause: ExitCause = state.limitSeen
       ? "limit"
       : killedByWatchdog && exitCode !== 0
-        ? "stall"
+        ? watchdogReason === "turn-deadline"
+          ? "killed" // D11: the run was killed on budget, not stalled
+          : "stall"
         : exitCode === 0
           ? "clean"
           : exitCode === null

package/src/interpretation/argv.ts

@@ -8,6 +8,7 @@ import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descr
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { ArgvRefusalError } from "./refusal.js";
 import { assertUsableSessionId } from "./session-id.js";
+import { renderSkillsSelection } from "./skills-selection.js";
 import { supportedBy } from "./support.js";
 import { renderToolSelection } from "./tool-selection.js";
 import { renderTurnOptions } from "./turn-options.js";
@@ -54,6 +55,11 @@ export interface TurnOptions {
   readonly prompt: string;
   readonly tools?: readonly string[];
   readonly excludeTools?: readonly string[];
+  /** Caller-directed skills allowlist: resolved absolute paths, one per
+   * skill. Rendering: pi loads each via --skill with discovery off;
+   * claude turns off the complement via skillOverrides settings; codex
+   * and muse refuse (structural - no per-skill surface). */
+  readonly skills?: readonly string[];
   readonly model?: string;
   readonly autonomy?: boolean;
   readonly effort?: string;
@@ -112,6 +118,9 @@ const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
     });
     tail.push(...rendered.tokens);
   }
+  if (opts.skills !== undefined && opts.skills.length > 0) {
+    tail.push(...renderSkillsSelection(h, opts.skills));
+  }
   return tail;
 };
 

package/src/interpretation/refusal.ts

@@ -33,6 +33,7 @@ export type RefusalOption =
   | TurnOptionKey
   | "tools"
   | "excludeTools"
+  | "skills"
   | "autonomy"
   | `discovery.${string}`;
 

package/src/interpretation/resolve-options.ts

@@ -54,6 +54,9 @@ const EXPRESSIBLE: Readonly<Record<ProfileKey, (h: HarnessDescriptor) => boolean
   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 {
@@ -155,12 +158,33 @@ export const resolveEffectiveOptions = (
       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) 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))) {
+    // 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;
     }

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/knowledge/claude-code.ts

@@ -161,6 +161,7 @@ export const claudeCode: HarnessDescriptor = deepFreeze({
   // 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.
+  skills: { loadFlag: null, overridesVia: "settings-skilloverrides" },
   tools: {
     includeFlag: "--allowedTools",
     excludeFlag: "--disallowedTools",

package/src/knowledge/codex.ts

@@ -119,6 +119,7 @@ export const codexCli: HarnessDescriptor = deepFreeze({
   // (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.
+  skills: null,
   tools: {
     includeFlag: null,
     excludeFlag: null,

package/src/knowledge/descriptor.ts

@@ -356,6 +356,13 @@ export interface HarnessDescriptor {
    * 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). */
+  /** Caller-directed skills allowlist surface (issue #38). pi: repeatable
+   * load flag. claude: per-name "off" overrides via settings JSON.
+   * codex/muse: null (structural gap - trust/config scoped only). */
+  readonly skills: {
+    readonly loadFlag: string | null;
+    readonly overridesVia: "settings-skilloverrides" | null;
+  } | null;
   readonly tools: {
     readonly includeFlag: string | null;
     readonly excludeFlag: string | null;

package/src/knowledge/muse.ts

@@ -116,6 +116,7 @@ export const museCode: HarnessDescriptor = deepFreeze({
   // 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.
+  skills: null,
   tools: {
     includeFlag: null,
     excludeFlag: null,

package/src/knowledge/pi.ts

@@ -122,6 +122,7 @@ export const piCli: HarnessDescriptor = deepFreeze({
   // 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.
+  skills: { loadFlag: "--skill", overridesVia: null },
   tools: {
     includeFlag: "--tools",
     excludeFlag: "--exclude-tools",