@dzhechkov/harness-core 0.8.10 → 0.8.20

package/dist/codex-invoke.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The one supported way to invoke Codex from a Claude Code session.
+ *
+ * Three failure modes were measured on 2026-08-31, each violating knowledge we had already
+ * written down and could not enforce: the fire-and-forget wrapper returning a dispatch stub for a
+ * stage whose deliverable is its return value; a prompt passed as a shell ARGUMENT whose backticks
+ * the shell read as command substitution, leaving codex to read an empty stdin and hang for 26
+ * minutes; and an unscoped run spending its whole budget exploring the tree and returning no
+ * verdict at all.
+ *
+ * The cure is structural, not advisory: this module has no parameter that accepts a prompt STRING
+ * (so a shell can never mangle it), a timeout is always present, and the outcome set is CLOSED —
+ * either the model's text, or one of five named refusals. There is no third state, which is the
+ * property the tests pin.
+ */
+/** Every way this can fail, enumerated. A refusal outside this set is a bug, not a new case. */
+export type CodexRefusal = 'timeout' | 'no-output' | 'model-unavailable' | 'tool-error' | 'bad-usage';
+export interface CodexOk {
+    readonly ok: true;
+    readonly text: string;
+    readonly model: string;
+    readonly elapsedMs: number;
+}
+export interface CodexRefused {
+    readonly ok: false;
+    readonly refusal: CodexRefusal;
+    /** Human-readable, names WHAT was observed — never a guess at the cause. */
+    readonly detail: string;
+    readonly model?: string;
+    readonly elapsedMs?: number;
+}
+export type CodexOutcome = CodexOk | CodexRefused;
+export declare const CODEX_DEFAULT_TIMEOUT_MS = 600000;
+export declare const CODEX_PROBE_TIMEOUT_MS = 90000;
+/** Model ids this account has been seen to answer on. A name here is spellable, never available. */
+export declare const CODEX_KNOWN_MODELS: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5"];
+export interface CodexRunInput {
+    /** Absolute path to a file holding the prompt. There is deliberately no string variant. */
+    readonly promptFile: string;
+    readonly model: string;
+    readonly timeoutMs?: number;
+    /**
+     * Files the model may read. REQUIRED for review-shaped work: an unscoped run was measured at
+     * 280s / exit 124 / 416KB of exploration and no verdict, while the same question scoped to two
+     * named files answered in 41s. Empty means "no scope declared" and is allowed only for a
+     * self-contained question that needs no repository access.
+     */
+    readonly scope?: readonly string[];
+    readonly effort?: 'low' | 'medium' | 'high' | 'xhigh';
+}
+/** What a runner must provide. Kept tiny so tests can substitute it without spawning anything. */
+export interface CodexRunner {
+    (argv: readonly string[], timeoutMs: number): {
+        readonly status: number | null;
+        readonly stdout: string;
+        readonly stderr: string;
+        readonly timedOut: boolean;
+    };
+}
+/** Build the argv. Exported so a test can assert the prompt never rides on the command line. */
+export declare function codexArgv(input: CodexRunInput): string[];
+/** Turn a raw runner result into the closed outcome set. */
+export declare function classifyCodexResult(raw: {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}, model: string, elapsedMs: number): CodexOutcome;
+/** Compose the prompt file's content: the task, plus the scope fence when one is declared. */
+export declare function codexPromptBody(task: string, scope?: readonly string[]): string;
+/** True when the outcome may be consumed as an answer. Exists so callers cannot forget the check. */
+export declare function codexAnswered(outcome: CodexOutcome): outcome is CodexOk;
+//# sourceMappingURL=codex-invoke.d.ts.map

package/dist/codex-invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-invoke.d.ts","sourceRoot":"","sources":["../src/codex-invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gGAAgG;AAChG,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,WAAW,GACX,mBAAmB,GACnB,YAAY,GACZ,WAAW,CAAC;AAEhB,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,YAAY,CAAC;AAElD,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAChD,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,oGAAoG;AACpG,eAAO,MAAM,kBAAkB,sEAAuE,CAAC;AAEvG,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;CACvD;AAED,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG;QAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CAIxD;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CACjC,GAAG,EAAE;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EACjF,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,YAAY,CAgCd;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAY/E;AAED,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,IAAI,OAAO,CAEvE"}

package/dist/codex-invoke.js

@@ -0,0 +1,80 @@
+/**
+ * The one supported way to invoke Codex from a Claude Code session.
+ *
+ * Three failure modes were measured on 2026-08-31, each violating knowledge we had already
+ * written down and could not enforce: the fire-and-forget wrapper returning a dispatch stub for a
+ * stage whose deliverable is its return value; a prompt passed as a shell ARGUMENT whose backticks
+ * the shell read as command substitution, leaving codex to read an empty stdin and hang for 26
+ * minutes; and an unscoped run spending its whole budget exploring the tree and returning no
+ * verdict at all.
+ *
+ * The cure is structural, not advisory: this module has no parameter that accepts a prompt STRING
+ * (so a shell can never mangle it), a timeout is always present, and the outcome set is CLOSED —
+ * either the model's text, or one of five named refusals. There is no third state, which is the
+ * property the tests pin.
+ */
+export const CODEX_DEFAULT_TIMEOUT_MS = 600_000;
+export const CODEX_PROBE_TIMEOUT_MS = 90_000;
+/** Model ids this account has been seen to answer on. A name here is spellable, never available. */
+export const CODEX_KNOWN_MODELS = ['gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.5'];
+/** Build the argv. Exported so a test can assert the prompt never rides on the command line. */
+export function codexArgv(input) {
+    const argv = ['exec', '-m', input.model, '--skip-git-repo-check'];
+    if (input.effort !== undefined)
+        argv.push('-c', `model_reasoning_effort=${input.effort}`);
+    return argv;
+}
+/** Turn a raw runner result into the closed outcome set. */
+export function classifyCodexResult(raw, model, elapsedMs) {
+    if (raw.timedOut) {
+        return {
+            ok: false,
+            refusal: 'timeout',
+            detail: `no answer within the deadline (${elapsedMs}ms); narrow the scope rather than raising the ceiling — an unscoped run spends the budget exploring`,
+            model,
+            elapsedMs,
+        };
+    }
+    if (raw.status !== 0) {
+        return {
+            ok: false,
+            refusal: 'tool-error',
+            detail: `codex exited ${raw.status === null ? 'by signal' : String(raw.status)}: ${raw.stderr.trim().slice(0, 300) || '(no stderr)'}`,
+            model,
+            elapsedMs,
+        };
+    }
+    const text = raw.stdout.trim();
+    if (text === '') {
+        // Silence is the failure this module exists to make impossible. A clean exit with nothing
+        // written is what a mangled prompt looks like from the outside, and it must never read as ok.
+        return {
+            ok: false,
+            refusal: 'no-output',
+            detail: 'codex exited 0 but wrote nothing — an empty answer is a refusal, never a clean result',
+            model,
+            elapsedMs,
+        };
+    }
+    return { ok: true, text, model, elapsedMs };
+}
+/** Compose the prompt file's content: the task, plus the scope fence when one is declared. */
+export function codexPromptBody(task, scope) {
+    const trimmed = String(task ?? '').trim();
+    if (scope === undefined || scope.length === 0)
+        return trimmed;
+    const list = scope.map((p) => `- ${p}`).join('\n');
+    return [
+        trimmed,
+        '',
+        'SCOPE — read ONLY these files and do not open others. This bound is what makes an answer',
+        'possible at all: an unscoped run was measured spending its entire budget exploring the tree',
+        'and returning no verdict.',
+        list,
+    ].join('\n');
+}
+/** True when the outcome may be consumed as an answer. Exists so callers cannot forget the check. */
+export function codexAnswered(outcome) {
+    return outcome.ok === true;
+}
+//# sourceMappingURL=codex-invoke.js.map

package/dist/codex-invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-invoke.js","sourceRoot":"","sources":["../src/codex-invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA4BH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAChD,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C,oGAAoG;AACpG,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,CAAU,CAAC;AA2BvG,gGAAgG;AAChG,MAAM,UAAU,SAAS,CAAC,KAAoB;IAC5C,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,uBAAuB,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,0BAA0B,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,mBAAmB,CACjC,GAAiF,EACjF,KAAa,EACb,SAAiB;IAEjB,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,SAAS;YAClB,MAAM,EAAE,kCAAkC,SAAS,qGAAqG;YACxJ,KAAK;YACL,SAAS;SACV,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,YAAY;YACrB,MAAM,EAAE,gBAAgB,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,aAAa,EAAE;YACrI,KAAK;YACL,SAAS;SACV,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,0FAA0F;QAC1F,8FAA8F;QAC9F,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,WAAW;YACpB,MAAM,EAAE,uFAAuF;YAC/F,KAAK;YACL,SAAS;SACV,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9C,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,KAAyB;IACrE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC9D,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnD,OAAO;QACL,OAAO;QACP,EAAE;QACF,0FAA0F;QAC1F,6FAA6F;QAC7F,2BAA2B;QAC3B,IAAI;KACL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,aAAa,CAAC,OAAqB;IACjD,OAAO,OAAO,CAAC,EAAE,KAAK,IAAI,CAAC;AAC7B,CAAC"}

package/dist/course-staleness.d.ts

@@ -0,0 +1,19 @@
+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;
+}
+/**
+ * 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 declare function classifyCourseStaleness(input: CourseStalenessInput): CourseStalenessResult;
+//# sourceMappingURL=course-staleness.d.ts.map

package/dist/course-staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"course-staleness.d.ts","sourceRoot":"","sources":["../src/course-staleness.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,mBAAmB,GACnB,mBAAmB,GACnB,cAAc,GACd,oBAAoB,GACpB,qBAAqB,GACrB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AASD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAwF1F"}

package/dist/course-staleness.js

@@ -0,0 +1,95 @@
+import { compareVersions } from './publish.js';
+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) {
+    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) {
+    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,
+    };
+}
+//# sourceMappingURL=course-staleness.js.map

package/dist/course-staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"course-staleness.js","sourceRoot":"","sources":["../src/course-staleness.ts"],"names":[],"mappings":"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"}

package/dist/destructive-guard-hook.d.ts

@@ -0,0 +1,40 @@
+/** Prefix of a BLOCKING message. Must appear verbatim for a block to be attributed to this guard. */
+export declare const DESTRUCTIVE_REFUSE_MARKER = "DZ-DESTRUCTIVE:";
+/** Prefix of a non-blocking message: an `undecidable` verdict, or our own failure to read. */
+export declare 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';
+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;
+}
+/**
+ * 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 declare function decideDestructiveHook(payload: unknown, host: DestructiveHookHost): DestructiveHookDecision;
+//# sourceMappingURL=destructive-guard-hook.d.ts.map

package/dist/destructive-guard-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"destructive-guard-hook.d.ts","sourceRoot":"","sources":["../src/destructive-guard-hook.ts"],"names":[],"mappings":"AAsBA,qGAAqG;AACrG,eAAO,MAAM,yBAAyB,oBAAoB,CAAC;AAE3D,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAKrD,MAAM,WAAW,uBAAuB;IACtC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IACzB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;IAChF,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAoDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,uBAAuB,CAiC1G"}

package/dist/destructive-guard-hook.js

@@ -0,0 +1,109 @@
+// 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';
+/** 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:';
+/** Tool names that ARE a shell on the Claude host. */
+const SHELL_TOOL_NAMES = new Set(['Bash', 'bash', 'shell', 'local_shell']);
+/**
+ * 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) {
+    const head = 'Чего этот страж НЕ решает (печатается при каждом вердикте, чтобы он не читался как гарантия):';
+    return [head, ...limits.map((l) => `  - ${l}`)].join('\n');
+}
+function renderRefusal(verdict) {
+    return [
+        `${DESTRUCTIVE_REFUSE_MARKER} ОТКАЗ — удаление по буквальному пути в защищаемое хранилище.`,
+        '',
+        `Путь:    ${verdict.path ?? '(не назван)'}`,
+        `Правило: ${verdict.rule ?? '(не названо)'}`,
+        `Причина: ${verdict.reason}`,
+        '',
+        renderLimits(verdict.limits),
+        '',
+        'Санкционированное удаление защищаемого хранилища выполняет владелец вручную, вне сеанса агента.',
+        '',
+    ].join('\n');
+}
+function renderUndecidable(verdict) {
+    return [
+        `${DESTRUCTIVE_WARN_MARKER} команду не удалось разобрать (${verdict.reason}) — ПРОПУЩЕНА без отказа: «проверить не удалось» никогда не выдаётся за «запрещено» (AC-10).`,
+        renderLimits(verdict.limits),
+        '',
+    ].join('\n');
+}
+function unreadable(message) {
+    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 = { exitCode: 0, stderr: '', outcome: 'skipped', rule: null };
+const ALLOW = { 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, host) {
+    if (payload === null || typeof payload !== 'object') {
+        return unreadable('полезная нагрузка хука не прочиталась');
+    }
+    const p = payload;
+    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.command : undefined;
+    if (typeof command !== 'string' || command === '')
+        return SKIP;
+    let verdict;
+    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?.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;
+}
+//# sourceMappingURL=destructive-guard-hook.js.map

package/dist/destructive-guard-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"destructive-guard-hook.js","sourceRoot":"","sources":["../src/destructive-guard-hook.ts"],"names":[],"mappings":"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"}

package/dist/destructive-guard.d.ts

@@ -0,0 +1,27 @@
+/** A verdict on one shell command. `limits` is always populated — see LIMITS below. */
+export interface DestructiveVerdict {
+    /** `refuse` = block it. `allow` = out of scope. `undecidable` = could not parse; consumer PASSES. */
+    outcome: 'refuse' | 'allow' | 'undecidable';
+    /** The literal path that triggered the refusal, as the SHELL would pass it to the program. */
+    path: string | null;
+    /** The id of the rule that fired — one of DESTRUCTIVE_RULES. */
+    rule: string | null;
+    /** One line naming what was decided and why. A refusal always names the path and the rule. */
+    reason: string;
+    /** What this guard does NOT decide. Printed on EVERY verdict, refusals included. */
+    limits: readonly string[];
+}
+/** The complete rule table. A refusal always carries one of these ids. */
+export declare const DESTRUCTIVE_RULES: readonly {
+    id: string;
+    what: string;
+}[];
+/**
+ * Decide whether a shell command must be refused BEFORE it runs.
+ *
+ * Refuses only when it can name a concrete literal path and the rule that path broke. Everything
+ * else is allowed, and every verdict prints the guard's limits (LIMITS) so it is never read as a
+ * total guarantee.
+ */
+export declare function classifyDestructive(command: string): DestructiveVerdict;
+//# sourceMappingURL=destructive-guard.d.ts.map

package/dist/destructive-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"destructive-guard.d.ts","sourceRoot":"","sources":["../src/destructive-guard.ts"],"names":[],"mappings":"AAkBA,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,qGAAqG;IACrG,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAC;IAC5C,8FAA8F;IAC9F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAiBD,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAInE,CAAC;AA4rFH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAoBvE"}