@dzhechkov/harness-core 0.4.4 → 0.5.0

package/dist/codex-hooks.d.ts

@@ -0,0 +1,258 @@
+/**
+ * The Codex hook registry model (`crossrt-2-codex-hooks`, ADR-001).
+ *
+ * Pure: paths, the managed entry set, sha-based attribution, the manifest, drift, and the TOML text
+ * of a trust block. Every filesystem and process action lives in `operations.ts`.
+ *
+ * ## Measured facts this module encodes (M0 spike, codex-cli 0.147.0 — see
+ * `features/crossrt-2-codex-hooks/07_code_changes/probe-results/spike-arming.md`)
+ *
+ * - `$CODEX_HOME/hooks.json` is the user registry and **`CODEX_HOME` relocates discovery**, which is
+ *   what makes every automated probe hermetic (G-H). `$CODEX_HOME/hooks/hooks.json` is the PLUGIN
+ *   bundle layout and does not fire.
+ * - Entries are trust-gated. An untrusted entry is silently not run. Trust is persisted per entry in
+ *   `$CODEX_HOME/config.toml` as `[hooks.state."<key>"] trusted_hash = "<currentHash>"`, and both
+ *   `key` and `currentHash` come from the runtime's own `hooks/list` RPC — they are **read, never
+ *   computed**, because `currentHash`'s preimage is internal to codex.
+ * - `timeout` is in SECONDS and IS honored (600 → 5, MEASURED). `timeoutSec` in an entry is
+ *   **silently ignored** and leaves the 600 s default in place — which is why this module emits
+ *   `timeout` and a test pins the key set (AM-15, now probe-proven by spike S2).
+ * - The hook runner spawns via `$SHELL -lc`, so the emitted command is a SHELL string: the
+ *   interpreter is an absolute `process.execPath` and both paths are single-quoted (AM-32/AM-35d).
+ *
+ * @packageDocumentation
+ */
+/** Bump when a helper BODY changes: a changed body changes codex's `currentHash` ⇒ re-trust. */
+export declare const DZ_HOOK_HELPER_VERSION = 1;
+/** Seconds. Probe-proven (spike S2): `timeout` is honored, the unset default is 600 s. */
+export declare const DZ_HOOK_TIMEOUT_SECONDS = 5;
+/** The wide matcher (AM-8). Narrowing needs a recorded live probe; the guard keys on the payload. */
+export declare const DZ_VETO_MATCHER = "Bash|shell|local_shell";
+export interface CodexHooksPaths {
+    readonly codexHome: string;
+    readonly registry: string;
+    readonly configToml: string;
+    readonly helperDir: string;
+    readonly vetoHelper: string;
+    readonly recallHelper: string;
+    readonly manifest: string;
+    readonly errorLog: string;
+}
+/** Every path this leg touches, all `CODEX_HOME`-relative (AM-13). */
+export declare function codexHooksPaths(codexHome: string): CodexHooksPaths;
+/** The EMITTER's write-set (AM-12). The RUNTIME's is stated separately — see {@link runtimeWriteSet}. */
+export declare function emitterWriteSet(paths: CodexHooksPaths): readonly string[];
+/**
+ * The RUNTIME's write-set (AM-33). Exactly one path beyond the emitter's, and it is
+ * `CODEX_HOME`-local: a helper must never create a `.dz/` inside a repository the user merely ran
+ * `codex` in. (Recall rows are the one exception and they are opt-in-gated: they land in an
+ * ALREADY-EXISTING opted-in project's `.dz/`, so nothing is ever created.)
+ */
+export declare function runtimeWriteSet(paths: CodexHooksPaths): readonly string[];
+/** A single quote inside a single-quoted shell word cannot be escaped — such a path is REFUSED. */
+export declare function isSafeForSingleQuote(path: string): boolean;
+export declare function singleQuote(path: string): string;
+/**
+ * The shell string codex runs. Absolute interpreter + single-quoted paths (AM-32/AM-35d).
+ * @throws when either path cannot be safely quoted — never emit a broken entry that READS installed.
+ */
+export declare function buildHookCommand(nodePath: string, scriptPath: string): string;
+export type CodexHookId = 'codex-veto' | 'codex-recall';
+export type CodexHookEvent = 'PreToolUse' | 'UserPromptSubmit';
+export interface CodexHookSpec {
+    readonly id: CodexHookId;
+    readonly event: CodexHookEvent;
+    readonly matcher?: string;
+    readonly script: 'veto' | 'recall';
+}
+/** The two entries this leg ships, and nothing else. */
+export declare const CODEX_MANAGED_HOOKS: readonly CodexHookSpec[];
+export interface BuildManagedEntriesOptions {
+    readonly nodePath: string;
+    readonly paths: CodexHooksPaths;
+}
+export interface ManagedEntry {
+    readonly id: CodexHookId;
+    readonly event: CodexHookEvent;
+    readonly command: string;
+    readonly entry: Record<string, unknown>;
+}
+/**
+ * Build the managed entries.
+ *
+ * Key set is EXACTLY `{matcher?, hooks:[{type, command, timeout}]}` (AM-15). `timeout` is included
+ * because spike S2 recorded a probe proving the registry loads with it AND honors it; every other
+ * key stays out until it has its own probe.
+ */
+export declare function buildManagedEntries(opts: BuildManagedEntriesOptions): readonly ManagedEntry[];
+/** `managed` in the shape {@link mergeManagedHookEntries} takes. */
+export declare function managedByEvent(entries: readonly ManagedEntry[]): Record<string, unknown[]>;
+export declare function codexHookSha256(text: string): string;
+export interface CodexHookManifestEntry {
+    readonly id: CodexHookId;
+    readonly event: CodexHookEvent;
+    readonly matcher?: string;
+    readonly commandSha256: string;
+    /** The runtime trust key, as reported by `hooks/list`. Absent until a list succeeded. */
+    readonly trustKey?: string;
+}
+export interface CodexHookVerifyRecord {
+    readonly verdict: string;
+    readonly trust: string;
+    readonly bypassed: boolean;
+    readonly at: string;
+    readonly transcript?: string;
+}
+export interface CodexHookManifest {
+    readonly version: 1;
+    readonly writtenAt: string;
+    readonly codexVersion: string;
+    readonly registryPath: string;
+    readonly helperVersion: number;
+    readonly nodePath: string;
+    readonly entries: readonly CodexHookManifestEntry[];
+    readonly lastVerify?: CodexHookVerifyRecord;
+}
+export interface BuildManifestOptions {
+    readonly entries: readonly ManagedEntry[];
+    readonly paths: CodexHooksPaths;
+    readonly codexVersion: string;
+    readonly writtenAt: string;
+    readonly nodePath: string;
+    readonly trustKeys?: Readonly<Record<string, string>>;
+    readonly lastVerify?: CodexHookVerifyRecord;
+}
+export declare function buildCodexHookManifest(opts: BuildManifestOptions): CodexHookManifest;
+export declare function parseCodexHookManifest(text: string): CodexHookManifest | undefined;
+/**
+ * Attribution is `codexHookSha256(command) ∈ manifest` — never a substring guess.
+ *
+ * ADR-001 §3: dz deletes only what it can PROVE it wrote. An entry that merely looks like ours (it
+ * mentions our helper filename) but whose command hash is absent from the manifest is KEPT, counted
+ * in `unattributable`, and warned about. A hand-edited managed command therefore survives.
+ */
+export declare function isDzManagedEntry(entry: unknown, manifest: CodexHookManifest | undefined): boolean;
+/** Cheap resemblance test — drives the `unattributable` COUNT only, never a deletion. */
+export declare function looksLikeDzEntry(entry: unknown): boolean;
+export interface CodexRegistry {
+    /** Every top-level key other than `hooks`, preserved verbatim. */
+    readonly rest: Record<string, unknown>;
+    readonly hooks: Record<string, unknown[]>;
+}
+export type ParseRegistryResult = {
+    readonly ok: true;
+    readonly registry: CodexRegistry;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Parse an existing registry. An unparseable file is an ERROR, never an empty registry: silently
+ * treating it as `{}` would overwrite entries we promised to preserve (I1).
+ */
+export declare function parseCodexRegistry(text: string | undefined): ParseRegistryResult;
+export declare function serializeCodexRegistry(registry: CodexRegistry): string;
+export interface CodexHooksPlan {
+    readonly registry: CodexRegistry;
+    readonly text: string;
+    readonly changed: boolean;
+    readonly foreignPreserved: number;
+    readonly unattributable: number;
+}
+export interface PlanCodexHooksInput {
+    readonly currentText: string | undefined;
+    readonly entries: readonly ManagedEntry[];
+    readonly manifest: CodexHookManifest | undefined;
+}
+/**
+ * Compute the merged registry.
+ *
+ * The merge itself is `mergeManagedHookEntries` — the SAME implementation the Claude path uses
+ * (AM-3 / G-E). Only the attribution predicate differs.
+ */
+export declare function planCodexHooks(input: PlanCodexHooksInput): {
+    ok: true;
+    plan: CodexHooksPlan;
+} | {
+    ok: false;
+    error: string;
+};
+export interface RemoveCodexHooksResult {
+    readonly registry: CodexRegistry;
+    readonly text: string;
+    readonly removed: number;
+    readonly changed: boolean;
+    readonly unattributable: number;
+}
+/**
+ * `--remove`: delete ONLY manifest-attributed entries.
+ *
+ * With the manifest deleted this removes **zero** entries and reports them all as `unattributable`.
+ * That is the intended, conservative behaviour: dz never deletes what it cannot prove it wrote.
+ */
+export declare function removeCodexHooks(currentText: string | undefined, manifest: CodexHookManifest | undefined): {
+    ok: true;
+    result: RemoveCodexHooksResult;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DriftReport {
+    /** Both managed entries present in the registry and attributable. */
+    readonly installed: boolean;
+    readonly presentIds: readonly CodexHookId[];
+    readonly missingIds: readonly CodexHookId[];
+    readonly foreignPreserved: number;
+    readonly unattributable: number;
+    /** A managed command whose hash is not the one the manifest records for that id. */
+    readonly drifted: readonly CodexHookId[];
+}
+/** `--check` recomputes from the FILE; it never trusts the manifest's claim on its own. */
+export declare function diffCodexHooks(currentText: string | undefined, entries: readonly ManagedEntry[], manifest: CodexHookManifest | undefined): DriftReport;
+/** codex's snake_case event spelling inside a trust key (MEASURED from `hooks/list`). */
+export declare function trustEventName(event: CodexHookEvent): string;
+/**
+ * The trust key codex uses: `<sourcePath>:<snake_event>:<groupIndex>:<hookIndex>`.
+ *
+ * This is the EXPECTED spelling, used only to cross-check what `hooks/list` reports. The install
+ * path uses the reported key verbatim — a computed key that drifts from the runtime's would arm
+ * nothing while reading like success.
+ */
+export declare function expectedTrustKey(registryPath: string, event: CodexHookEvent, groupIndex: number, hookIndex: number): string;
+export interface HookTrustRow {
+    readonly key: string;
+    readonly trustedHash: string;
+}
+export declare const DZ_TRUST_BEGIN = "# --- dz codex hooks trust (managed block, dz-rewritten) ---";
+export declare const DZ_TRUST_END = "# --- end dz codex hooks trust ---";
+/**
+ * Render dz's trust rows as a MANAGED BLOCK in `config.toml`.
+ *
+ * A managed block, not a whole-file rewrite: `~/.codex/config.toml` already carries a
+ * `ruvnet-brain` managed block and seven `[projects."…"]` trust rows on this machine (MEASURED),
+ * and dz is not the only writer. The block is delimited so a re-run replaces exactly dz's rows and
+ * nothing else.
+ */
+export declare function renderTrustBlock(rows: readonly HookTrustRow[]): string;
+/** Replace (or append) dz's managed trust block, leaving every other byte of config.toml alone. */
+export declare function upsertTrustBlock(configToml: string, rows: readonly HookTrustRow[]): string;
+export interface HooksListHookMetadata {
+    readonly key: string;
+    readonly eventName: string;
+    readonly command?: string | null;
+    readonly sourcePath: string;
+    readonly source: string;
+    readonly currentHash: string;
+    readonly trustStatus: 'managed' | 'untrusted' | 'trusted' | 'modified';
+    readonly enabled: boolean;
+    readonly timeoutSec: number;
+}
+/**
+ * Pick, from a `hooks/list` response, the metadata of the entries WE wrote — matched on the exact
+ * command string, so a third party's entry can never inherit dz's trust write.
+ */
+export declare function selectOwnHookMetadata(hooks: readonly HooksListHookMetadata[], entries: readonly ManagedEntry[]): {
+    readonly id: CodexHookId;
+    readonly meta: HooksListHookMetadata;
+}[];
+//# sourceMappingURL=codex-hooks.d.ts.map

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

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

package/dist/codex-hooks.js

@@ -0,0 +1,391 @@
+/**
+ * The Codex hook registry model (`crossrt-2-codex-hooks`, ADR-001).
+ *
+ * Pure: paths, the managed entry set, sha-based attribution, the manifest, drift, and the TOML text
+ * of a trust block. Every filesystem and process action lives in `operations.ts`.
+ *
+ * ## Measured facts this module encodes (M0 spike, codex-cli 0.147.0 — see
+ * `features/crossrt-2-codex-hooks/07_code_changes/probe-results/spike-arming.md`)
+ *
+ * - `$CODEX_HOME/hooks.json` is the user registry and **`CODEX_HOME` relocates discovery**, which is
+ *   what makes every automated probe hermetic (G-H). `$CODEX_HOME/hooks/hooks.json` is the PLUGIN
+ *   bundle layout and does not fire.
+ * - Entries are trust-gated. An untrusted entry is silently not run. Trust is persisted per entry in
+ *   `$CODEX_HOME/config.toml` as `[hooks.state."<key>"] trusted_hash = "<currentHash>"`, and both
+ *   `key` and `currentHash` come from the runtime's own `hooks/list` RPC — they are **read, never
+ *   computed**, because `currentHash`'s preimage is internal to codex.
+ * - `timeout` is in SECONDS and IS honored (600 → 5, MEASURED). `timeoutSec` in an entry is
+ *   **silently ignored** and leaves the 600 s default in place — which is why this module emits
+ *   `timeout` and a test pins the key set (AM-15, now probe-proven by spike S2).
+ * - The hook runner spawns via `$SHELL -lc`, so the emitted command is a SHELL string: the
+ *   interpreter is an absolute `process.execPath` and both paths are single-quoted (AM-32/AM-35d).
+ *
+ * @packageDocumentation
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { mergeManagedHookEntries } from './managed-hooks.js';
+/** Bump when a helper BODY changes: a changed body changes codex's `currentHash` ⇒ re-trust. */
+export const DZ_HOOK_HELPER_VERSION = 1;
+/** Seconds. Probe-proven (spike S2): `timeout` is honored, the unset default is 600 s. */
+export const DZ_HOOK_TIMEOUT_SECONDS = 5;
+/** The wide matcher (AM-8). Narrowing needs a recorded live probe; the guard keys on the payload. */
+export const DZ_VETO_MATCHER = 'Bash|shell|local_shell';
+/** Every path this leg touches, all `CODEX_HOME`-relative (AM-13). */
+export function codexHooksPaths(codexHome) {
+    const helperDir = join(codexHome, 'dz-hooks');
+    return {
+        codexHome,
+        registry: join(codexHome, 'hooks.json'),
+        configToml: join(codexHome, 'config.toml'),
+        helperDir,
+        vetoHelper: join(helperDir, 'dz-codex-veto.cjs'),
+        recallHelper: join(helperDir, 'dz-codex-recall.cjs'),
+        manifest: join(helperDir, 'manifest.json'),
+        errorLog: join(helperDir, 'helper-errors.jsonl'),
+    };
+}
+/** The EMITTER's write-set (AM-12). The RUNTIME's is stated separately — see {@link runtimeWriteSet}. */
+export function emitterWriteSet(paths) {
+    return [paths.registry, paths.vetoHelper, paths.recallHelper, paths.manifest];
+}
+/**
+ * The RUNTIME's write-set (AM-33). Exactly one path beyond the emitter's, and it is
+ * `CODEX_HOME`-local: a helper must never create a `.dz/` inside a repository the user merely ran
+ * `codex` in. (Recall rows are the one exception and they are opt-in-gated: they land in an
+ * ALREADY-EXISTING opted-in project's `.dz/`, so nothing is ever created.)
+ */
+export function runtimeWriteSet(paths) {
+    return [paths.errorLog];
+}
+/* -------------------------------------------------------------------------- */
+/* Quoting                                                                     */
+/* -------------------------------------------------------------------------- */
+/** A single quote inside a single-quoted shell word cannot be escaped — such a path is REFUSED. */
+export function isSafeForSingleQuote(path) {
+    return typeof path === 'string' && path !== '' && !path.includes("'") && !path.includes('\n');
+}
+export function singleQuote(path) {
+    return `'${path}'`;
+}
+/**
+ * The shell string codex runs. Absolute interpreter + single-quoted paths (AM-32/AM-35d).
+ * @throws when either path cannot be safely quoted — never emit a broken entry that READS installed.
+ */
+export function buildHookCommand(nodePath, scriptPath) {
+    if (!isSafeForSingleQuote(nodePath) || !isSafeForSingleQuote(scriptPath)) {
+        throw new Error(`refusing to emit a hook command containing an unquotable path (single quote or newline): ${nodePath} ${scriptPath}`);
+    }
+    return `${singleQuote(nodePath)} ${singleQuote(scriptPath)}`;
+}
+/** The two entries this leg ships, and nothing else. */
+export const CODEX_MANAGED_HOOKS = [
+    { id: 'codex-veto', event: 'PreToolUse', matcher: DZ_VETO_MATCHER, script: 'veto' },
+    { id: 'codex-recall', event: 'UserPromptSubmit', script: 'recall' },
+];
+/**
+ * Build the managed entries.
+ *
+ * Key set is EXACTLY `{matcher?, hooks:[{type, command, timeout}]}` (AM-15). `timeout` is included
+ * because spike S2 recorded a probe proving the registry loads with it AND honors it; every other
+ * key stays out until it has its own probe.
+ */
+export function buildManagedEntries(opts) {
+    return CODEX_MANAGED_HOOKS.map((spec) => {
+        const script = spec.script === 'veto' ? opts.paths.vetoHelper : opts.paths.recallHelper;
+        const command = buildHookCommand(opts.nodePath, script);
+        const entry = {
+            ...(spec.matcher !== undefined ? { matcher: spec.matcher } : {}),
+            hooks: [{ type: 'command', command, timeout: DZ_HOOK_TIMEOUT_SECONDS }],
+        };
+        return { id: spec.id, event: spec.event, command, entry };
+    });
+}
+/** `managed` in the shape {@link mergeManagedHookEntries} takes. */
+export function managedByEvent(entries) {
+    const out = {};
+    for (const e of entries) {
+        (out[e.event] ??= []).push(e.entry);
+    }
+    return out;
+}
+/* -------------------------------------------------------------------------- */
+/* Manifest + attribution                                                      */
+/* -------------------------------------------------------------------------- */
+export function codexHookSha256(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+export function buildCodexHookManifest(opts) {
+    return {
+        version: 1,
+        writtenAt: opts.writtenAt,
+        codexVersion: opts.codexVersion,
+        registryPath: opts.paths.registry,
+        helperVersion: DZ_HOOK_HELPER_VERSION,
+        nodePath: opts.nodePath,
+        entries: opts.entries.map((e) => {
+            const spec = CODEX_MANAGED_HOOKS.find((s) => s.id === e.id);
+            const trustKey = opts.trustKeys?.[e.id];
+            return {
+                id: e.id,
+                event: e.event,
+                ...(spec?.matcher !== undefined ? { matcher: spec.matcher } : {}),
+                commandSha256: codexHookSha256(e.command),
+                ...(trustKey !== undefined ? { trustKey } : {}),
+            };
+        }),
+        ...(opts.lastVerify !== undefined ? { lastVerify: opts.lastVerify } : {}),
+    };
+}
+export function parseCodexHookManifest(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== 'object')
+            return undefined;
+        const m = parsed;
+        if (m.version !== 1 || !Array.isArray(m.entries))
+            return undefined;
+        return m;
+    }
+    catch {
+        return undefined;
+    }
+}
+function entryCommands(entry) {
+    const e = entry;
+    if (Array.isArray(e?.hooks))
+        return e.hooks.map((h) => String(h?.command ?? ''));
+    return [String(e?.command ?? '')];
+}
+/**
+ * Attribution is `codexHookSha256(command) ∈ manifest` — never a substring guess.
+ *
+ * ADR-001 §3: dz deletes only what it can PROVE it wrote. An entry that merely looks like ours (it
+ * mentions our helper filename) but whose command hash is absent from the manifest is KEPT, counted
+ * in `unattributable`, and warned about. A hand-edited managed command therefore survives.
+ */
+export function isDzManagedEntry(entry, manifest) {
+    if (manifest === undefined)
+        return false;
+    const known = new Set(manifest.entries.map((e) => e.commandSha256));
+    return entryCommands(entry).some((cmd) => cmd !== '' && known.has(codexHookSha256(cmd)));
+}
+/** Cheap resemblance test — drives the `unattributable` COUNT only, never a deletion. */
+export function looksLikeDzEntry(entry) {
+    return entryCommands(entry).some((cmd) => cmd.includes('dz-codex-veto.cjs') || cmd.includes('dz-codex-recall.cjs'));
+}
+/**
+ * Parse an existing registry. An unparseable file is an ERROR, never an empty registry: silently
+ * treating it as `{}` would overwrite entries we promised to preserve (I1).
+ */
+export function parseCodexRegistry(text) {
+    if (text === undefined || text.trim() === '') {
+        return { ok: true, registry: { rest: {}, hooks: {} } };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        return { ok: false, error: `hooks.json is not valid JSON: ${err.message}` };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, error: 'hooks.json must be a JSON object' };
+    }
+    const obj = parsed;
+    const rawHooks = obj['hooks'];
+    if (rawHooks !== undefined && (rawHooks === null || typeof rawHooks !== 'object' || Array.isArray(rawHooks))) {
+        return { ok: false, error: 'hooks.json "hooks" must be an object keyed by event name' };
+    }
+    const hooks = {};
+    for (const [event, value] of Object.entries((rawHooks ?? {}))) {
+        hooks[event] = Array.isArray(value) ? [...value] : [];
+    }
+    const rest = {};
+    for (const [k, v] of Object.entries(obj))
+        if (k !== 'hooks')
+            rest[k] = v;
+    return { ok: true, registry: { rest, hooks } };
+}
+export function serializeCodexRegistry(registry) {
+    return `${JSON.stringify({ ...registry.rest, hooks: registry.hooks }, null, 2)}\n`;
+}
+/**
+ * Compute the merged registry.
+ *
+ * The merge itself is `mergeManagedHookEntries` — the SAME implementation the Claude path uses
+ * (AM-3 / G-E). Only the attribution predicate differs.
+ */
+export function planCodexHooks(input) {
+    const parsed = parseCodexRegistry(input.currentText);
+    if (!parsed.ok)
+        return { ok: false, error: parsed.error };
+    // The union of the manifest's hashes and the ones we are about to write: on a re-run the manifest
+    // is current, on a helper-version bump it is not, and BOTH vintages of our own entry must be
+    // replaced rather than duplicated.
+    const selfManifest = {
+        version: 1,
+        writtenAt: '',
+        codexVersion: '',
+        registryPath: '',
+        helperVersion: DZ_HOOK_HELPER_VERSION,
+        nodePath: '',
+        entries: [
+            ...(input.manifest?.entries ?? []),
+            ...input.entries.map((e) => ({ id: e.id, event: e.event, commandSha256: codexHookSha256(e.command) })),
+        ],
+    };
+    const plan = mergeManagedHookEntries(parsed.registry.hooks, managedByEvent(input.entries), {
+        isManaged: (entry) => isDzManagedEntry(entry, selfManifest),
+        looksLikeOurs: (entry) => looksLikeDzEntry(entry) && !isDzManagedEntry(entry, selfManifest),
+        reportLabel: 'codex',
+    });
+    const registry = { rest: parsed.registry.rest, hooks: plan.hooks };
+    return {
+        ok: true,
+        plan: {
+            registry,
+            text: serializeCodexRegistry(registry),
+            changed: plan.changed,
+            foreignPreserved: plan.foreignPreserved,
+            unattributable: plan.unattributable,
+        },
+    };
+}
+/**
+ * `--remove`: delete ONLY manifest-attributed entries.
+ *
+ * With the manifest deleted this removes **zero** entries and reports them all as `unattributable`.
+ * That is the intended, conservative behaviour: dz never deletes what it cannot prove it wrote.
+ */
+export function removeCodexHooks(currentText, manifest) {
+    const parsed = parseCodexRegistry(currentText);
+    if (!parsed.ok)
+        return { ok: false, error: parsed.error };
+    const hooks = {};
+    let removed = 0;
+    let unattributable = 0;
+    for (const [event, entries] of Object.entries(parsed.registry.hooks)) {
+        const kept = entries.filter((entry) => {
+            if (isDzManagedEntry(entry, manifest)) {
+                removed += 1;
+                return false;
+            }
+            if (looksLikeDzEntry(entry))
+                unattributable += 1;
+            return true;
+        });
+        hooks[event] = kept;
+    }
+    const registry = { rest: parsed.registry.rest, hooks };
+    return {
+        ok: true,
+        result: { registry, text: serializeCodexRegistry(registry), removed, changed: removed > 0, unattributable },
+    };
+}
+/** `--check` recomputes from the FILE; it never trusts the manifest's claim on its own. */
+export function diffCodexHooks(currentText, entries, manifest) {
+    const parsed = parseCodexRegistry(currentText);
+    const hooks = parsed.ok ? parsed.registry.hooks : {};
+    const present = [];
+    const drifted = [];
+    let foreignPreserved = 0;
+    let unattributable = 0;
+    const wantByEvent = new Map(entries.map((e) => [e.event, e]));
+    for (const [event, list] of Object.entries(hooks)) {
+        for (const entry of list) {
+            const want = wantByEvent.get(event);
+            const cmds = entryCommands(entry);
+            if (want !== undefined && cmds.includes(want.command)) {
+                present.push(want.id);
+                continue;
+            }
+            if (isDzManagedEntry(entry, manifest)) {
+                // Ours by manifest, but not the command we would write now: an old helper version.
+                const id = manifest?.entries.find((m) => cmds.some((c) => codexHookSha256(c) === m.commandSha256))?.id;
+                if (id !== undefined)
+                    drifted.push(id);
+                continue;
+            }
+            foreignPreserved += 1;
+            if (looksLikeDzEntry(entry))
+                unattributable += 1;
+        }
+    }
+    const missing = entries.map((e) => e.id).filter((id) => !present.includes(id));
+    return {
+        installed: missing.length === 0,
+        presentIds: present,
+        missingIds: missing,
+        foreignPreserved,
+        unattributable,
+        drifted,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Trust (the M0 arming route)                                                 */
+/* -------------------------------------------------------------------------- */
+/** codex's snake_case event spelling inside a trust key (MEASURED from `hooks/list`). */
+export function trustEventName(event) {
+    return event === 'PreToolUse' ? 'pre_tool_use' : 'user_prompt_submit';
+}
+/**
+ * The trust key codex uses: `<sourcePath>:<snake_event>:<groupIndex>:<hookIndex>`.
+ *
+ * This is the EXPECTED spelling, used only to cross-check what `hooks/list` reports. The install
+ * path uses the reported key verbatim — a computed key that drifts from the runtime's would arm
+ * nothing while reading like success.
+ */
+export function expectedTrustKey(registryPath, event, groupIndex, hookIndex) {
+    return `${registryPath}:${trustEventName(event)}:${groupIndex}:${hookIndex}`;
+}
+/** TOML-escape a bare-string key (the key is an absolute path plus `:` separators). */
+function tomlQuote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+export const DZ_TRUST_BEGIN = '# --- dz codex hooks trust (managed block, dz-rewritten) ---';
+export const DZ_TRUST_END = '# --- end dz codex hooks trust ---';
+/**
+ * Render dz's trust rows as a MANAGED BLOCK in `config.toml`.
+ *
+ * A managed block, not a whole-file rewrite: `~/.codex/config.toml` already carries a
+ * `ruvnet-brain` managed block and seven `[projects."…"]` trust rows on this machine (MEASURED),
+ * and dz is not the only writer. The block is delimited so a re-run replaces exactly dz's rows and
+ * nothing else.
+ */
+export function renderTrustBlock(rows) {
+    if (rows.length === 0)
+        return '';
+    const body = rows
+        .map((r) => `[hooks.state.${tomlQuote(r.key)}]\ntrusted_hash = ${tomlQuote(r.trustedHash)}`)
+        .join('\n');
+    return `${DZ_TRUST_BEGIN}\n${body}\n${DZ_TRUST_END}\n`;
+}
+/** Replace (or append) dz's managed trust block, leaving every other byte of config.toml alone. */
+export function upsertTrustBlock(configToml, rows) {
+    const block = renderTrustBlock(rows);
+    const begin = configToml.indexOf(DZ_TRUST_BEGIN);
+    const end = configToml.indexOf(DZ_TRUST_END);
+    if (begin >= 0 && end > begin) {
+        const before = configToml.slice(0, begin);
+        const after = configToml.slice(end + DZ_TRUST_END.length).replace(/^\n/, '');
+        return `${before}${block}${after}`;
+    }
+    const base = configToml === '' || configToml.endsWith('\n') ? configToml : `${configToml}\n`;
+    return `${base}${base === '' ? '' : '\n'}${block}`;
+}
+/**
+ * Pick, from a `hooks/list` response, the metadata of the entries WE wrote — matched on the exact
+ * command string, so a third party's entry can never inherit dz's trust write.
+ */
+export function selectOwnHookMetadata(hooks, entries) {
+    const byCommand = new Map(entries.map((e) => [e.command, e.id]));
+    const out = [];
+    for (const meta of hooks) {
+        const id = typeof meta.command === 'string' ? byCommand.get(meta.command) : undefined;
+        if (id !== undefined)
+            out.push({ id, meta });
+    }
+    return out;
+}
+//# sourceMappingURL=codex-hooks.js.map