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

package/src/cli/run.ts

@@ -2,12 +2,9 @@ import type { HarnessEvent } from "../execution/events.js";
 import { nodeRunnerDeps } from "../execution/node-deps.js";
 import { KILL_GRACE_MS, redactArgv, streamTurn } from "../execution/stream-turn.js";
 import { buildLaunchArgv, buildResumeArgv } from "../interpretation/argv.js";
+import { composeEscalatedPrompt } from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
-import {
-  FloorExceededError,
-  type ProvenanceEntry,
-  resolveEffectiveOptions,
-} from "../interpretation/resolve-options.js";
+import { FloorExceededError, resolveEffectiveOptions } from "../interpretation/resolve-options.js";
 import { recognizeNativeSpelling, supportedBy } from "../interpretation/support.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { parseRunExtra, parseTurnOptions, resolvePromptAsync } from "./args.js";
@@ -186,16 +183,45 @@ 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;
-  if (extra.resume === undefined) {
-    const tiers: {
-      user?: Partial<ReturnType<typeof parseTurnOptions>>;
-      project?: Partial<ReturnType<typeof parseTurnOptions>>;
-    } = {};
+  const resolvedTiers: {
+    user?: Partial<ReturnType<typeof parseTurnOptions>>;
+    project?: Partial<ReturnType<typeof parseTurnOptions>>;
+  } = {};
+  // Config files load on EVERY run, launch or resume: the tiers feed the
+  // defaults profile on launch, and issue #41's escalateQuestions (a
+  // behavior instruction, not a turn option) resolves from them on resume
+  // too - otherwise a no-escalate session would flip its preamble on the
+  // answer turn. Resolution of TURN options stays launch-only.
+  const tiers = resolvedTiers;
+  {
     const { loadUserConfig, loadProjectConfig, ConfigError } = await import("./config.js");
     try {
       const loaded = loadUserConfig();
@@ -210,6 +236,8 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
       }
       throw configErr;
     }
+  }
+  if (extra.resume === undefined) {
     let resolved: ReturnType<typeof resolveEffectiveOptions>;
     try {
       resolved = resolveEffectiveOptions(h, { ...turnOpts, prompt } as never, tiers);
@@ -222,8 +250,6 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
       throw resErr;
     }
     const { provenance, unrenderable } = resolved;
-    resolvedProvenance = provenance;
-    resolvedUnrenderable = unrenderable;
     const { prompt: _p, ...rest } = resolved.options as { prompt: string };
     effectiveTurnOpts = rest as ReturnType<typeof parseTurnOptions>;
     // Provenance is diagnostic data like the spawn line - stderr in BOTH
@@ -242,12 +268,39 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     }
   }
 
+  // issue #41: question-escalation precedence arg > project > user >
+  // default-true (a behavior instruction, not a turn option - the
+  // default lives OUTSIDE the profile on purpose, per the spec). It
+  // applies on LAUNCH AND RESUME alike: it shapes each turn's prompt
+  // preamble and event stream, never a session setting.
+  const projectEscalate = (resolvedTiers.project as { escalateQuestions?: boolean } | undefined)
+    ?.escalateQuestions;
+  const userEscalate = (resolvedTiers.user as { escalateQuestions?: boolean } | undefined)
+    ?.escalateQuestions;
+  const escalateQuestions =
+    turnOpts.escalateQuestions !== undefined
+      ? turnOpts.escalateQuestions
+      : projectEscalate !== undefined
+        ? projectEscalate
+        : userEscalate !== undefined
+          ? userEscalate
+          : true;
+  const escalateTier =
+    turnOpts.escalateQuestions !== undefined
+      ? "arg"
+      : projectEscalate !== undefined
+        ? "project-config"
+        : userEscalate !== undefined
+          ? "user-config"
+          : "default";
+
   const fullOpts = {
     ...effectiveTurnOpts,
-    prompt,
+    prompt: composeEscalatedPrompt(prompt, escalateQuestions),
     cwd: extra.cwd,
     env: extra.env,
     resume: extra.resume,
+    escalateQuestions,
     ...(passthrough.length > 0 ? { passthrough } : {}),
     ...(isExplicit ? { __explicitPrompt: true as const } : {}),
   } as Parameters<typeof streamTurn>[1] & {
@@ -261,22 +314,30 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   let preArgv: string[] | null = null;
   try {
     if (fullOpts.resume) {
-      // Resume never carries profile/config resolution (launch-only rule),
-      // so it builds from the raw turn options.
+      // Resume never carries TURN-option profile resolution (launch-only
+      // rule), so it builds from the raw turn options; hcn-owned behavior
+      // (escalateQuestions preamble, timeout budget) still applies.
       preArgv = buildResumeArgv(h, {
         ...(turnOpts as object),
-        prompt,
+        prompt: fullOpts.prompt,
         sessionId: fullOpts.resume,
         __explicitPrompt: isExplicit,
       } as never);
     } else {
       // Launch builds from the RESOLVED options so the spawn line and the
-      // real argv agree.
+      // real argv agree. The prompt here is the COMPOSED one (escalation
+      // preamble included) - redactArgv masks by position, so an argv
+      // built from the raw prompt would leak it into the spawn line.
       preArgv = buildLaunchArgv(h, {
         ...(effectiveTurnOpts as object),
-        prompt,
+        prompt: fullOpts.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) {
@@ -299,19 +360,34 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   // since buildLaunchArgv now respects __explicitPrompt.
 
   if (preArgv) {
-    const redacted = redactArgv(preArgv, prompt);
+    const redacted = redactArgv(preArgv, fullOpts.prompt);
     if (!wantJson) {
       process.stderr.write(`spawn: ${redacted.join(" ")}\n`);
     } else {
       // In JSON mode, diagnostics to stderr only
       process.stderr.write(`spawn: ${redacted.join(" ")}\n`);
     }
+    // issue #41: the escalation mode rides stderr as provenance, like
+    // every other resolution the turn depends on.
+    process.stderr.write(
+      `provenance: escalateQuestions = ${escalateQuestions} (${escalateTier})\n`,
+    );
   }
 
   // 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;
@@ -372,7 +448,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
         renderEvent(event, state);
       }
       if (event.kind === "done") {
-        if (event.cause === "clean") exitCode = 0;
+        if (event.cause === "clean" || event.cause === "awaiting-input") exitCode = 0;
         else exitCode = 1;
         // If failure class is rejected? But done.cause for rejected would be failed? Still 1 per mapping, but refusal before spawn is 2.
         // The RFC says limit/auth ->1, transport ->1, refusal ->2 (already handled). So done non-clean =>1.

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/events.ts

@@ -17,7 +17,16 @@
 import type { CapabilityResult } from "../interpretation/capabilities.js";
 import type { FailureSummary } from "./failure.js";
 
-export type ExitCause = "clean" | "limit" | "crash" | "stall" | "killed" | "failed";
+export type ExitCause =
+  | "clean"
+  | "limit"
+  | "crash"
+  | "stall"
+  | "killed"
+  | "failed"
+  /** issue #41: the turn ended by asking (escalateQuestions) - a
+   * SUCCESSFUL turn (process exit 0); the caller resumes with the answer. */
+  | "awaiting-input";
 
 export type HarnessEvent =
   | {
@@ -31,6 +40,15 @@ export type HarnessEvent =
   | { readonly kind: "progress"; readonly label: string }
   | { readonly kind: "tool"; readonly name: string; readonly input?: unknown }
   | { readonly kind: "context"; readonly usedPct: number }
+  | {
+      /** issue #41: the worker asked the caller's user a question (the
+       * final message carried an hcn-question block). Structured-first:
+       * these fields ARE the question; prose renders from them. */
+      readonly kind: "question";
+      readonly question: string;
+      readonly options: readonly string[];
+      readonly recommended?: string;
+    }
   | { readonly kind: "limit"; readonly code: string; readonly message: string }
   | { readonly kind: "error"; readonly message: string }
   | ({ readonly kind: "failure" } & FailureSummary)

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

@@ -17,6 +17,7 @@ import {
 } from "../interpretation/argv.js";
 import { stdinPolicyOf } from "../interpretation/dimensions.js";
 import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 import { matcherOverridesOf } from "../knowledge/overrides.js";
@@ -30,6 +31,7 @@ import {
   failureFromLimit,
   failureFromNative,
   failureFromRejected,
+  failureFromTimeout,
   failureFromTransport,
   reduceFailures,
 } from "./failure.js";
@@ -101,6 +103,13 @@ export interface TurnRunOptions extends LaunchOptions {
    * normalized argv. Wrong-harness flags here fail in the harness itself
    * and surface as native errors - hcn never validates them. */
   readonly passthrough?: readonly string[];
+  /** issue #41: question escalation (behavior instruction, NOT a turn
+   * option - no flag ever reaches the harness). True (the default when
+   * undefined) prepends the protocol preamble and arms question-block
+   * detection; false prepends the state-the-assumption instruction and
+   * disarms detection. Applies on launch AND resume: it shapes each
+   * turn's prompt and event stream, never a session setting. */
+  readonly escalateQuestions?: boolean;
 }
 
 export async function* streamTurn(
@@ -111,6 +120,21 @@ export async function* streamTurn(
   const turnId = deps.turnId ?? `turn-${++turnCounter}`;
   const log = deps.log ?? (() => {});
 
+  // issue #41: compose the escalation preamble onto the prompt (the
+  // transport IS the prompt - no harness has native question conveyance)
+  // and arm detection in the true mode. Composition is idempotent, so a
+  // caller that already composed (the CLI does, for spawn-line truth)
+  // never double-prepends.
+  const escalateQuestions = opts.escalateQuestions !== false;
+  const effective: TurnRunOptions = {
+    ...opts,
+    prompt: composeEscalatedPrompt(opts.prompt, escalateQuestions),
+  };
+  // The turn's last assistant message - where the protocol says the
+  // hcn-question block lives. Tracked only when detection is armed.
+  let lastAssistantText: string | null = null;
+  let asked = false;
+
   // Validate env before building argv so an invalid env is a refusal, not a spawn
   if (opts.env !== undefined) {
     for (const [k, v] of Object.entries(opts.env)) {
@@ -133,7 +157,7 @@ export async function* streamTurn(
           harness: h.name,
           issue: refusal.issue,
           supported: refusal.supported,
-          argv: redactArgv([], opts.prompt),
+          argv: redactArgv([], effective.prompt),
         });
         yield { kind: "failure", ...failure };
         yield { kind: "done", exitCode: null, cause: "failed", failure };
@@ -146,11 +170,18 @@ export async function* streamTurn(
   let granularity: import("../knowledge/descriptor.js").StreamingGranularity;
   try {
     argv =
-      opts.resume === undefined
-        ? buildLaunchArgv(h, opts)
-        : buildResumeArgv(h, { ...opts, sessionId: opts.resume });
-    if (opts.passthrough !== undefined && opts.passthrough.length > 0) {
-      argv = [...argv, "--", ...opts.passthrough];
+      effective.resume === undefined
+        ? buildLaunchArgv(h, effective)
+        : buildResumeArgv(h, { ...effective, sessionId: effective.resume });
+    if (effective.passthrough !== undefined && effective.passthrough.length > 0) {
+      argv = [...argv, "--", ...effective.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) {
@@ -167,7 +198,7 @@ export async function* streamTurn(
       // No process spawned on a refusal - log rejected instead of spawn
       let argvForLog: string[] = [];
       try {
-        argvForLog = redactArgv([], opts.prompt);
+        argvForLog = redactArgv([], effective.prompt);
       } catch {}
       log({
         event: "rejected",
@@ -192,7 +223,7 @@ export async function* streamTurn(
     event: "spawn",
     turnId,
     harness: h.name,
-    argv: redactArgv(argv, opts.prompt),
+    argv: redactArgv(argv, effective.prompt),
     granularity,
     ...(matcherOverrides ? { matcherOverrides } : {}),
     ...(envKeys?.length ? { envKeys } : {}),
@@ -202,8 +233,8 @@ export async function* streamTurn(
   try {
     proc = deps.spawn(argv, {
       stdin: stdinPolicyOf(h) === "close-required" ? "close" : "inherit",
-      ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
-      ...(opts.env !== undefined ? { env: opts.env } : {}),
+      ...(effective.cwd !== undefined ? { cwd: effective.cwd } : {}),
+      ...(effective.env !== undefined ? { env: effective.env } : {}),
     });
   } catch (cause) {
     // Spawn failure is a transport failure, not merely a crash
@@ -224,7 +255,7 @@ export async function* streamTurn(
   }
 
   const queue = new AsyncChannel<HarnessEvent>();
-  const state = freshDecodeState(opts.resume ?? null);
+  const state = freshDecodeState(effective.resume ?? null);
   const stderrTail = new StderrTail();
   let killedByWatchdog = false;
   let exited = false;
@@ -333,6 +364,9 @@ export async function* streamTurn(
             // Directly from decode's rate_limit_event handling - track for reduction
             failures.push(event as unknown as FailureSummary);
           }
+          if (escalateQuestions && event.kind === "message" && event.role === "assistant") {
+            lastAssistantText = event.text;
+          }
           await queue.push(event);
         }
       }
@@ -348,6 +382,37 @@ export async function* streamTurn(
     }
   };
 
+  /** issue #41: scan the last assistant message for the hcn-question
+   * block. Structured-first - the block's fields become the event; no
+   * prose parsing. Runs after the pumps settle (the last message is only
+   * last then) and only when detection is armed (escalateQuestions
+   * true). A malformed block surfaces as an error event, never a silent
+   * no-op. */
+  const emitQuestionIfAsked = async (): Promise<void> => {
+    if (!escalateQuestions || lastAssistantText === null) return;
+    const detection = detectQuestionBlock(lastAssistantText);
+    if (detection === null) return;
+    if ("malformed" in detection) {
+      await queue.push({ kind: "error", message: detection.malformed });
+      return;
+    }
+    log({
+      event: "question",
+      turnId,
+      harness: h.name,
+      options: detection.block.options.length,
+    });
+    asked = true;
+    await queue.push({
+      kind: "question",
+      question: detection.block.question,
+      options: detection.block.options,
+      ...(detection.block.recommended !== undefined
+        ? { recommended: detection.block.recommended }
+        : {}),
+    });
+  };
+
   const pumpStderr = async (): Promise<void> => {
     const lines = new LineBuffer();
     for await (const chunk of proc.stderr) {
@@ -405,7 +470,9 @@ export async function* streamTurn(
     observePump("stdout", pumpStdout()),
     observePump("stderr", pumpStderr()),
   ]);
-  void Promise.all([proc.exited, pumpSettlements]).then(() => queue.close());
+  void Promise.all([proc.exited, pumpSettlements])
+    .then(() => emitQuestionIfAsked())
+    .then(() => queue.close());
 
   try {
     for await (const event of queue) yield event;
@@ -434,7 +501,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,9 +514,13 @@ 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"
+          ? asked
+            ? "awaiting-input" // issue #41: asking SUCCEEDED the turn
+            : "clean"
           : exitCode === null
             ? "killed"
             : "crash";

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;
@@ -63,6 +69,11 @@ export interface TurnOptions {
   readonly write?: boolean;
   readonly shell?: boolean;
   readonly maxSteps?: number;
+  /** issue #41: question escalation - a BEHAVIOR INSTRUCTION, not a turn
+   * option. It never renders into any harness argv; the CLI layer turns
+   * it into the prompt preamble and arms question-block detection.
+   * Undefined means the default: true. */
+  readonly escalateQuestions?: boolean;
   /** Internal: set by CLI when prompt came from --prompt/--prompt-file to bypass leading '-' guard */
   readonly __explicitPrompt?: boolean;
 }
@@ -112,6 +123,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;
 };