@dungle-scrubs/harness-cli-normalizer 0.4.5 → 0.5.0

package/src/cli/provenance.ts

@@ -0,0 +1,19 @@
+import type { ProvenanceEntry } from "../interpretation/resolve-options.js";
+
+export const writeProvenance = (
+  harnessName: string,
+  provenance: readonly ProvenanceEntry[],
+  unrenderable: readonly string[],
+): void => {
+  if (provenance.length === 0 && unrenderable.length === 0) return;
+  for (const entry of provenance) {
+    process.stderr.write(
+      `provenance: ${entry.key} = ${JSON.stringify(entry.value)} (${entry.tier})\n`,
+    );
+  }
+  for (const key of unrenderable) {
+    process.stderr.write(
+      `divergence: profile ${JSON.stringify(key)} not expressible on ${harnessName}; harness default applies\n`,
+    );
+  }
+};

package/src/cli/refuse.ts

@@ -0,0 +1,50 @@
+import { failureFromRejected } from "../execution/failure.js";
+import type { ArgvRefusalError, RefusalIssue } from "../interpretation/refusal.js";
+import { writeEventNdjson } from "./render.js";
+
+export interface Refusal {
+  readonly message: string;
+  readonly issue: RefusalIssue;
+  readonly option?: ArgvRefusalError["option"];
+  readonly facet?: ArgvRefusalError["facet"];
+  readonly supported?: readonly string[];
+  readonly supportedBy?: ArgvRefusalError["supportedBy"];
+  readonly hint?: string;
+  readonly trailer?: readonly string[];
+}
+
+export const refusalOf = (err: ArgvRefusalError): Refusal => ({
+  message: err.message,
+  issue: err.issue,
+  option: err.option,
+  facet: err.facet,
+  supported: err.supported,
+  supportedBy: err.supportedBy,
+  hint: err.hint,
+});
+
+export const refuse = (r: Refusal, json: boolean): void => {
+  process.stderr.write(`${r.message}\n`);
+  if (r.hint) process.stderr.write(`hint: ${r.hint}\n`);
+  if (r.supportedBy?.length) {
+    process.stderr.write(
+      `supported on: ${r.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
+    );
+  }
+  if (r.supported?.length) process.stderr.write(`supported: ${r.supported.join(", ")}\n`);
+  for (const line of r.trailer ?? []) process.stderr.write(`${line}\n`);
+  if (json) {
+    const summary = failureFromRejected({
+      issue: r.issue,
+      option: r.option,
+      facet: r.facet,
+      supported: r.supported,
+      supportedBy: r.supportedBy,
+      hint: r.hint,
+      detail: r.message,
+    });
+    writeEventNdjson({ kind: "failure", ...summary });
+    writeEventNdjson({ kind: "done", exitCode: null, cause: "failed", failure: summary });
+  }
+  process.exitCode = 2;
+};

package/src/cli/run.ts

@@ -1,72 +1,19 @@
 import { existsSync } from "node:fs";
 import type { HarnessEvent } from "../execution/events.js";
-import { failureFromRejected } from "../execution/failure.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 type { RefusalIssue } from "../interpretation/refusal.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 import { FloorExceededError, resolveEffectiveOptions } from "../interpretation/resolve-options.js";
 import { storePath } from "../interpretation/store.js";
 import { recognizeNativeSpelling, supportedBy } from "../interpretation/support.js";
 import { defaultDescriptors } from "../knowledge/overrides.js";
 import { parseRunExtra, parseTurnOptions, resolvePromptAsync } from "./args.js";
+import { refusalOf, refuse } from "./refuse.js";
 import { createRenderState, renderEvent, writeEventNdjson } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
 
-/** One shape for every hcn-side refusal. Stderr keeps the prose (message,
- * hint, support lists, usage pointer); under --json the same fields also
- * ride stdout as a `failure` event plus a `done`, so a stream reader never
- * meets an empty stream on exit 2. */
-interface Refusal {
-  readonly message: string;
-  readonly issue: RefusalIssue;
-  readonly option?: ArgvRefusalError["option"];
-  readonly facet?: ArgvRefusalError["facet"];
-  readonly supported?: readonly string[];
-  readonly supportedBy?: ArgvRefusalError["supportedBy"];
-  readonly hint?: string;
-  /** Plain stderr lines written after the structured ones. */
-  readonly trailer?: readonly string[];
-}
-
-const refusalOf = (err: ArgvRefusalError): Refusal => ({
-  message: err.message,
-  issue: err.issue,
-  option: err.option,
-  facet: err.facet,
-  supported: err.supported,
-  supportedBy: err.supportedBy,
-  hint: err.hint,
-});
-
-const refuse = (r: Refusal, json: boolean): void => {
-  process.stderr.write(`${r.message}\n`);
-  if (r.hint) process.stderr.write(`hint: ${r.hint}\n`);
-  if (r.supportedBy?.length) {
-    process.stderr.write(
-      `supported on: ${r.supportedBy.map((e) => `${e.harness} (${e.spelling})`).join(", ")}\n`,
-    );
-  }
-  if (r.supported?.length) process.stderr.write(`supported: ${r.supported.join(", ")}\n`);
-  for (const line of r.trailer ?? []) process.stderr.write(`${line}\n`);
-  if (json) {
-    const summary = failureFromRejected({
-      issue: r.issue,
-      option: r.option,
-      facet: r.facet,
-      supported: r.supported,
-      supportedBy: r.supportedBy,
-      hint: r.hint,
-      detail: r.message,
-    });
-    writeEventNdjson({ kind: "failure", ...summary });
-    writeEventNdjson({ kind: "done", exitCode: null, cause: "failed", failure: summary });
-  }
-  process.exitCode = 2;
-};
-
 export const run = async (harnessName: string, rawArgs: string[]): Promise<void> => {
   const h = resolveHarness(harnessName);
 
@@ -238,7 +185,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   if (rawSkills !== undefined && rawSkills.length > 0) {
     try {
       const { resolveSkillNames, listKnownSkills } = await import("./skills-root.js");
-      const resolvedSkills = resolveSkillNames(rawSkills);
+      const resolvedSkills = resolveSkillNames(rawSkills, h.name);
       const claudeTokens: string[] = [];
       if (h.name === "claude") {
         const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
@@ -295,6 +242,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
         refuse({ message: resErr.message, issue: "invalid-tool-grant" }, wantJson);
         return;
       }
+      if (resErr instanceof ArgvRefusalError) {
+        refuse(refusalOf(resErr), wantJson);
+        return;
+      }
       throw resErr;
     }
     const { provenance, unrenderable } = resolved;
@@ -302,30 +253,8 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     effectiveTurnOpts = rest as ReturnType<typeof parseTurnOptions>;
     // Provenance is diagnostic data like the spawn line - stderr in BOTH
     // render modes, never stdout (stdout carries the NDJSON contract).
-    if (provenance.length > 0 || unrenderable.length > 0) {
-      for (const entry of provenance) {
-        process.stderr.write(
-          `provenance: ${entry.key} = ${JSON.stringify(entry.value)} (${entry.tier})\n`,
-        );
-      }
-      for (const key of unrenderable) {
-        process.stderr.write(
-          `divergence: profile ${JSON.stringify(key)} not expressible on ${h.name}; harness default applies\n`,
-        );
-      }
-      // issue #48 (ratified): when claude's instruction-files isolation
-      // rides (the --setting-sources project spelling), surface its known
-      // cost as a divergence line - legal to use, priced in stderr.
-      if (
-        h.name === "claude" &&
-        (resolved.options as { discovery?: { instructionFiles?: boolean } }).discovery
-          ?.instructionFiles === false
-      ) {
-        process.stderr.write(
-          "divergence: setting-sources isolation also skips hooks, LSP and keychain reads on claude - weighed, not refused\n",
-        );
-      }
-    }
+    const { writeProvenance } = await import("./provenance.js");
+    writeProvenance(h.name, provenance, unrenderable);
   }
 
   // issue #41: question-escalation precedence arg > project > user >
@@ -430,12 +359,12 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     // all refuses inside buildLaunchArgv below, so a throw here is left
     // to that path.
     const grant = (fullOpts.resume ? turnOpts : effectiveTurnOpts).tools;
-    if (grant !== undefined && grant.length > 0 && !h.tools.includeIsStrictAllowlist) {
+    if (grant !== undefined && grant.length > 0) {
       try {
         const { renderToolSelection } = await import("../interpretation/tool-selection.js");
-        const { unmapped } = renderToolSelection(h, { include: [...grant] });
-        if (unmapped.length > 0) {
-          process.stderr.write(`provenance: unmapped tools = ${JSON.stringify(unmapped)}\n`);
+        const { passthrough } = renderToolSelection(h, { include: [...grant] });
+        if (passthrough.length > 0) {
+          process.stderr.write(`provenance: native tools = ${JSON.stringify(passthrough)}\n`);
         }
       } catch {
         // refused below with the structured message
@@ -490,7 +419,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
   const _currentProc: { signal: (sig: "SIGTERM" | "SIGKILL") => void } | null = null;
   // We'll need to track the spawned process via deps.signal; but streamTurn owns process handle.
   // Instead we intercept deps.signal via a wrapper that captures proc.
-  // Simpler: use deps directly and handle SIGINT by calling process.kill? But spec says via injected signal.
+  // Simpler: use deps directly and handle SIGINT via injected signal.
   // We'll create a wrapper deps where signal captures last proc.
   let lastProc: import("../execution/deps.js").SpawnedProcess | null = null;
   const originalSignal = deps.signal;
@@ -509,6 +438,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
 
   const abortController = new AbortController();
   let interrupted = false;
+  let escalationTimer: ReturnType<typeof setTimeout> | null = null;
   const onSig = async () => {
     if (interrupted) return;
     interrupted = true;
@@ -516,16 +446,15 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     if (lastProc) {
       try {
         wrappedDeps.signal(lastProc, "SIGTERM");
-        await new Promise<void>((resolve) => {
-          setTimeout(() => {
-            if (lastProc) {
-              try {
-                wrappedDeps.signal(lastProc, "SIGKILL");
-              } catch {}
-            }
-            resolve();
-          }, KILL_GRACE_MS);
-        });
+        escalationTimer = setTimeout(() => {
+          if (lastProc) {
+            try {
+              wrappedDeps.signal(lastProc, "SIGKILL");
+            } catch {}
+          }
+          escalationTimer = null;
+        }, KILL_GRACE_MS);
+        escalationTimer.unref?.();
       } catch {}
     }
   };
@@ -591,6 +520,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     process.off("SIGTERM", onSig);
     return;
   } finally {
+    if (escalationTimer !== null) {
+      clearTimeout(escalationTimer);
+      escalationTimer = null;
+    }
     process.off("SIGINT", onSig);
     process.off("SIGTERM", onSig);
   }

package/src/cli/session.ts

@@ -3,6 +3,8 @@ import { createInterface } from "node:readline/promises";
 import { nodeRunnerDeps } from "../execution/node-deps.js";
 import { CLOSE_GRACE_MS, openSession } from "../execution/open-session.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
 import { createRenderState, renderEvent } from "./render.js";
 import { resolveHarness } from "./resolve-harness.js";
 
@@ -12,9 +14,8 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   // session mode is available the moment its descriptor declares one.
   const h = resolveHarness(harnessName);
   if (h.sessionMode === null) {
-    const supported = ["claude", "codex", "pi", "muse"]
-      .map((name) => resolveHarness(name))
-      .filter((d) => d.sessionMode !== null)
+    const supported = Object.values(defaultDescriptors())
+      .filter((d): d is HarnessDescriptor => d !== undefined && d.sessionMode !== null)
       .map((d) => d.name);
     const err = new ArgvRefusalError({
       issue: "no-session-mode",

package/src/cli/skills-root.ts

@@ -12,6 +12,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
+import type { HarnessName } from "../knowledge/descriptor.js";
 
 export const skillsRoot = (): string =>
   process.env.HCN_SKILLS_ROOT ?? join(homedir(), ".agents", "skills");
@@ -30,16 +31,22 @@ export const listKnownSkills = (): string[] => {
   });
 };
 
-export const resolveSkillNames = (names: readonly string[]): string[] => {
+export const resolveSkillNames = (
+  names: readonly string[],
+  harness: HarnessName = "claude",
+): 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",
+      issue: "invalid-option-value",
+      harness,
       option: "skills",
-      supported: known.size > 0 ? [[...known].join(", ")] : ["(registry is empty)"],
+      supported:
+        known.size > 0
+          ? [`registry at ${root}`, [...known].join(", ")]
+          : [`registry at ${root} (empty)`],
       detail: `unknown skill name(s): ${unknown.join(", ")}`,
     });
   }

package/src/execution/decode.ts

@@ -69,10 +69,11 @@ export const decodeParsed = (
   const decoded = decodeIdentity(h, raw, state.lastSeenId, state.requestedId);
   if (decoded.sessionId !== null) state.lastSeenId = decoded.sessionId;
   if (decoded.identity !== null) {
+    const authority = state.requestedId !== null ? "caller-assigned" : "harness-minted";
     events.push({
       kind: "identity",
       sessionId: decoded.identity,
-      authority: h.identity.authority,
+      authority,
       capabilities: capabilities(),
     });
   } else if (decoded.outcome === "malformed" || decoded.outcome === "rotated") {

package/src/execution/deps.ts

@@ -1,6 +1,6 @@
 /**
  * Injected runtime primitives (D-005): the execution layer never imports
- * child_process, never calls process.kill, and never reads a wall clock -
+ * child_process, never signals the process directly, and never reads a wall clock -
  * spawn, clock, and signalling arrive as data so Node/Bun is a real
  * portability boundary and tests run against fakes deterministically.
  */

package/src/execution/failure.ts

@@ -13,8 +13,14 @@
  * options or a different harness, not a different model.
  */
 
+import { detectAuthFailureInLine, detectTransportInLine } from "../interpretation/limits.js";
 import type { RefusalIssue } from "../interpretation/refusal.js";
-import type { AuthFailureKind, DiscoveryFacet, LimitCode } from "../knowledge/descriptor.js";
+import type {
+  AuthFailureKind,
+  DiscoveryFacet,
+  HarnessDescriptor,
+  LimitCode,
+} from "../knowledge/descriptor.js";
 
 export const FAILURE_CLASSES = Object.freeze([
   "rate-limit",
@@ -131,6 +137,16 @@ export const failureFromAuth = (kind: AuthFailureKind): FailureSummary => ({
   authKind: kind,
 });
 
+/** A terminal error the harness reported on its stream: classify by what
+ * it says. An auth wall or a transport fault reached no verdict on the
+ * work (retryable); anything else is the model's own failure (task). */
+export const failureFromTerminalError = (h: HarnessDescriptor, message: string): FailureSummary => {
+  const auth = detectAuthFailureInLine(h, message);
+  if (auth !== null) return failureFromAuth(auth);
+  if (detectTransportInLine(message)) return failureFromTransport(message);
+  return failureFromTask(message);
+};
+
 export const failureFromTask = (detail?: string): FailureSummary => ({
   class: "task",
   retryable: false,

package/src/execution/index.ts

@@ -4,8 +4,8 @@
  * It exposes openSession() and streamTurn(), which drive a CLI process via
  * injected {spawn, clock, signal} primitives and emit HarnessEvent values.
  * This module knows nothing about any chat protocol. Because it must run
- * identically on Node and Bun, it never imports child_process and never calls
- * process.kill directly outside the node-deps adapter - all process I/O and
+ * identically on Node and Bun, it never imports child_process and never
+ * signals the process directly outside the node-deps adapter - all process I/O and
  * signalling flows through the injected primitives.
  */
 export { AsyncChannel } from "./channel.js";

package/src/execution/open-session.ts

@@ -15,7 +15,11 @@
  */
 import { buildSessionArgv } from "../interpretation/argv.js";
 import { capabilitiesOf } from "../interpretation/capabilities.js";
-import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import {
+  detectAuthFailureInLine,
+  detectLimitInLine,
+  detectTransportInLine,
+} from "../interpretation/limits.js";
 import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
 import {
   encodeSessionInput,
@@ -28,7 +32,14 @@ import { decodeParsed, freshDecodeState } from "./decode.js";
 import type { RunnerDeps, SpawnedProcess } from "./deps.js";
 import type { ExitCause, HarnessEvent } from "./events.js";
 import type { FailureSummary } from "./failure.js";
-import { failureFromAuth, failureFromLimit, reduceFailures } from "./failure.js";
+import {
+  failureFromAuth,
+  failureFromLimit,
+  failureFromTask,
+  failureFromTerminalError,
+  failureFromTransport,
+  reduceFailures,
+} from "./failure.js";
 import { LineBuffer } from "./lines.js";
 import { KILL_GRACE_MS, PIPE_GRACE_MS, redactArgv, StderrTail } from "./stream-turn.js";
 
@@ -210,6 +221,9 @@ export const openSession = (
     if (detection === null) return;
     if ("malformed" in detection) {
       activeTurn?.push({ kind: "error", message: detection.malformed });
+      const failure = failureFromTask(`malformed hcn-question block: ${detection.malformed}`);
+      turnFailures.push(failure);
+      void activeTurn?.push({ kind: "failure", ...failure });
       return;
     }
     turnAsked = true;
@@ -240,7 +254,10 @@ export const openSession = (
     // Every failure was already emitted as an event through pushFailure;
     // the turn's done carries the reduced summary, as streamTurn's does.
     const reduced = reduceFailures(turnFailures);
-    if (reduced !== undefined) done = { ...done, failure: reduced };
+    if (reduced !== undefined) {
+      if (done.cause === "clean") done = { ...done, cause: "failed", failure: reduced };
+      else done = { ...done, failure: reduced };
+    }
     activeTurn.push(done);
     activeTurn.close();
     log({
@@ -287,6 +304,15 @@ export const openSession = (
     return routeEvent({ kind: "failure", ...f });
   };
 
+  /** A decoded event other than a failure: a terminal error also records
+   * the failure it stands for, the way streamTurn does. */
+  const routeDecoded = async (event: HarnessEvent): Promise<void> => {
+    await routeEvent(event);
+    if (event.kind === "error" && event.terminal === true) {
+      await pushFailure(failureFromTerminalError(h, event.message));
+    }
+  };
+
   const pumpStdout = async (): Promise<void> => {
     const lines = new LineBuffer();
     const matches = (
@@ -351,7 +377,7 @@ export const openSession = (
               await routeEvent({
                 kind: "identity",
                 sessionId: announced,
-                authority: h.identity.authority,
+                authority: "harness-minted",
                 capabilities: capabilitiesOf(h, opts.model ?? "", "headless-session"),
               });
             }
@@ -361,7 +387,7 @@ export const openSession = (
               await routeEvent({
                 kind: "identity",
                 sessionId: announced,
-                authority: h.identity.authority,
+                authority: "caller-assigned",
                 capabilities: capabilitiesOf(h, opts.model ?? "", "headless-session"),
               });
             }
@@ -392,7 +418,7 @@ export const openSession = (
         // still track resultError here to classify the done cause.
         for (const event of events) {
           if (event.kind === "failure") await pushFailure(summaryOf(event));
-          else await routeEvent(event);
+          else await routeDecoded(event);
         }
         if (parsed.is_error === true) resultError = true;
         endTurn({
@@ -404,7 +430,7 @@ export const openSession = (
       }
       for (const event of events) {
         if (event.kind === "failure") await pushFailure(summaryOf(event));
-        else await routeEvent(event);
+        else await routeDecoded(event);
       }
     };
     for await (const chunk of proc.stdout) {

package/src/execution/stream-turn.ts

@@ -16,7 +16,11 @@ import {
   streamingGranularityOf,
 } from "../interpretation/argv.js";
 import { stdinPolicyOf } from "../interpretation/dimensions.js";
-import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import {
+  detectAuthFailureInLine,
+  detectLimitInLine,
+  detectTransportInLine,
+} from "../interpretation/limits.js";
 import { composeEscalatedPrompt, detectQuestionBlock } from "../interpretation/question.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
@@ -32,6 +36,7 @@ import {
   failureFromNative,
   failureFromRejected,
   failureFromTask,
+  failureFromTerminalError,
   failureFromTimeout,
   failureFromTransport,
   reduceFailures,
@@ -312,6 +317,9 @@ export async function* streamTurn(
 
   const failures: FailureSummary[] = [];
   const pushFailure = async (f: FailureSummary): Promise<void> => {
+    // Suppress a failure identical in class and message to the previous one
+    const prev = failures[failures.length - 1];
+    if (prev !== undefined && prev.class === f.class && prev.message === f.message) return;
     failures.push(f);
     await queue.push({ kind: "failure", ...f });
   };
@@ -426,7 +434,7 @@ export async function* streamTurn(
       }
       if (event.kind === "error") {
         await queue.push(event);
-        if (event.terminal === true) await pushFailure(failureFromTask(event.message));
+        if (event.terminal === true) await pushFailure(failureFromTerminalError(h, event.message));
         return;
       }
       if (escalateQuestions && event.kind === "message" && event.role === "assistant") {
@@ -468,6 +476,7 @@ export async function* streamTurn(
     if (detection === null) return;
     if ("malformed" in detection) {
       await queue.push({ kind: "error", message: detection.malformed });
+      await pushFailure(failureFromTask(`malformed hcn-question block: ${detection.malformed}`));
       return;
     }
     log({
@@ -585,10 +594,13 @@ export async function* streamTurn(
       !state.limitSeen
     ) {
       const tailForNative = stderrTail.snapshot();
+      const transportLine = tailForNative.find((line) => detectTransportInLine(line));
       const f =
-        tailForNative.length > 0
-          ? failureFromNative(exitCode, tailForNative)
-          : failureFromTransport(`nonzero exit ${exitCode}`);
+        transportLine !== undefined
+          ? failureFromTransport(transportLine)
+          : tailForNative.length > 0
+            ? failureFromNative(exitCode, tailForNative)
+            : failureFromTransport(`nonzero exit ${exitCode}`);
       failures.push(f);
       // Need to emit this failure before done, even though queue is closed
       yield { kind: "failure", ...f };
@@ -624,10 +636,10 @@ export async function* streamTurn(
                 : "crash";
     const reduced = reduceFailures(failures);
     if (reduced && cause === "clean") cause = "failed";
-    // A work-verdict failure (the model ran out of steps, or ended its
-    // turn in error) is not a harness crash even when the process exits
-    // nonzero: the cause is failed and the real exit code rides along.
-    if ((reduced?.class === "budget" || reduced?.class === "task") && cause === "crash") {
+    // A classified failure other than native on a nonzero exit is a failed
+    // turn, not a crash: the failure taxonomy already captured the reason.
+    // Crash stays for unclassified exits and native failures.
+    if (reduced && reduced.class !== "native" && cause === "crash") {
       cause = "failed";
     }
     const tail = stderrTail.snapshot();

package/src/interpretation/argv.ts

@@ -83,6 +83,9 @@ export interface TurnOptions {
   readonly escalateQuestions?: boolean;
   /** Internal: set by CLI when prompt came from --prompt/--prompt-file to bypass leading '-' guard */
   readonly __explicitPrompt?: boolean;
+  /** toolMap extensible vocabulary per harness (issue toolMap) */
+  readonly toolMap?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  readonly access?: "read" | "write";
 }
 
 export interface ResumeOptions extends TurnOptions {
@@ -124,9 +127,11 @@ const turnTail = (h: HarnessDescriptor, opts: TurnOptions): string[] => {
     tail.push(h.autonomy.flag);
   }
   if (opts.tools !== undefined || opts.excludeTools !== undefined) {
+    const perHarnessMap = opts.toolMap?.[h.name];
     const rendered = renderToolSelection(h, {
       include: opts.tools,
       exclude: opts.excludeTools,
+      toolMap: perHarnessMap,
     });
     tail.push(...rendered.tokens);
   }
@@ -188,10 +193,13 @@ export interface SessionOptions {
 
 export const buildSessionArgv = (h: HarnessDescriptor, opts: SessionOptions): string[] => {
   if (!h.sessionMode) {
+    const supported = Object.values(defaultDescriptors())
+      .filter((d): d is HarnessDescriptor => d !== undefined && d.sessionMode !== null)
+      .map((d) => d.name);
     throw new ArgvRefusalError({
       issue: "no-session-mode",
       harness: h.name,
-      supported: ["session is available where sessionMode is declared"],
+      supported,
     });
   }
   refuseUnusableSessionId(h, opts.sessionId);

package/src/interpretation/content.ts

@@ -130,10 +130,14 @@ const pi = (r: Record<string, unknown>): ContentEvent[] => {
       // an expired minimax token: empty content, stopReason error, clean
       // exit). Without this the failure is invisible - a silent empty turn.
       if (message.stopReason === "error") {
+        const msg =
+          typeof message.errorMessage === "string"
+            ? `pi turn ended with stopReason error: ${message.errorMessage}`
+            : "pi turn ended with stopReason error (provider/auth failure)";
         return [
           {
             kind: "error",
-            message: "pi turn ended with stopReason error (provider/auth failure)",
+            message: msg,
             terminal: true,
           },
         ];

package/src/interpretation/hints.ts

@@ -27,6 +27,10 @@ const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFr
       "claude has no isolated instruction-file toggle; --setting-sources project isolates from user-level settings but also skips hooks, LSP and keychain reads - weigh that before using it as an approximation",
   },
   codex: {
+    tools:
+      "codex has no per-tool name lists; use --sandbox read-only for a read-only grant or category switches via config keys (features.shell_tool, web_search)",
+    excludeTools:
+      "codex has no per-tool name lists; use category switches via config keys (features.shell_tool) or --sandbox modes",
     write:
       "codex has no write toggle; use --sandbox read-only (config: sandbox_mode) so shell commands cannot write either",
     // issue #48: the append half has no codex spelling.
@@ -58,6 +62,10 @@ const HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = deepFr
       "pi has no step cap flag; bound the work in the prompt or impose a wall-clock timeout at the caller",
   },
   muse: {
+    tools:
+      "muse has no per-tool name lists; gate execution with --disable-write, --disable-shell, --disable-web-tools - there is no allowlist",
+    excludeTools:
+      "muse has no per-tool name lists; gate execution with --disable-write, --disable-shell, --disable-web-tools category switches",
     sandbox:
       "muse's sandbox is on by default and not selectable per-call; --disable-sandbox exists to turn it OFF, and exposure can be tuned with --disable-write, --disable-shell, --disable-web-tools - there is no mode selector",
     provider: