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

package/src/interpretation/question.ts

@@ -0,0 +1,137 @@
+/**
+ * Question escalation (issue #41): the protocol that lets a headless
+ * worker ask the CALLER's user a question. Transport is the prompt - no
+ * harness ships native question conveyance - so hcn prepends a protocol
+ * contract (escalateQuestions true, the default) or the state-the-
+ * assumption instruction (false). The worker's final message then carries
+ * a fenced `hcn-question` block; detection is structured-first (fields
+ * parsed from the block, prose rendered downstream from them).
+ *
+ * Ratified design note (2026-08-19): autonomy and escalateQuestions are
+ * independent flags carving the same substrate by ORIGIN - autonomy =
+ * interrupts the harness raises (permission gates), escalateQuestions =
+ * interrupts the model raises (judgment gaps). The true-mode preamble
+ * must therefore never conflate asking with permission: "you may ask" is
+ * never "you lack permission." Both preambles open with the same marker
+ * so composition is idempotent (a composed prompt is never re-composed).
+ */
+
+/** The shared first line of both preambles - also the idempotence marker
+ * for composeEscalatedPrompt. */
+export const QUESTION_PREAMBLE_MARKER = "[hcn question protocol]";
+
+export const ESCALATION_PREAMBLE = `${QUESTION_PREAMBLE_MARKER}
+You are running headless: no one is watching this session live, but a caller relays answers between turns. This protocol never changes your permissions - asking is not how you obtain permission, and it never removes any permission this run already has. Use the tools you have exactly as granted.
+If and only if a genuine decision you cannot make defensibly blocks correct progress, ask by ending your turn: emit one fenced code block tagged hcn-question, as the last content of your final message, containing a single JSON object:
+
+\`\`\`hcn-question
+{"question": "<the decision you need made>", "options": ["<option 1>", "<option 2>"], "recommended": "<one of options>"}
+\`\`\`
+
+Say nothing after the block. Your turn ends there; the caller's user will answer, and your next turn continues from that answer. For every choice you can make defensibly yourself, do not ask - decide, act, and state the decision you made.`;
+
+export const NO_ESCALATION_PREAMBLE = `${QUESTION_PREAMBLE_MARKER}
+You are running headless and no one will answer you in this session. Never ask a question, never request input or confirmation, and never end your turn awaiting a reply. When a decision is ambiguous, pick the most defensible reading, state the assumption you proceeded under in one sentence, and continue to completion.`;
+
+/** Compose the transport preamble onto a prompt. Idempotent: a prompt
+ * that already carries either preamble (re-composition on resume, a
+ * caller that pre-composed) passes through unchanged. */
+export const composeEscalatedPrompt = (prompt: string, escalate: boolean): string =>
+  prompt.startsWith(QUESTION_PREAMBLE_MARKER)
+    ? prompt
+    : `${escalate ? ESCALATION_PREAMBLE : NO_ESCALATION_PREAMBLE}\n\n${prompt}`;
+
+/** The structured question a worker asks (the block's fields). */
+export interface QuestionBlock {
+  readonly question: string;
+  readonly options: readonly string[];
+  readonly recommended?: string;
+}
+
+/** Detection result: a parsed block, a named malformation (the worker
+ * tried to ask but botched the shape - surfaced, never swallowed), or
+ * null when no hcn-question block is present. */
+export type QuestionDetection = { readonly block: QuestionBlock } | { readonly malformed: string };
+
+/** One fenced-block candidate: the body text plus whether the fence was
+ * properly closed (an unclosed opener at end-of-text is still examined -
+ * the most likely formatting slip is forgetting the closing fence). */
+interface FenceCandidate {
+  readonly body: string;
+  readonly closed: boolean;
+}
+
+const FENCE_OPEN = /(?:^|\n)[ \t]*```[ \t]*hcn-question[ \t]*(?=\n)/g;
+
+/** All hcn-question fence bodies in a text, in order. */
+const fenceBodies = (text: string): FenceCandidate[] => {
+  const out: FenceCandidate[] = [];
+  FENCE_OPEN.lastIndex = 0;
+  for (let m = FENCE_OPEN.exec(text); m !== null; m = FENCE_OPEN.exec(text)) {
+    const bodyStart = m.index + m[0].length;
+    // The closing fence may be indented like the opener (probe evidence:
+    // indented blocks occur), so match newline + optional spaces + ```.
+    const close = text.slice(bodyStart).search(/\n[ \t]*```/);
+    if (close === -1) {
+      // Unclosed fence: the body runs to end-of-text. Only meaningful
+      // when nothing follows the opener - take it as a candidate anyway.
+      out.push({ body: text.slice(bodyStart), closed: false });
+      break;
+    }
+    const bodyEnd = bodyStart + close;
+    out.push({ body: text.slice(bodyStart, bodyEnd), closed: true });
+    FENCE_OPEN.lastIndex = bodyEnd;
+  }
+  return out;
+};
+
+const parseBlock = (body: string): QuestionDetection => {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(body);
+  } catch (e) {
+    return { malformed: `hcn-question block is not valid JSON: ${(e as Error).message}` };
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { malformed: "hcn-question block must be a JSON object" };
+  }
+  const obj = raw as Record<string, unknown>;
+  const { question, options, recommended } = obj;
+  if (typeof question !== "string" || question.trim() === "") {
+    return { malformed: 'hcn-question block field "question" must be a non-empty string' };
+  }
+  if (
+    !Array.isArray(options) ||
+    options.length === 0 ||
+    options.some((o) => typeof o !== "string" || o.trim() === "")
+  ) {
+    return {
+      malformed: 'hcn-question block field "options" must be an array of non-empty strings',
+    };
+  }
+  if (recommended !== undefined && typeof recommended !== "string") {
+    return { malformed: 'hcn-question block field "recommended" must be a string' };
+  }
+  return {
+    block: {
+      question,
+      options,
+      ...(recommended !== undefined ? { recommended } : {}),
+    },
+  };
+};
+
+/** Detect the hcn-question block in a message text. The LAST block wins
+ * (the protocol makes the block the turn's final content; a corrected
+ * re-emit supersedes an earlier one). An empty candidate body (a bare
+ * unclosed opener with nothing after it) is not a detection. */
+export const detectQuestionBlock = (text: string): QuestionDetection | null => {
+  const candidates = fenceBodies(text);
+  for (let i = candidates.length - 1; i >= 0; i--) {
+    const candidate = candidates[i];
+    if (candidate === undefined) continue;
+    if (candidate.body.trim() === "") continue;
+    return parseBlock(candidate.body);
+  }
+  return null;
+};

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",

package/src/knowledge/profile.ts

@@ -28,6 +28,26 @@ 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.
 } as const);
 
 export type ProfileKey = keyof typeof DEFAULT_TURN_PROFILE;