@cleocode/core 2026.10.2 → 2026.10.4

package/dist/resources/heavy-command-hook-delivery.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Heavy-command hook delivery for `cleo init`, `cleo upgrade`, `cleo doctor`
+ * and the session briefing (T13124).
+ *
+ * The hook (`cleo hook heavy-command`, T12983) routes agent-run tests, builds
+ * and typechecks through `cleo run`, the machine-wide ResourceGovernor. It only
+ * helps where it is installed. init/upgrade used to install it through
+ * `AdapterManager`, whose discovery finds no adapter in any project, and a
+ * try/catch swallowed every failure, so on 2026-10-03 it was installed nowhere.
+ * Delivery is now its own step, with one outcome per provider in the report,
+ * and `cleo doctor` plus the briefing say when a provider in use lacks it.
+ *
+ * The per-provider installers live in `@cleocode/adapters` (provider delivery).
+ * That package builds on this one, so it is loaded at run time through its
+ * light `@cleocode/adapters/heavy-command-hook` entry point and validated
+ * against the {@link HeavyHookDeliveryApi} contract.
+ *
+ * @module resources/heavy-command-hook-delivery
+ * @task T13124
+ * @epic T13121
+ */
+import type { HeavyCommandHookMode, HeavyHookCliProbe, HeavyHookDeliveryApi, HeavyHookDeliveryOptions, HeavyHookDeliveryOutcome, HeavyHookInspection } from '@cleocode/contracts';
+/** The adapters entry point that carries the delivery functions. */
+export declare const HEAVY_HOOK_DELIVERY_MODULE = "@cleocode/adapters/heavy-command-hook";
+/** The command that installs or refreshes only this hook. */
+export declare const HEAVY_HOOK_FIX = "cleo doctor heavy-command-hook --fix";
+/**
+ * Load the delivery functions from `@cleocode/adapters`. The specifier is held
+ * in a variable so TypeScript does not resolve it at build time (adapters
+ * references core, so a static import would be a build cycle).
+ *
+ * @returns the delivery API.
+ * @throws when the module is missing or does not export the API.
+ */
+export declare function loadHeavyHookDelivery(): Promise<HeavyHookDeliveryApi>;
+/**
+ * The hook mode init/upgrade install from: `resources.heavyCommandHook`
+ * (default `rewrite`). The `CLEO_HEAVY_COMMAND_HOOK` environment variable
+ * switches the hook at run time only and does not change what is installed.
+ *
+ * @param projectRoot - the project whose config to read.
+ */
+export declare function installedHeavyHookMode(projectRoot: string): Promise<HeavyCommandHookMode>;
+/** What {@link deliverHeavyCommandHooks} did. */
+export interface HeavyHookDeliveryReport {
+    /** The mode installed from. */
+    readonly mode: HeavyCommandHookMode;
+    /** One outcome per provider. */
+    readonly outcomes: readonly HeavyHookDeliveryOutcome[];
+}
+/**
+ * Install, refresh or remove the hook for every provider in use in the project.
+ *
+ * @param projectRoot - the project root.
+ * @param options - environment and provider list (tests); `api` replaces the
+ *   run-time loaded adapters module.
+ * @returns the mode and each provider's outcome.
+ * @throws only when the adapters module cannot be loaded.
+ */
+export declare function deliverHeavyCommandHooks(projectRoot: string, options?: HeavyHookDeliveryOptions & {
+    readonly api?: HeavyHookDeliveryApi;
+}): Promise<HeavyHookDeliveryReport>;
+/** What {@link inspectHeavyCommandHooks} found. */
+export interface HeavyHookInspectionReport {
+    /** The configured mode. */
+    readonly mode: HeavyCommandHookMode;
+    /** One inspection per provider. */
+    readonly inspections: readonly HeavyHookInspection[];
+}
+/**
+ * Read-only: the hook's state for every provider in the project.
+ *
+ * @param projectRoot - the project root.
+ * @param options - environment and provider list (tests); `api` replaces the
+ *   run-time loaded adapters module.
+ * @returns the mode and each provider's state.
+ * @throws only when the adapters module cannot be loaded.
+ */
+export declare function inspectHeavyCommandHooks(projectRoot: string, options?: HeavyHookDeliveryOptions & {
+    readonly api?: HeavyHookDeliveryApi;
+}): Promise<HeavyHookInspectionReport>;
+/**
+ * Whether the `cleo` on PATH, as the hook resolves it from the project, can
+ * answer the hook (an installed hook in front of an older CLEO governs
+ * nothing). Starts that `cleo` once.
+ *
+ * @param projectRoot - the project root.
+ * @param options - environment (tests); `api` replaces the run-time loaded
+ *   adapters module.
+ * @throws only when the adapters module cannot be loaded.
+ */
+export declare function probeHeavyHookCliFor(projectRoot: string, options?: HeavyHookDeliveryOptions & {
+    readonly api?: HeavyHookDeliveryApi;
+}): Promise<HeavyHookCliProbe>;
+/**
+ * Whether any provider has CLEO's hook in place (installed or outdated), so
+ * the `cleo` it calls matters.
+ *
+ * @param inspections - the providers' states.
+ */
+export declare function heavyHookPresent(inspections: readonly HeavyHookInspection[]): boolean;
+/** One line of an init/upgrade report about the hook. */
+export interface HeavyHookReportLine {
+    /** `applied`: something was written; `skipped`: the hook is not (fully) in place. */
+    readonly status: 'applied' | 'skipped';
+    /** What happened, naming the provider and file. */
+    readonly details: string;
+    /** Why the hook is not in place (`skipped` only). */
+    readonly reason?: string;
+    /** The exact remedy (`skipped` only). */
+    readonly fix?: string;
+}
+/**
+ * The report lines for a delivery: every write, and every provider in use
+ * whose hook could not be put in place (blocked, unsupported or failed).
+ * Unchanged hooks and providers not in use add nothing.
+ *
+ * @param outcomes - the delivery outcomes.
+ * @returns the lines, in provider order.
+ */
+export declare function heavyHookReportLines(outcomes: readonly HeavyHookDeliveryOutcome[]): readonly HeavyHookReportLine[];
+/**
+ * Whether an inspection is a problem the user should fix: the hook is
+ * missing, outdated, blocked or unreadable for a provider in use (or present
+ * while the mode is off).
+ *
+ * @param inspection - one provider's state.
+ */
+export declare function isHeavyHookProblem(inspection: HeavyHookInspection): boolean;
+/**
+ * The one-line briefing warning when a provider in use has no working hook,
+ * or `null` when every provider in use is covered (or the check itself
+ * fails; doctor reports that). Kimi's permanent `unsupported` state and a
+ * team's `needs-consent` are left to `cleo doctor`, so the briefing does not
+ * repeat them every session. It makes no git spawns (`gitChecks: false`).
+ *
+ * @param projectRoot - the project root.
+ * @param options - environment and provider list (tests); `api` replaces the
+ *   run-time loaded adapters module.
+ */
+export declare function heavyHookBriefingWarning(projectRoot: string, options?: HeavyHookDeliveryOptions & {
+    readonly api?: HeavyHookDeliveryApi;
+}): Promise<string | null>;
+//# sourceMappingURL=heavy-command-hook-delivery.d.ts.map

package/dist/resources/heavy-command-hook-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heavy-command-hook-delivery.d.ts","sourceRoot":"","sources":["../../src/resources/heavy-command-hook-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAG7B,oEAAoE;AACpE,eAAO,MAAM,0BAA0B,0CAA0C,CAAC;AAElF,6DAA6D;AAC7D,eAAO,MAAM,cAAc,yCAAyC,CAAC;AAgBrE;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAS3E;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAE/F;AAED,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACxD;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,wBAAwB,GAAG;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAC/E,OAAO,CAAC,uBAAuB,CAAC,CAMlC;AAED,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACtD;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,wBAAwB,GAAG;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAC/E,OAAO,CAAC,yBAAyB,CAAC,CAKpC;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,wBAAwB,GAAG;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAC/E,OAAO,CAAC,iBAAiB,CAAC,CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,GAAG,OAAO,CAErF;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IACvC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,GAC5C,SAAS,mBAAmB,EAAE,CA4BhC;AAWD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAE3E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,wBAAwB,GAAG;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAC/E,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmBxB"}

package/dist/resources/heavy-command-hook-delivery.js

@@ -0,0 +1,204 @@
+/**
+ * Heavy-command hook delivery for `cleo init`, `cleo upgrade`, `cleo doctor`
+ * and the session briefing (T13124).
+ *
+ * The hook (`cleo hook heavy-command`, T12983) routes agent-run tests, builds
+ * and typechecks through `cleo run`, the machine-wide ResourceGovernor. It only
+ * helps where it is installed. init/upgrade used to install it through
+ * `AdapterManager`, whose discovery finds no adapter in any project, and a
+ * try/catch swallowed every failure, so on 2026-10-03 it was installed nowhere.
+ * Delivery is now its own step, with one outcome per provider in the report,
+ * and `cleo doctor` plus the briefing say when a provider in use lacks it.
+ *
+ * The per-provider installers live in `@cleocode/adapters` (provider delivery).
+ * That package builds on this one, so it is loaded at run time through its
+ * light `@cleocode/adapters/heavy-command-hook` entry point and validated
+ * against the {@link HeavyHookDeliveryApi} contract.
+ *
+ * @module resources/heavy-command-hook-delivery
+ * @task T13124
+ * @epic T13121
+ */
+import { configuredHeavyHookMode, resolveHeavyHookMode } from './heavy-command.js';
+/** The adapters entry point that carries the delivery functions. */
+export const HEAVY_HOOK_DELIVERY_MODULE = '@cleocode/adapters/heavy-command-hook';
+/** The command that installs or refreshes only this hook. */
+export const HEAVY_HOOK_FIX = 'cleo doctor heavy-command-hook --fix';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Whether a loaded module export implements {@link HeavyHookDeliveryApi}. */
+function isDeliveryApi(value) {
+    return (isRecord(value) &&
+        typeof value.syncProjectHeavyCommandHooks === 'function' &&
+        typeof value.inspectProjectHeavyCommandHooks === 'function' &&
+        typeof value.probeHeavyHookCli === 'function');
+}
+/**
+ * Load the delivery functions from `@cleocode/adapters`. The specifier is held
+ * in a variable so TypeScript does not resolve it at build time (adapters
+ * references core, so a static import would be a build cycle).
+ *
+ * @returns the delivery API.
+ * @throws when the module is missing or does not export the API.
+ */
+export async function loadHeavyHookDelivery() {
+    const specifier = HEAVY_HOOK_DELIVERY_MODULE;
+    const mod = await import(specifier);
+    const api = isRecord(mod) ? mod.heavyHookDeliveryApi : undefined;
+    if (!isDeliveryApi(api)) {
+        // @sync-invariant none:local-only a broken install of the adapters package; writes project config files, never a synced row
+        throw new Error(`${specifier} does not export heavyHookDeliveryApi`);
+    }
+    return api;
+}
+/**
+ * The hook mode init/upgrade install from: `resources.heavyCommandHook`
+ * (default `rewrite`). The `CLEO_HEAVY_COMMAND_HOOK` environment variable
+ * switches the hook at run time only and does not change what is installed.
+ *
+ * @param projectRoot - the project whose config to read.
+ */
+export async function installedHeavyHookMode(projectRoot) {
+    return resolveHeavyHookMode(undefined, await configuredHeavyHookMode(projectRoot));
+}
+/**
+ * Install, refresh or remove the hook for every provider in use in the project.
+ *
+ * @param projectRoot - the project root.
+ * @param options - environment and provider list (tests); `api` replaces the
+ *   run-time loaded adapters module.
+ * @returns the mode and each provider's outcome.
+ * @throws only when the adapters module cannot be loaded.
+ */
+export async function deliverHeavyCommandHooks(projectRoot, options = {}) {
+    const { api: injected, ...delivery } = options;
+    const api = injected ?? (await loadHeavyHookDelivery());
+    const mode = await installedHeavyHookMode(projectRoot);
+    const outcomes = await api.syncProjectHeavyCommandHooks(projectRoot, mode, delivery);
+    return { mode, outcomes };
+}
+/**
+ * Read-only: the hook's state for every provider in the project.
+ *
+ * @param projectRoot - the project root.
+ * @param options - environment and provider list (tests); `api` replaces the
+ *   run-time loaded adapters module.
+ * @returns the mode and each provider's state.
+ * @throws only when the adapters module cannot be loaded.
+ */
+export async function inspectHeavyCommandHooks(projectRoot, options = {}) {
+    const { api: injected, ...delivery } = options;
+    const api = injected ?? (await loadHeavyHookDelivery());
+    const mode = await installedHeavyHookMode(projectRoot);
+    return { mode, inspections: api.inspectProjectHeavyCommandHooks(projectRoot, mode, delivery) };
+}
+/**
+ * Whether the `cleo` on PATH, as the hook resolves it from the project, can
+ * answer the hook (an installed hook in front of an older CLEO governs
+ * nothing). Starts that `cleo` once.
+ *
+ * @param projectRoot - the project root.
+ * @param options - environment (tests); `api` replaces the run-time loaded
+ *   adapters module.
+ * @throws only when the adapters module cannot be loaded.
+ */
+export async function probeHeavyHookCliFor(projectRoot, options = {}) {
+    const { api: injected, ...delivery } = options;
+    const api = injected ?? (await loadHeavyHookDelivery());
+    return api.probeHeavyHookCli(projectRoot, delivery);
+}
+/**
+ * Whether any provider has CLEO's hook in place (installed or outdated), so
+ * the `cleo` it calls matters.
+ *
+ * @param inspections - the providers' states.
+ */
+export function heavyHookPresent(inspections) {
+    return inspections.some((i) => i.state === 'installed' || i.state === 'outdated');
+}
+/**
+ * The report lines for a delivery: every write, and every provider in use
+ * whose hook could not be put in place (blocked, unsupported or failed).
+ * Unchanged hooks and providers not in use add nothing.
+ *
+ * @param outcomes - the delivery outcomes.
+ * @returns the lines, in provider order.
+ */
+export function heavyHookReportLines(outcomes) {
+    const lines = [];
+    for (const o of outcomes) {
+        switch (o.status) {
+            case 'installed':
+            case 'updated':
+            case 'removed':
+                lines.push({
+                    status: 'applied',
+                    details: `heavy-command hook (${o.provider}): ${o.status} ${o.target}`,
+                });
+                break;
+            case 'blocked':
+            case 'unsupported':
+            case 'needs-consent':
+            case 'failed':
+                lines.push({
+                    status: 'skipped',
+                    details: `heavy-command hook (${o.provider}): ${o.status}, ${o.target}`,
+                    reason: `${o.provider} ${o.status}: ${o.reason ?? 'no reason given'}`,
+                    ...(o.remedy === undefined ? {} : { fix: o.remedy }),
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    return lines;
+}
+/** States that need the user's attention (the provider is in use). */
+const PROBLEM_STATES = new Set([
+    'missing',
+    'outdated',
+    'blocked',
+    'unreadable',
+    'needs-consent',
+]);
+/**
+ * Whether an inspection is a problem the user should fix: the hook is
+ * missing, outdated, blocked or unreadable for a provider in use (or present
+ * while the mode is off).
+ *
+ * @param inspection - one provider's state.
+ */
+export function isHeavyHookProblem(inspection) {
+    return PROBLEM_STATES.has(inspection.state);
+}
+/**
+ * The one-line briefing warning when a provider in use has no working hook,
+ * or `null` when every provider in use is covered (or the check itself
+ * fails; doctor reports that). Kimi's permanent `unsupported` state and a
+ * team's `needs-consent` are left to `cleo doctor`, so the briefing does not
+ * repeat them every session. It makes no git spawns (`gitChecks: false`).
+ *
+ * @param projectRoot - the project root.
+ * @param options - environment and provider list (tests); `api` replaces the
+ *   run-time loaded adapters module.
+ */
+export async function heavyHookBriefingWarning(projectRoot, options = {}) {
+    let report;
+    try {
+        // No git spawns on the briefing path (review LOW-5); `cleo doctor` runs them.
+        report = await inspectHeavyCommandHooks(projectRoot, { gitChecks: false, ...options });
+    }
+    catch {
+        return null;
+    }
+    // `needs-consent` is a team's standing decision about its own config: doctor
+    // reports it, the briefing does not repeat it every session.
+    const problems = report.inspections.filter((i) => isHeavyHookProblem(i) && i.state !== 'needs-consent');
+    if (problems.length === 0)
+        return null;
+    const list = problems.map((p) => `${p.provider} (${p.state})`).join(', ');
+    return (`Heavy-command hook not in place for ${list}: agent-run tests, builds and typechecks ` +
+        `bypass the machine-wide resource budget. Remedy: ${HEAVY_HOOK_FIX}`);
+}
+//# sourceMappingURL=heavy-command-hook-delivery.js.map

package/dist/resources/heavy-command-hook-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heavy-command-hook-delivery.js","sourceRoot":"","sources":["../../src/resources/heavy-command-hook-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAUH,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEnF,oEAAoE;AACpE,MAAM,CAAC,MAAM,0BAA0B,GAAG,uCAAuC,CAAC;AAElF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAG,sCAAsC,CAAC;AAErE,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,8EAA8E;AAC9E,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC;QACf,OAAO,KAAK,CAAC,4BAA4B,KAAK,UAAU;QACxD,OAAO,KAAK,CAAC,+BAA+B,KAAK,UAAU;QAC3D,OAAO,KAAK,CAAC,iBAAiB,KAAK,UAAU,CAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB;IACzC,MAAM,SAAS,GAAG,0BAA0B,CAAC;IAC7C,MAAM,GAAG,GAAY,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,4HAA4H;QAC5H,MAAM,IAAI,KAAK,CAAC,GAAG,SAAS,uCAAuC,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,WAAmB;IAC9D,OAAO,oBAAoB,CAAC,SAAS,EAAE,MAAM,uBAAuB,CAAC,WAAW,CAAC,CAAC,CAAC;AACrF,CAAC;AAUD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,WAAmB,EACnB,UAA8E,EAAE;IAEhF,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC/C,MAAM,GAAG,GAAG,QAAQ,IAAI,CAAC,MAAM,qBAAqB,EAAE,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,4BAA4B,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAUD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,WAAmB,EACnB,UAA8E,EAAE;IAEhF,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC/C,MAAM,GAAG,GAAG,QAAQ,IAAI,CAAC,MAAM,qBAAqB,EAAE,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACvD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,+BAA+B,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;AACjG,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,WAAmB,EACnB,UAA8E,EAAE;IAEhF,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC/C,MAAM,GAAG,GAAG,QAAQ,IAAI,CAAC,MAAM,qBAAqB,EAAE,CAAC,CAAC;IACxD,OAAO,GAAG,CAAC,iBAAiB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAA2C;IAC1E,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC;AACpF,CAAC;AAcD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAA6C;IAE7C,MAAM,KAAK,GAA0B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC;YACjB,KAAK,WAAW,CAAC;YACjB,KAAK,SAAS,CAAC;YACf,KAAK,SAAS;gBACZ,KAAK,CAAC,IAAI,CAAC;oBACT,MAAM,EAAE,SAAS;oBACjB,OAAO,EAAE,uBAAuB,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,EAAE;iBACvE,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,SAAS,CAAC;YACf,KAAK,aAAa,CAAC;YACnB,KAAK,eAAe,CAAC;YACrB,KAAK,QAAQ;gBACX,KAAK,CAAC,IAAI,CAAC;oBACT,MAAM,EAAE,SAAS;oBACjB,OAAO,EAAE,uBAAuB,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE;oBACvE,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,iBAAiB,EAAE;oBACrE,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;iBACrD,CAAC,CAAC;gBACH,MAAM;YACR;gBACE,MAAM;QACV,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,sEAAsE;AACtE,MAAM,cAAc,GAA8C,IAAI,GAAG,CAAC;IACxE,SAAS;IACT,UAAU;IACV,SAAS;IACT,YAAY;IACZ,eAAe;CAChB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAA+B;IAChE,OAAO,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,WAAmB,EACnB,UAA8E,EAAE;IAEhF,IAAI,MAAiC,CAAC;IACtC,IAAI,CAAC;QACH,8EAA8E;QAC9E,MAAM,GAAG,MAAM,wBAAwB,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,6EAA6E;IAC7E,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CACxC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,eAAe,CAC5D,CAAC;IACF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1E,OAAO,CACL,uCAAuC,IAAI,2CAA2C;QACtF,oDAAoD,cAAc,EAAE,CACrE,CAAC;AACJ,CAAC"}

package/dist/resources/heavy-command.d.ts

@@ -77,6 +77,75 @@ export interface HeavyCommandPlanOptions {
  * ```
  */
 export declare function planHeavyCommand(command: string, opts: HeavyCommandPlanOptions): HeavyCommandPlan;
+/**
+ * Whether a Claude Code Bash rule pattern (the text inside `Bash(…)`) matches
+ * one subcommand's text, as the permissions reference specifies: `*` stands for
+ * any text including spaces, a trailing `:*` equals a trailing ` *`, a trailing
+ * ` *` that is the rule's only wildcard also matches the bare command, and a
+ * rule without `*` matches one exact command. The bare `Bash` rule is `*`.
+ *
+ * @param pattern - the rule pattern, e.g. `pnpm test *` or `npm run test:*`.
+ * @param text - one subcommand as written.
+ *
+ * @example
+ * ```ts
+ * claudeBashRuleMatches('pnpm test *', 'pnpm test'); // true
+ * claudeBashRuleMatches('pnpm test:*', 'pnpm test --run'); // true
+ * claudeBashRuleMatches('ls *', 'lsof'); // false
+ * ```
+ */
+export declare function claudeBashRuleMatches(pattern: string, text: string): boolean;
+/** Options for {@link claudePreApproval}. */
+export interface ClaudePreApprovalOptions {
+    /** The directory the command line starts in. */
+    readonly cwd: string;
+    /**
+     * Claude Code's primary working directory (`CLAUDE_PROJECT_DIR`). A `cd`
+     * and the read-only commands are accepted only inside it.
+     */
+    readonly workingDir: string;
+}
+/** Whether Claude Code would run a command line without a prompt. */
+export type ClaudePreApproval = {
+    readonly approved: true;
+} | {
+    readonly approved: false;
+    readonly reason: string;
+};
+/**
+ * Whether Claude Code would run `command` WITHOUT a prompt because the user's
+ * Bash allow rules approve it: every subcommand (split at `&&`, `||`, `;`,
+ * `|`, `|&` and newlines, as Claude Code splits) matches an allow rule, or is
+ * a narrow read-only form Claude Code runs unprompted (`cd` into the working
+ * directory, `tail -50`, `grep -v x`, …).
+ *
+ * The heavy-command hook uses this to rewrite a command in Claude Code's
+ * default, acceptEdits, dontAsk and auto modes with `permissionDecision:
+ * "allow"`: the user already approved the command, and the rewrite only makes
+ * it queue for the machine-wide budget. So this check must never approve more
+ * than Claude Code would. It is deliberately narrower: no wrapper stripping
+ * (`timeout`, `nice`), no leading assignments, no expansions, no
+ * substitutions, subshells, compound commands or background jobs, no
+ * redirection except to `/dev/null` or a file descriptor, and both the stage
+ * as written and its words alone must match the same rule. Anything else is
+ * "not pre-approved" and the hook falls back to a warning. Deny and ask rules
+ * are not checked here (the hook checks them, and Claude Code enforces them
+ * on the rewritten command regardless).
+ *
+ * @param command - the command line as the agent wrote it.
+ * @param allowPatterns - the patterns of the user's `Bash(…)` allow rules (`*` for a bare `Bash`).
+ * @param opts - where the line starts, and Claude Code's working directory.
+ * @returns approved, or the first reason it is not.
+ *
+ * @example
+ * ```ts
+ * claudePreApproval('pnpm test 2>&1 | tail -50', ['pnpm test *'], { cwd: '/repo', workingDir: '/repo' });
+ * // { approved: true }
+ * claudePreApproval('pnpm test && rm -rf dist', ['pnpm test *'], { cwd: '/repo', workingDir: '/repo' });
+ * // { approved: false, reason: '`rm` is not approved by an allow rule' }
+ * ```
+ */
+export declare function claudePreApproval(command: string, allowPatterns: readonly string[], opts: ClaudePreApprovalOptions): ClaudePreApproval;
 /**
  * Whether `value` (trimmed, any case) names a hook mode. The hook reads the
  * config only when the environment variable does not.

package/dist/resources/heavy-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heavy-command.d.ts","sourceRoot":"","sources":["../../src/resources/heavy-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EAGjB,MAAM,qBAAqB,CAAC;AAuf7B;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AA2GD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,GAAG,gBAAgB,CAajG;AAQD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,oBAAoB,CAMtB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAS3C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWxD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAWrF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqBlF"}
+{"version":3,"file":"heavy-command.d.ts","sourceRoot":"","sources":["../../src/resources/heavy-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EAGjB,MAAM,qBAAqB,CAAC;AAqgB7B;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AA2GD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,GAAG,gBAAgB,CAiBjG;AA2PD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ5E;AA+BD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA0E1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,IAAI,EAAE,wBAAwB,GAC7B,iBAAiB,CAuEnB;AAQD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,oBAAoB,CAMtB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAS3C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWxD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAWrF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqBlF"}