@dzhechkov/harness-core 0.8.11 → 0.8.21

package/src/codex-hooks-assets.ts

@@ -29,18 +29,26 @@
  */
 
 import { DZ_HOOK_HELPER_VERSION } from './codex-hooks.js';
+import { harnessCoreDistDir } from './harness-core-location.js';
 
 /** Shared prologue: payload read, project-root walk, never-throw error note. */
-function preamble(): string {
+function preamble(installedDistDir: string | null): string {
   return `#!/usr/bin/env node
 // GENERATED by @dzhechkov/harness-core — dz-hook-helper-version: ${DZ_HOOK_HELPER_VERSION}
 // Do not edit: dz rewrites this file, and any edit disarms the hook until it is re-trusted.
 'use strict';
 const fs = require('node:fs');
 const path = require('node:path');
+const { pathToFileURL } = require('node:url');
 
 const HELPER_VERSION = ${DZ_HOOK_HELPER_VERSION};
 const CODEX_HOME = process.env.CODEX_HOME || path.join(require('node:os').homedir(), '.codex');
+// The harness-core installation that EMITTED this helper, baked in at emission time.
+// MEASURED 2026-09-05: with only the two project-relative candidates below, the documented
+// global install ('npm i -g @dzhechkov/harness-cli') left every target repository without a
+// resolvable module — every shell call reached 'guard not loaded' and was ALLOWED. It is null
+// when the emitter could not name its own location; the project candidates still apply.
+const INSTALLED_CORE_DIST = ${installedDistDir === null ? 'null' : JSON.stringify(installedDistDir)};
 const ERROR_LOG = path.join(CODEX_HOME, 'dz-hooks', 'helper-errors.jsonl');
 
 /**
@@ -141,35 +149,77 @@ function readProjectConfig(root) {
   }
 }
 
-/** Load a built module from the project's own harness-core, or null. Never throws. */
-function loadCore(root, fileName, predicate) {
+/**
+ * Load a built module from the project's own harness-core. Never throws.
+ *
+ * \`import()\`, NEVER \`require()\`. \`@dzhechkov/harness-core\` is \`"type": "module"\`, so every file in
+ * its \`dist/\` is an ES module, while this package supports \`node >= 20\`. \`require()\` of an ES
+ * module was only unflagged in Node 20.19 / 22.12 — below that it throws ERR_REQUIRE_ESM, this
+ * loader turned that into \`null\`, and a \`null\` policy is a SILENT allow. MEASURED 2026-09-05 on
+ * this machine, reproducing the old loader with the flag that turns the unflagging back off:
+ *   node --no-experimental-require-module <veto helper>  on  \`rm -rf .agentic-qe\`
+ *   ⇒ exit 0 and an EMPTY stderr — the guard was not weak there, it was absent and mute.
+ * \`import()\` loads BOTH module kinds on every supported Node, so there is one loader instead of one
+ * that happens to work on the runtime that ran the tests.
+ *
+ * Returns \`{ mod, reason }\`. \`reason\` is the cause that was OBSERVED — the module id plus the code
+ * Node reported for it — never a cause we assumed: a warning that says "no build" about an
+ * ERR_REQUIRE_ESM sends the reader to fix something that is not broken.
+ */
+async function loadCoreDetailed(root, fileName, predicate) {
   const candidates = [
     path.join(root, 'node_modules', '@dzhechkov', 'harness-core', 'dist', fileName),
     path.join(root, 'packages', '@dzhechkov', 'harness-core', 'dist', fileName),
   ];
+  // The emitting installation is the LAST resort, never the first: a project that ships its own
+  // harness-core must keep using its own copy rather than being pinned to whatever emitted the hook.
+  if (INSTALLED_CORE_DIST !== null) candidates.push(path.join(INSTALLED_CORE_DIST, fileName));
+  const failures = [];
   for (const candidate of candidates) {
     try {
-      if (!fs.existsSync(candidate)) continue;
-      const mod = require(candidate);
-      if (predicate(mod)) return mod;
+      const mod = await import(pathToFileURL(candidate).href);
+      if (predicate(mod)) return { mod: mod, reason: null };
+      if (mod.default && predicate(mod.default)) return { mod: mod.default, reason: null };
+      failures.push(candidate + ': загружен, но нужный экспорт отсутствует');
     } catch (err) {
-      note('load-core:' + fileName, err);
+      const code = (err && err.code) || 'ERR_UNKNOWN';
+      failures.push(candidate + ': ' + code + ' ' + String((err && err.message) || err));
+      // An absent optional module is the ORDINARY case (a project may not ship every policy), so it
+      // does not earn a durable note; anything else is a real load failure and does.
+      if (code !== 'ERR_MODULE_NOT_FOUND') note('load-core:' + fileName, err);
     }
   }
-  return null;
+  return { mod: null, reason: failures.join(' | ').replace(/\\s*\\n\\s*/g, ' ') };
+}
+
+/** The module only, for callers that have nothing to say about WHY it is missing. */
+async function loadCore(root, fileName, predicate) {
+  return (await loadCoreDetailed(root, fileName, predicate)).mod;
 }
 `;
 }
 
 /**
- * The PreToolUse veto helper.
+ * The PreToolUse veto helper — TWO checks behind one registry entry.
+ *
+ * 1. The destructive-command guard (feature `destructive-command-guard`, ADR-001): a deletion by a
+ *    LITERAL path into a protected store (`.dz/`, `.agentic-qe/`, a database file). It blocks
+ *    UNCONDITIONALLY, with no config mode, and that asymmetry with the shell veto below is
+ *    deliberate: the shell veto's default is `warn` because its class is broad and its false-hit
+ *    rate is unmeasured, while this guard's scope was cut by measurement over 20 938 real commands
+ *    down to one refusal per ~510 commands (0,196 %) — narrow enough that a refusal is a fact about
+ *    the command's FORM, not a judgement about its intent. The verdict, the text and the limits all
+ *    come from `destructive-guard-hook.js`, the SAME module the Claude host's hook consumes, so
+ *    both runtimes refuse the same commands in the same words.
+ * 2. The shell veto policy: fail-OPEN on OUR failure, mode-driven on a POLICY hit. Exit 2 only when
+ *    the project explicitly opted in — the shipped default warns and returns 0 (AM-24 / G-J).
  *
- * Fail-OPEN on OUR failure, mode-driven on a POLICY hit. Exit 2 only when the project explicitly
- * opted in — the shipped default warns and returns 0 (AM-24 / G-J).
+ * The destructive check runs FIRST and is loaded SEPARATELY, so a project whose build lacks the
+ * shell-veto policy still gets it, and vice versa.
  */
-export function generateCodexVetoHelper(): string {
-  return `${preamble().replace('const HELPER_VERSION', "const HELPER = 'dz-codex-veto';\nconst HELPER_VERSION")}
-function main() {
+export function generateCodexVetoHelper(installedDistDir: string | null = harnessCoreDistDir()): string {
+  return `${preamble(installedDistDir).replace('const HELPER_VERSION', "const HELPER = 'dz-codex-veto';\nconst HELPER_VERSION")}
+async function main() {
   const payload = readPayload();
   if (payload === null) return 0;
 
@@ -183,7 +233,58 @@ function main() {
   const root = findProjectRoot(cwd);
   if (root === null) return 0; // inert outside an opted-in dz project: no decision, no output, no write
 
-  const policy = loadCore(root, 'shell-veto-policy.js', (m) => typeof m.vetoShellCommand === 'function');
+  // (1) The destructive-command guard. Never blocks on our own failure: an absent module, a throw,
+  // or an \`undecidable\` verdict all fall through to the shell veto below (AC-10).
+  const destructiveLoad = await loadCoreDetailed(root, 'destructive-guard-hook.js', (m) => typeof m.decideDestructiveHook === 'function');
+  if (destructiveLoad.mod === null) {
+    // NEVER silence. A guard that could not load is indistinguishable from a guard that decided
+    // "allow" unless it SAYS so, and the measurement that produced this branch is exactly that:
+    // exit 0 with an empty stderr on \`rm -rf .agentic-qe\`. The exit code stays 0 — our failure is
+    // not the user's violation — but it is announced on ONE line in BOTH places a human can read
+    // it: the transcript, and the durable notes log (codex swallows an exit-0 stderr, M9).
+    const line = 'DZ-DESTRUCTIVE-WARN: guard not loaded — ' + destructiveLoad.reason;
+    process.stderr.write(line + '\\n');
+    note('destructive-not-loaded', null, Object.assign(
+      { marker: 'DZ-DESTRUCTIVE-WARN', reason: destructiveLoad.reason },
+      commandFacts(command),
+    ));
+  } else {
+    const destructive = destructiveLoad.mod;
+    let decision = null;
+    try {
+      decision = destructive.decideDestructiveHook(payload, 'codex');
+      // CHECKED, not assumed: a decision the helper cannot read must reach the loud path with a
+      // NAME. Both \`null\` and \`{}\` are falsy at \`decision.stderr\` further down, so an unreadable
+      // shape used to make the verdict simply vanish — a second door into the same silence.
+      if (!decision || typeof decision.stderr !== 'string') {
+        throw new TypeError('решение стража нечитаемо: ' + JSON.stringify(decision));
+      }
+    } catch (err) {
+      // ONE line, always (round 9). The Claude hook already failed open LOUDLY here; this helper
+      // only wrote a note, so in the transcript a thrown decider was indistinguishable from a clean
+      // allow — the round-2 defect class (absent AND mute) reached through another door. Exit stays
+      // 0, because our failure is not the user's violation, and the record lands in BOTH places a
+      // human can read: the transcript, and the notes log (codex swallows an exit-0 stderr, M9).
+      const why = String((err && err.message) || err).replace(/\\s*\\n\\s*/g, ' ');
+      process.stderr.write('DZ-DESTRUCTIVE-WARN: classifier threw — ' + why + '\\n');
+      note('destructive-threw', err, Object.assign({ marker: 'DZ-DESTRUCTIVE-WARN' }, commandFacts(command)));
+      decision = null;
+    }
+    if (decision && decision.stderr) process.stderr.write(decision.stderr);
+    if (decision && decision.exitCode === 2) {
+      // The note carries the RULE and the command's hash, never the command line itself (R2-8).
+      note('destructive-block', null, Object.assign({ marker: 'DZ-DESTRUCTIVE', rule: decision.rule }, commandFacts(command)));
+      return 2;
+    }
+    if (decision && decision.stderr) {
+      // MEASURED (M9): codex swallows an exit-0 hook's stderr, so a non-blocking word from this
+      // guard is unobservable unless it is ALSO written where it can be read back.
+      note('destructive-' + decision.outcome, null, Object.assign({ marker: 'DZ-DESTRUCTIVE-WARN' }, commandFacts(command)));
+    }
+  }
+
+  // (2) The shell veto policy.
+  const policy = await loadCore(root, 'shell-veto-policy.js', (m) => typeof m.vetoShellCommand === 'function');
   if (policy === null) return 0; // no logic available => allow (never block on OUR failure)
 
   let hit = null;
@@ -210,14 +311,12 @@ function main() {
   return 0;
 }
 
-let code = 0;
-try {
-  code = main();
-} catch (err) {
-  note('main', err);
-  code = 0;
-}
-process.exit(code === 2 ? 2 : 0);
+// \`main\` is async because the policy loader is (\`import()\`, not \`require()\` — see loadCoreDetailed).
+// The exit code still comes from exactly one place, and a rejected promise is the same fail-open as
+// a thrown error was: note it, exit 0.
+main()
+  .catch((err) => { note('main', err); return 0; })
+  .then((code) => process.exit(code === 2 ? 2 : 0));
 `;
 }
 
@@ -228,8 +327,8 @@ process.exit(code === 2 ? 2 : 0);
  * relevant, which is exactly why the acceptance canary is a FORCED HIT plus a removed-hook twin
  * (AM-4) — a dead hook and a correctly-silent one are indistinguishable from the outside.
  */
-export function generateCodexRecallHelper(): string {
-  return `${preamble().replace('const HELPER_VERSION', "const HELPER = 'dz-codex-recall';\nconst HELPER_VERSION")}
+export function generateCodexRecallHelper(installedDistDir: string | null = harnessCoreDistDir()): string {
+  return `${preamble(installedDistDir).replace('const HELPER_VERSION', "const HELPER = 'dz-codex-recall';\nconst HELPER_VERSION")}
 const net = require('node:net');
 const DAEMON_TIMEOUT_MS = 2000;
 
@@ -275,7 +374,7 @@ async function main() {
   const root = findProjectRoot(cwd);
   if (root === null) return; // inert outside an opted-in dz project
 
-  const policy = loadCore(root, 'recall-hook-policy.js', (m) => typeof m.selectHookHits === 'function');
+  const policy = await loadCore(root, 'recall-hook-policy.js', (m) => typeof m.selectHookHits === 'function');
   if (policy === null) return;
 
   const candidates = await askDaemon(root, prompt);
@@ -301,7 +400,7 @@ async function main() {
   // The usage row carries runtime: 'codex' (ADR-003 §3) through the SHARED chained appender in
   // harness-core — ONE writer implementation, two callers (AM-6/AM-7). Written AFTER stdout so a
   // logging failure can never cost the user their injection.
-  const usage = loadCore(root, 'recall-usage.js', (m) => typeof m.appendRecallUsage === 'function');
+  const usage = await loadCore(root, 'recall-usage.js', (m) => typeof m.appendRecallUsage === 'function');
   if (usage === null) return;
   try {
     usage.appendRecallUsage({
@@ -322,7 +421,18 @@ main()
 `;
 }
 
-/** Both helper bodies, keyed by the file they are written to. */
-export function generateCodexHelpers(): Readonly<Record<'veto' | 'recall', string>> {
-  return { veto: generateCodexVetoHelper(), recall: generateCodexRecallHelper() };
+/**
+ * Both helper bodies, keyed by the file they are written to.
+ *
+ * `installedDistDir` defaults to the harness-core doing the emitting; pass `null` for a body with
+ * no absolute fallback (the pre-fix behaviour, kept so a test can prove the fallback is what makes
+ * a global install work rather than asserting it).
+ */
+export function generateCodexHelpers(
+  installedDistDir: string | null = harnessCoreDistDir(),
+): Readonly<Record<'veto' | 'recall', string>> {
+  return {
+    veto: generateCodexVetoHelper(installedDistDir),
+    recall: generateCodexRecallHelper(installedDistDir),
+  };
 }

package/src/codex-hooks.ts

@@ -36,8 +36,28 @@ import { mergeManagedHookEntries } from './managed-hooks.js';
  * 3 — fix round 2: the note's `commandSynopsis` is a binary NAME or `(redacted)` — an
  * env-assignment first token (`SECRET=xyz ssh …`) carried the credential the redaction removed
  * everywhere else (R2-8).
+ * 4 — the destructive-command guard (feature `destructive-command-guard`, ADR-001, task T8): the
+ * veto helper consults `destructive-guard-hook.js` BEFORE the shell veto and blocks
+ * unconditionally on a literal path into a protected store. A changed body changes codex's
+ * `currentHash`, so the entry must be re-trusted — re-run `dz setup --target codex`.
+ * 5 — round 2 of the cross-family review, MEASURED: the helper's module loader was `require()`, and
+ * every file in this package's `dist/` is an ES module, so on Node below 20.19 / 22.12 the load
+ * threw ERR_REQUIRE_ESM, the catch returned `null`, and the helper exited 0 with an EMPTY stderr on
+ * `rm -rf .agentic-qe` — absent AND mute on a Node the package claims to support. The loader is now
+ * `import()`, `main` is async, and a decider that still cannot load says so on one line instead of
+ * staying silent. A changed body ⇒ a changed `currentHash` ⇒ re-trust.
+ * 6 — round 3, MEASURED: the body's module candidates were both PROJECT-relative, so in the
+ * documented global install (`npm i -g @dzhechkov/harness-cli`) an ordinary target repository
+ * resolved neither — every shell call reached `guard not loaded` and was ALLOWED, while the tests
+ * hid it by symlinking the package into the temp project. The emitting installation's absolute
+ * dist path is now baked in as the LAST candidate. A changed body ⇒ re-trust.
+ * 7 — round 9, MEASURED: when the decider THREW (or returned a shape the helper could not read),
+ * the helper wrote a note and printed NOTHING — stderr came back empty, so in the transcript the
+ * run was indistinguishable from a clean allow. The Claude hook already failed open loudly here.
+ * Now it prints ONE line, `DZ-DESTRUCTIVE-WARN: classifier threw — <message>`, and still exits 0.
+ * A changed body ⇒ re-trust.
  */
-export const DZ_HOOK_HELPER_VERSION = 3;
+export const DZ_HOOK_HELPER_VERSION = 7;
 
 /** Seconds. Probe-proven (spike S2): `timeout` is honored, the unset default is 600 s. */
 export const DZ_HOOK_TIMEOUT_SECONDS = 5;

package/src/course-staleness.ts

@@ -0,0 +1,125 @@
+import { compareVersions } from './publish.js';
+
+export type CourseStalenessState =
+  | 'S0_SHIPPED'
+  | 'S3_TUTORIAL_STALE'
+  | 'S4_PACKAGE_BEHIND'
+  | 'E2_UNSTAMPED'
+  | 'E3_INVALID_VERSION'
+  | 'E4_PACKAGE_MISMATCH'
+  | 'E5_REGISTRY_UNKNOWN';
+
+export interface CourseStalenessInput {
+  readonly source: unknown;
+  readonly expectedPackage?: string | null;
+  readonly registryVersion?: string | null;
+}
+
+export interface CourseStalenessResult {
+  readonly state: CourseStalenessState;
+  readonly reason: string;
+  readonly courseVersion?: string;
+  readonly registryVersion?: string;
+  readonly package?: string;
+}
+
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Classify only the version evidence supplied by the caller. Obtaining a registry version is a
+ * caller responsibility; this function performs no filesystem, network, clock, or environment I/O.
+ */
+export function classifyCourseStaleness(input: CourseStalenessInput): CourseStalenessResult {
+  const candidate = isRecord(input) ? input : undefined;
+  const source = candidate?.source;
+
+  // Presence and shape come first. Unknown values must never reach an equality comparison where
+  // two absences could be mistaken for parity.
+  if (!isRecord(source)
+    || typeof source.package !== 'string'
+    || source.package.trim() === ''
+    || typeof source.version !== 'string'
+    || source.version.trim() === '') {
+    return {
+      state: 'E2_UNSTAMPED',
+      reason: 'course.source.package and course.source.version must both be non-empty strings',
+    };
+  }
+
+  const packageName = source.package.trim();
+  const courseVersion = source.version.trim();
+  if (!SEMVER.test(courseVersion)) {
+    return {
+      state: 'E3_INVALID_VERSION',
+      reason: `course.source.version is not valid semver: ${courseVersion}`,
+      courseVersion,
+      package: packageName,
+    };
+  }
+
+  const expectedPackage = typeof candidate?.expectedPackage === 'string'
+    ? candidate.expectedPackage.trim()
+    : candidate?.expectedPackage;
+  if (!PACKAGE_NAME.test(packageName)
+    || (expectedPackage !== null && expectedPackage !== undefined
+      && (!PACKAGE_NAME.test(expectedPackage) || packageName !== expectedPackage))) {
+    return {
+      state: 'E4_PACKAGE_MISMATCH',
+      reason: expectedPackage
+        ? `course.source.package ${packageName} does not match expectedPackage ${expectedPackage}`
+        : `course.source.package is not a valid npm package name: ${packageName}`,
+      courseVersion,
+      package: packageName,
+    };
+  }
+
+  const registryVersion = candidate?.registryVersion;
+  if (registryVersion === null || registryVersion === undefined) {
+    return {
+      state: 'E5_REGISTRY_UNKNOWN',
+      reason: 'registryVersion is absent, so package parity is unknown',
+      courseVersion,
+      package: packageName,
+    };
+  }
+  if (typeof registryVersion !== 'string' || !SEMVER.test(registryVersion.trim())) {
+    return {
+      state: 'E3_INVALID_VERSION',
+      reason: `registryVersion is not valid semver: ${String(registryVersion)}`,
+      courseVersion,
+      package: packageName,
+    };
+  }
+
+  const normalizedRegistryVersion = registryVersion.trim();
+  const ordering = compareVersions(courseVersion, normalizedRegistryVersion);
+  const common = {
+    courseVersion,
+    registryVersion: normalizedRegistryVersion,
+    package: packageName,
+  };
+  if (ordering === 0) {
+    return {
+      state: 'S0_SHIPPED',
+      reason: 'course.source.version equals registryVersion',
+      ...common,
+    };
+  }
+  if (ordering < 0) {
+    return {
+      state: 'S3_TUTORIAL_STALE',
+      reason: 'course.source.version is below registryVersion',
+      ...common,
+    };
+  }
+  return {
+    state: 'S4_PACKAGE_BEHIND',
+    reason: 'course.source.version is above registryVersion',
+    ...common,
+  };
+}

package/src/destructive-guard-hook.ts

@@ -0,0 +1,151 @@
+// destructive-guard-hook — the CONSUMER half of the destructive-command guard
+// (feature `destructive-command-guard`, ADR-001, plan task T8).
+//
+// WHY THIS FILE EXISTS AT ALL. The classifier (`destructive-guard.ts`) already returned a verdict,
+// and nothing on either host read it: the export existed, the consumer did not, so
+// `rm -rf .agentic-qe` still executed on both runtimes. A verdict nobody consumes is a document,
+// not a guard. This module is that consumer — and it is ONE module rather than two hook bodies,
+// because the two hosts must give the SAME answer in the SAME words. A refusal text duplicated in
+// two shell-spawned strings drifts silently the first time either is edited.
+//
+// PURE BY CONTRACT, exactly like the classifier it wraps: a payload in, an exit code and a piece of
+// text out. No filesystem access, no subprocess, no environment. The hook bodies that call it read
+// stdin, hand the parsed object over, print what comes back and exit with the code — nothing else.
+//
+// FAIL-OPEN ON OUR OWN FAILURE. Every branch that is not a decided `refuse` exits 0. An unparseable
+// payload, a classifier that throws, a tool that is not a shell — none of them is evidence of a
+// violation, and a guard that blocks on its own confusion is a guard the user switches off. This is
+// the same polarity the sibling guards ship with (`claim-check-hook.cjs`, `dz-codex-veto.cjs`).
+
+import { classifyDestructive } from './destructive-guard.js';
+import type { DestructiveVerdict } from './destructive-guard.js';
+
+/** Prefix of a BLOCKING message. Must appear verbatim for a block to be attributed to this guard. */
+export const DESTRUCTIVE_REFUSE_MARKER = 'DZ-DESTRUCTIVE:';
+
+/** Prefix of a non-blocking message: an `undecidable` verdict, or our own failure to read. */
+export const DESTRUCTIVE_WARN_MARKER = 'DZ-DESTRUCTIVE-WARN:';
+
+/**
+ * Which host contract the payload follows. The two differ in ONE measured respect, so the
+ * difference is a parameter rather than a guess:
+ *
+ * - `claude` — Claude Code sends `tool_name` for every tool and the registered matcher is `^Bash$`.
+ *   A payload whose `tool_name` is not a shell tool is skipped WITHOUT looking at any command field,
+ *   which is what the host contract promises and what the test pins.
+ * - `codex` — AM-8 of `crossrt-2-codex-hooks`: key on the PRESENCE of `tool_input.command`, never on
+ *   `tool_name` equality. Codex's shell tool has been observed under more than one name
+ *   (`Bash|shell|local_shell` is the matcher the emitted registry entry already carries), so a
+ *   tool_name test there would silently disarm the guard the day the runtime renames its tool.
+ */
+export type DestructiveHookHost = 'claude' | 'codex';
+
+/** Tool names that ARE a shell on the Claude host. */
+const SHELL_TOOL_NAMES: ReadonlySet<string> = new Set(['Bash', 'bash', 'shell', 'local_shell']);
+
+export interface DestructiveHookDecision {
+  /** 2 = block the call (the host contract on BOTH runtimes). 0 = let it through. */
+  readonly exitCode: 0 | 2;
+  /** Exactly what the hook body writes to stderr. Empty string ⇒ write nothing at all. */
+  readonly stderr: string;
+  /**
+   * What happened, for tests and for the helper's own notes log:
+   * `refuse` / `allow` / `undecidable` are the classifier's three outcomes;
+   * `skipped` = not a shell command, the classifier was never consulted;
+   * `unreadable` = the payload or the classifier failed us, and we passed rather than guessed.
+   */
+  readonly outcome: 'refuse' | 'allow' | 'undecidable' | 'skipped' | 'unreadable';
+  /** The rule id from a refusal, so a note can record WHICH rule fired without the command line. */
+  readonly rule: string | null;
+}
+
+/**
+ * Render the limits block from THE VERDICT's own list — never from a copy kept here.
+ *
+ * ADR-001 obliges the guard to NAME what it does not decide, in its own text, on every verdict it
+ * speaks about: a guard silent about its limits reads as a guarantee that recursive deletion is
+ * covered, and it is not. Re-listing them in this file would be a second copy free to drift from
+ * the classifier's; `verdict.limits` is the single source.
+ */
+function renderLimits(limits: readonly string[]): string {
+  const head = 'Чего этот страж НЕ решает (печатается при каждом вердикте, чтобы он не читался как гарантия):';
+  return [head, ...limits.map((l) => `  - ${l}`)].join('\n');
+}
+
+function renderRefusal(verdict: DestructiveVerdict): string {
+  return [
+    `${DESTRUCTIVE_REFUSE_MARKER} ОТКАЗ — удаление по буквальному пути в защищаемое хранилище.`,
+    '',
+    `Путь:    ${verdict.path ?? '(не назван)'}`,
+    `Правило: ${verdict.rule ?? '(не названо)'}`,
+    `Причина: ${verdict.reason}`,
+    '',
+    renderLimits(verdict.limits),
+    '',
+    'Санкционированное удаление защищаемого хранилища выполняет владелец вручную, вне сеанса агента.',
+    '',
+  ].join('\n');
+}
+
+function renderUndecidable(verdict: DestructiveVerdict): string {
+  return [
+    `${DESTRUCTIVE_WARN_MARKER} команду не удалось разобрать (${verdict.reason}) — ПРОПУЩЕНА без отказа: «проверить не удалось» никогда не выдаётся за «запрещено» (AC-10).`,
+    renderLimits(verdict.limits),
+    '',
+  ].join('\n');
+}
+
+function unreadable(message: string): DestructiveHookDecision {
+  return {
+    exitCode: 0,
+    // One line, and no limits block: there is no verdict here to quote limits FROM, and inventing
+    // one would be the same lie in the other direction.
+    stderr: `${DESTRUCTIVE_WARN_MARKER} ${message} — пропуск без отказа; отсутствие вердикта нарушением не является.\n`,
+    outcome: 'unreadable',
+    rule: null,
+  };
+}
+
+const SKIP: DestructiveHookDecision = { exitCode: 0, stderr: '', outcome: 'skipped', rule: null };
+const ALLOW: DestructiveHookDecision = { exitCode: 0, stderr: '', outcome: 'allow', rule: null };
+
+/**
+ * Turn one hook payload into an exit code and a piece of text. The whole policy, both hosts.
+ *
+ * @param payload the parsed stdin object, or `null`/anything else when it did not parse.
+ * @param host    which host contract the payload follows — see {@link DestructiveHookHost}.
+ */
+export function decideDestructiveHook(payload: unknown, host: DestructiveHookHost): DestructiveHookDecision {
+  if (payload === null || typeof payload !== 'object') {
+    return unreadable('полезная нагрузка хука не прочиталась');
+  }
+
+  const p = payload as { tool_name?: unknown; tool_input?: unknown };
+
+  if (host === 'claude') {
+    // The Claude contract: decide from the tool NAME first, and on a non-shell tool return before
+    // any command field is even looked at.
+    const toolName = typeof p.tool_name === 'string' ? p.tool_name : '';
+    if (!SHELL_TOOL_NAMES.has(toolName)) return SKIP;
+  }
+
+  const input = p.tool_input;
+  const command = input !== null && typeof input === 'object' ? (input as { command?: unknown }).command : undefined;
+  if (typeof command !== 'string' || command === '') return SKIP;
+
+  let verdict: DestructiveVerdict;
+  try {
+    verdict = classifyDestructive(command);
+  } catch (err) {
+    // Our own failure. Never a refusal — see the FAIL-OPEN note at the top of the file.
+    return unreadable(`классификатор не смог вынести вердикт (${String((err as Error)?.message ?? err)})`);
+  }
+
+  if (verdict.outcome === 'refuse') {
+    return { exitCode: 2, stderr: renderRefusal(verdict), outcome: 'refuse', rule: verdict.rule };
+  }
+  if (verdict.outcome === 'undecidable') {
+    return { exitCode: 0, stderr: renderUndecidable(verdict), outcome: 'undecidable', rule: null };
+  }
+  return ALLOW;
+}