aiden-runtime 4.8.1 → 4.9.0

package/dist/core/v4/hooks/dispatcher.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/hooks/dispatcher.ts — v4.9.0 Slice 12a.
+ *
+ * Given an event + payload + execution context, queries the DB for
+ * active subscriptions, runs each through the subprocess runner,
+ * aggregates decisions per the authority/mode model, and writes a
+ * `hook_executions` audit row for every firing.
+ *
+ * Aggregation rules:
+ *   - If ANY `mandatory_policy` subscription's net outcome is `block`
+ *     (including via on_error/on_timeout policy promotion), the
+ *     overall dispatch returns `decision: 'block'`. Earliest blocker
+ *     wins.
+ *   - `transform_input` / `transform_output` patches apply in
+ *     priority order (highest first); subsequent hooks see the
+ *     patched payload.
+ *   - Best-effort observers + advisory_policy hooks never block the
+ *     overall flow — their outcomes only land in the audit table.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHookSubprocess = exports.CONSECUTIVE_FAILURE_THRESHOLD = void 0;
+exports.setAutoDisableLogger = setAutoDisableLogger;
+exports.dispatchHook = dispatchHook;
+const node_path_1 = __importDefault(require("node:path"));
+const identity_1 = require("../identity");
+const subprocessRunner_1 = require("./runtime/subprocessRunner");
+Object.defineProperty(exports, "runHookSubprocess", { enumerable: true, get: function () { return subprocessRunner_1.runHookSubprocess; } });
+const trust_1 = require("./trust");
+/**
+ * v4.9.0 Slice 12b — auto-disable threshold. After this many
+ * consecutive non-`ok` outcomes the dispatcher auto-revokes the
+ * hook regardless of `on_error` / `on_timeout` policy. Defense in
+ * depth: a poorly-configured `on_error: 'allow'` won't mask a
+ * permanently broken hook.
+ */
+exports.CONSECUTIVE_FAILURE_THRESHOLD = 3;
+let _autoDisableLogger = null;
+function setAutoDisableLogger(fn) { _autoDisableLogger = fn; }
+/**
+ * Look up the most recent N `hook_executions` rows for a hook so the
+ * `hook.auto_disabled` log line can cross-reference the failures.
+ */
+function recentExecutionIds(db, hookId, n) {
+    const rows = db.prepare(`SELECT hook_execution_id FROM hook_executions WHERE hook_id = ?
+       ORDER BY started_at DESC LIMIT ?`).all(hookId, n);
+    return rows.map((r) => r.hook_execution_id);
+}
+/**
+ * Apply auto-disable policy after a single subscription firing.
+ * Branches:
+ *   - status='ok'                          → reset consecutive_failures = 0
+ *   - status in {timeout,crash,malformed}  → increment counter
+ *     * if `on_error|on_timeout == 'disable_hook'` → immediate revoke
+ *     * else if counter >= threshold       → 3-strike revoke
+ *
+ * `testMode=true` (used by `aiden hooks test`) skips ALL counter
+ * mutation and policy application — pure dry-run.
+ */
+function applyAutoDisablePolicy(db, hookId, subId, status, policy, testMode) {
+    if (testMode)
+        return;
+    if (status === 'ok') {
+        db.prepare(`UPDATE hooks SET consecutive_failures=0, updated_at=? WHERE hook_id=?`)
+            .run(new Date().toISOString(), hookId);
+        return;
+    }
+    // Increment counter for any non-ok outcome.
+    db.prepare(`UPDATE hooks SET consecutive_failures = consecutive_failures + 1,
+                              updated_at=? WHERE hook_id=?`)
+        .run(new Date().toISOString(), hookId);
+    // Immediate revoke when the subscription explicitly opts in.
+    if (policy === 'disable_hook') {
+        (0, trust_1.markRevoked)(db, hookId);
+        _autoDisableLogger?.({
+            hookId, subscriptionId: subId,
+            reason: `auto_disable:${status}`,
+            hookExecutionIds: recentExecutionIds(db, hookId, 3),
+        });
+        return;
+    }
+    // 3-strike defense in depth.
+    const row = db.prepare(`SELECT consecutive_failures AS n FROM hooks WHERE hook_id=?`)
+        .get(hookId);
+    if (row && row.n >= exports.CONSECUTIVE_FAILURE_THRESHOLD) {
+        (0, trust_1.markRevoked)(db, hookId);
+        _autoDisableLogger?.({
+            hookId, subscriptionId: subId,
+            reason: `auto_disable:three_strikes:${status}`,
+            hookExecutionIds: recentExecutionIds(db, hookId, 3),
+        });
+    }
+}
+/**
+ * Match a subscription against the dispatch context. Currently
+ * supports tool-name matching for `tool.call.*` events; other matcher
+ * shapes (paths, etc.) extend by adding branches here.
+ */
+function matches(sub, ctx) {
+    if (!sub.matcher_json)
+        return true;
+    try {
+        const m = JSON.parse(sub.matcher_json);
+        if (m.tools && m.tools.length > 0) {
+            if (!ctx.toolName || !m.tools.includes(ctx.toolName))
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return true;
+    } // malformed matcher → permissive
+}
+/**
+ * Read the hook's entrypoint argv from its manifest. We re-parse on
+ * each dispatch (sub-ms; the file is tiny) so a manifest edit doesn't
+ * require a daemon restart — only the entrypoint code change does,
+ * and that trips drift detection on the next scan.
+ */
+async function readEntrypoint(manifestPath) {
+    try {
+        const { parseHookManifest } = await Promise.resolve().then(() => __importStar(require('./manifest')));
+        const m = await parseHookManifest(manifestPath);
+        return { argv: m.entrypoint.argv, cwd: m.manifestDir };
+    }
+    catch {
+        return null;
+    }
+}
+function writeAudit(db, row) {
+    db.prepare(`INSERT INTO hook_executions
+       (hook_execution_id, hook_id, subscription_id, event,
+        run_id, trace_id, span_id, parent_span_id, tool_call_id,
+        status, decision, elapsed_ms, exit_code,
+        payload_hash, response_hash, stdout_preview, stderr_preview,
+        error_kind, error_message, started_at, finished_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.hookExecId, row.hookId, row.subscriptionId, row.event, row.ctx.runId ?? null, row.ctx.traceId ?? null, row.ctx.spanId ?? null, row.ctx.parentSpanId ?? null, row.ctx.toolCallId ?? null, row.status, row.decision, row.outcome?.elapsedMs ?? 0, row.outcome?.exitCode ?? null, row.outcome?.payloadHash ?? null, row.outcome?.responseHash ?? null, row.outcome?.stdoutPreview ?? null, row.outcome?.stderrPreview ?? null, row.outcome?.errorKind ?? null, row.outcome?.errorMessage ?? null, row.startedAt, row.finishedAt);
+}
+/**
+ * Dispatch all subscriptions matching `event` + `ctx`. Always
+ * resolves (never throws); decision aggregation is fail-closed for
+ * `mandatory_policy` and fail-open for everything else.
+ */
+async function dispatchHook(db, event, payload, ctx) {
+    const subs = db.prepare(`SELECT s.*, h.manifest_path, h.trust_state, h.enabled AS hook_enabled, h.name AS name
+       FROM hook_subscriptions s
+       JOIN hooks h ON h.hook_id = s.hook_id
+      WHERE s.event = ? AND s.enabled = 1
+        AND h.enabled = 1 AND h.trust_state = 'trusted'
+      ORDER BY s.priority DESC, s.subscription_id ASC`).all(event);
+    const fired = [];
+    let workingPayload = { ...payload };
+    let blockReason;
+    let userMessage;
+    let modelMessage;
+    let blocked = false;
+    for (const sub of subs) {
+        if (!matches(sub, ctx))
+            continue;
+        const ep = await readEntrypoint(sub.manifest_path);
+        const startedAt = new Date().toISOString();
+        const hookExecId = (0, identity_1.newHookExecId)();
+        let outcome = null;
+        let policyDecision = 'allow';
+        if (!ep) {
+            // Couldn't read manifest → treat as crash, apply on_error.
+            outcome = {
+                status: 'crash', exitCode: null, elapsedMs: 0, payloadHash: '',
+                stdoutPreview: '', stderrPreview: '',
+                errorKind: 'ManifestReadFailed',
+                errorMessage: `could not re-read manifest at ${sub.manifest_path}`,
+            };
+        }
+        else {
+            outcome = await (0, subprocessRunner_1.runHookSubprocess)({
+                argv: ep.argv,
+                cwd: ep.cwd,
+                payload: { event, hook_id: sub.hook_id, subscription_id: sub.subscription_id,
+                    run_id: ctx.runId, trace_id: ctx.traceId, parent_span_id: ctx.parentSpanId,
+                    payload: workingPayload },
+                timeoutMs: sub.timeout_ms,
+                hookId: sub.hook_id,
+                event,
+                runId: ctx.runId,
+                traceId: ctx.traceId,
+                parentSpanId: ctx.parentSpanId,
+            });
+        }
+        // Map outcome → policy decision.
+        if (outcome.status === 'ok') {
+            const d = outcome.response?.decision ?? 'none';
+            if (d === 'block' && sub.authority === 'decision') {
+                policyDecision = 'block';
+            }
+            else {
+                policyDecision = 'allow';
+            }
+            // Apply transform_* patches (priority order is loop order).
+            if (outcome.response?.patch && (sub.authority === 'transform_input' || sub.authority === 'transform_output')) {
+                workingPayload = { ...workingPayload, ...outcome.response.patch };
+            }
+        }
+        else {
+            // Non-ok statuses route via on_error / on_timeout.
+            const policy = outcome.status === 'timeout' ? sub.on_timeout : sub.on_error;
+            if (policy === 'block' && sub.mode === 'mandatory_policy') {
+                policyDecision = 'block';
+            }
+            // For 'disable_hook' policy in 12a: we don't auto-disable here;
+            // we just treat as allow (12b's CLI surfaces the failure).
+        }
+        const finishedAt = new Date().toISOString();
+        writeAudit(db, {
+            hookExecId, hookId: sub.hook_id, subscriptionId: sub.subscription_id,
+            event, ctx, status: outcome.status, decision: outcome.response?.decision ?? policyDecision,
+            outcome, startedAt, finishedAt,
+        });
+        // v4.9.0 Slice 12b — auto-disable policy. `disable_hook` triggers
+        // immediate revoke; 3 consecutive failures triggers revoke
+        // regardless of policy (defense in depth).
+        const policy = outcome.status === 'timeout' ? sub.on_timeout : sub.on_error;
+        applyAutoDisablePolicy(db, sub.hook_id, sub.subscription_id, outcome.status, policy, ctx.testMode === true);
+        fired.push({
+            hookId: sub.hook_id, subscriptionId: sub.subscription_id,
+            status: outcome.status, decision: outcome.response?.decision ?? policyDecision,
+            elapsedMs: outcome.elapsedMs,
+        });
+        if (policyDecision === 'block' && !blocked) {
+            blocked = true;
+            blockReason = outcome.response?.reason ?? (outcome.errorMessage ?? 'blocked by hook');
+            userMessage = outcome.response?.user_message;
+            modelMessage = outcome.response?.model_message;
+            // For mandatory_policy block, we still run later hooks so they
+            // can record audit rows — but mark `decision='block'`.
+        }
+    }
+    return {
+        decision: blocked ? 'block' : 'allow',
+        reason: blockReason, user_message: userMessage, model_message: modelMessage,
+        payload: workingPayload, fired,
+    };
+}
+// Silences unused-import lint when no path matcher fires.
+void node_path_1.default;

package/dist/core/v4/hooks/index.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/hooks/index.ts — v4.9.0 Slice 12a barrel.
+ *
+ * Public surface for the hook subsystem. Other v4 modules should
+ * import from here, not from the individual files, so the internal
+ * layout stays free to evolve.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HookBlockedError = exports.runToolWithHooks = exports.countByStatus = exports.failureRates = exports.queryHookExecutions = exports.fireApprovalResponded = exports.fireApprovalRequested = exports.fireSessionEnd = exports.fireSessionStart = exports.CONSECUTIVE_FAILURE_THRESHOLD = exports.setAutoDisableLogger = exports.runHookSubprocess = exports.dispatchHook = exports.markUntrusted = exports.markRevoked = exports.markTrusted = exports.listHooks = exports.scanAndLoadHooks = exports.ON_ERROR_POLICIES = exports.MODES = exports.AUTHORITIES = exports.HOOK_EVENTS = exports.parseHookManifest = void 0;
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "parseHookManifest", { enumerable: true, get: function () { return manifest_1.parseHookManifest; } });
+Object.defineProperty(exports, "HOOK_EVENTS", { enumerable: true, get: function () { return manifest_1.HOOK_EVENTS; } });
+Object.defineProperty(exports, "AUTHORITIES", { enumerable: true, get: function () { return manifest_1.AUTHORITIES; } });
+Object.defineProperty(exports, "MODES", { enumerable: true, get: function () { return manifest_1.MODES; } });
+Object.defineProperty(exports, "ON_ERROR_POLICIES", { enumerable: true, get: function () { return manifest_1.ON_ERROR_POLICIES; } });
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "scanAndLoadHooks", { enumerable: true, get: function () { return registry_1.scanAndLoadHooks; } });
+Object.defineProperty(exports, "listHooks", { enumerable: true, get: function () { return registry_1.listHooks; } });
+var trust_1 = require("./trust");
+Object.defineProperty(exports, "markTrusted", { enumerable: true, get: function () { return trust_1.markTrusted; } });
+Object.defineProperty(exports, "markRevoked", { enumerable: true, get: function () { return trust_1.markRevoked; } });
+Object.defineProperty(exports, "markUntrusted", { enumerable: true, get: function () { return trust_1.markUntrusted; } });
+var dispatcher_1 = require("./dispatcher");
+Object.defineProperty(exports, "dispatchHook", { enumerable: true, get: function () { return dispatcher_1.dispatchHook; } });
+Object.defineProperty(exports, "runHookSubprocess", { enumerable: true, get: function () { return dispatcher_1.runHookSubprocess; } });
+Object.defineProperty(exports, "setAutoDisableLogger", { enumerable: true, get: function () { return dispatcher_1.setAutoDisableLogger; } });
+Object.defineProperty(exports, "CONSECUTIVE_FAILURE_THRESHOLD", { enumerable: true, get: function () { return dispatcher_1.CONSECUTIVE_FAILURE_THRESHOLD; } });
+var lifecycle_1 = require("./lifecycle");
+Object.defineProperty(exports, "fireSessionStart", { enumerable: true, get: function () { return lifecycle_1.fireSessionStart; } });
+Object.defineProperty(exports, "fireSessionEnd", { enumerable: true, get: function () { return lifecycle_1.fireSessionEnd; } });
+Object.defineProperty(exports, "fireApprovalRequested", { enumerable: true, get: function () { return lifecycle_1.fireApprovalRequested; } });
+Object.defineProperty(exports, "fireApprovalResponded", { enumerable: true, get: function () { return lifecycle_1.fireApprovalResponded; } });
+var auditQuery_1 = require("./auditQuery");
+Object.defineProperty(exports, "queryHookExecutions", { enumerable: true, get: function () { return auditQuery_1.queryHookExecutions; } });
+Object.defineProperty(exports, "failureRates", { enumerable: true, get: function () { return auditQuery_1.failureRates; } });
+Object.defineProperty(exports, "countByStatus", { enumerable: true, get: function () { return auditQuery_1.countByStatus; } });
+var toolHookGate_1 = require("./toolHookGate");
+Object.defineProperty(exports, "runToolWithHooks", { enumerable: true, get: function () { return toolHookGate_1.runToolWithHooks; } });
+Object.defineProperty(exports, "HookBlockedError", { enumerable: true, get: function () { return toolHookGate_1.HookBlockedError; } });

package/dist/core/v4/hooks/lifecycle.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fireSessionStart = fireSessionStart;
+exports.fireSessionEnd = fireSessionEnd;
+exports.fireApprovalRequested = fireApprovalRequested;
+exports.fireApprovalResponded = fireApprovalResponded;
+const dispatcher_1 = require("./dispatcher");
+async function safeFire(db, event, payload, ctx) {
+    if (!db)
+        return;
+    try {
+        await (0, dispatcher_1.dispatchHook)(db, event, payload, ctx);
+    }
+    catch { /* fail-open — lifecycle hooks never throw out */ }
+}
+async function fireSessionStart(db, payload, ctx = {}) {
+    return safeFire(db, 'session.start', payload, ctx);
+}
+async function fireSessionEnd(db, payload, ctx = {}) {
+    return safeFire(db, 'session.end', payload, ctx);
+}
+async function fireApprovalRequested(db, payload, ctx = {}) {
+    return safeFire(db, 'approval.requested', payload, ctx);
+}
+async function fireApprovalResponded(db, payload, ctx = {}) {
+    return safeFire(db, 'approval.responded', payload, ctx);
+}

package/dist/core/v4/hooks/manifest.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/hooks/manifest.ts — v4.9.0 Slice 12a.
+ *
+ * Parse + validate HOOK.yaml manifests. Strict schema validation —
+ * malformed files are rejected with a precise error rather than
+ * silently ignored. Returns a typed `HookManifest` that downstream
+ * registry + runner code can rely on.
+ *
+ * Why strict: a manifest is privileged input (declares timeouts,
+ * authority, error policy). Soft-failing on bad fields lets a bad
+ * file silently bypass the policy the user intended.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ON_ERROR_POLICIES = exports.MODES = exports.AUTHORITIES = exports.HOOK_EVENTS = void 0;
+exports.parseHookManifest = parseHookManifest;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+exports.HOOK_EVENTS = [
+    'tool.call.pre',
+    'tool.call.post',
+    'session.start',
+    'session.end',
+    'approval.requested',
+    'approval.responded',
+];
+exports.AUTHORITIES = [
+    'observe', 'decision', 'transform_input', 'transform_output',
+];
+exports.MODES = [
+    'best_effort_observer', 'advisory_policy', 'mandatory_policy',
+];
+exports.ON_ERROR_POLICIES = ['allow', 'block', 'disable_hook'];
+const ID_RE = /^[a-z0-9][a-z0-9_-]{1,63}$/;
+function fail(p, msg) {
+    throw new Error(`HOOK.yaml at ${p}: ${msg}`);
+}
+/** Parse a HOOK.yaml file and return a validated manifest. */
+async function parseHookManifest(manifestPath) {
+    const raw = await node_fs_1.promises.readFile(manifestPath, 'utf8');
+    let doc;
+    try {
+        doc = js_yaml_1.default.load(raw);
+    }
+    catch (e) {
+        fail(manifestPath, `invalid YAML: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+        fail(manifestPath, 'root must be a YAML mapping');
+    }
+    const m = doc;
+    // Required scalars.
+    const id = m.id;
+    if (typeof id !== 'string' || !ID_RE.test(id)) {
+        fail(manifestPath, '`id` must be 2-64 chars of [a-z0-9_-] starting with [a-z0-9]');
+    }
+    const name = m.name;
+    if (typeof name !== 'string' || name.length === 0)
+        fail(manifestPath, '`name` must be a non-empty string');
+    const runtime = m.runtime;
+    if (runtime !== 'subprocess')
+        fail(manifestPath, '`runtime` must be `subprocess` (v4.9.0 supports only subprocess)');
+    // entrypoint.argv
+    const ep = m.entrypoint;
+    if (!ep || typeof ep !== 'object' || !Array.isArray(ep.argv) || ep.argv.length === 0 ||
+        !ep.argv.every((a) => typeof a === 'string' && a.length > 0)) {
+        fail(manifestPath, '`entrypoint.argv` must be a non-empty array of non-empty strings');
+    }
+    // subscriptions[]
+    const subsRaw = m.subscriptions;
+    if (!Array.isArray(subsRaw) || subsRaw.length === 0)
+        fail(manifestPath, '`subscriptions` must be a non-empty array');
+    const subs = subsRaw.map((s, i) => {
+        if (!s || typeof s !== 'object' || Array.isArray(s))
+            fail(manifestPath, `subscriptions[${i}] must be a mapping`);
+        const sub = s;
+        if (!exports.HOOK_EVENTS.includes(sub.event)) {
+            fail(manifestPath, `subscriptions[${i}].event must be one of: ${exports.HOOK_EVENTS.join(', ')}`);
+        }
+        if (!exports.AUTHORITIES.includes(sub.authority)) {
+            fail(manifestPath, `subscriptions[${i}].authority must be one of: ${exports.AUTHORITIES.join(', ')}`);
+        }
+        if (!exports.MODES.includes(sub.mode)) {
+            fail(manifestPath, `subscriptions[${i}].mode must be one of: ${exports.MODES.join(', ')}`);
+        }
+        const tms = sub.timeout_ms;
+        if (typeof tms !== 'number' || !Number.isFinite(tms) || tms <= 0 || tms > 30000) {
+            fail(manifestPath, `subscriptions[${i}].timeout_ms must be a positive number <= 30000`);
+        }
+        if (!exports.ON_ERROR_POLICIES.includes(sub.on_error)) {
+            fail(manifestPath, `subscriptions[${i}].on_error must be one of: ${exports.ON_ERROR_POLICIES.join(', ')}`);
+        }
+        if (!exports.ON_ERROR_POLICIES.includes(sub.on_timeout)) {
+            fail(manifestPath, `subscriptions[${i}].on_timeout must be one of: ${exports.ON_ERROR_POLICIES.join(', ')}`);
+        }
+        const out = {
+            event: sub.event,
+            authority: sub.authority,
+            mode: sub.mode,
+            timeout_ms: tms,
+            on_error: sub.on_error,
+            on_timeout: sub.on_timeout,
+        };
+        if (typeof sub.priority === 'number' && Number.isFinite(sub.priority))
+            out.priority = sub.priority;
+        if (sub.matcher && typeof sub.matcher === 'object' && !Array.isArray(sub.matcher)) {
+            const mm = sub.matcher;
+            const matcher = {};
+            if (Array.isArray(mm.tools) && mm.tools.every((t) => typeof t === 'string'))
+                matcher.tools = mm.tools;
+            if (Array.isArray(mm.paths) && mm.paths.every((p2) => typeof p2 === 'string'))
+                matcher.paths = mm.paths;
+            out.matcher = matcher;
+        }
+        return out;
+    });
+    // capabilities (optional, warn-only in 12a — just shape-check).
+    let caps;
+    if (m.capabilities && typeof m.capabilities === 'object' && !Array.isArray(m.capabilities)) {
+        caps = m.capabilities;
+    }
+    return {
+        id, name,
+        version: typeof m.version === 'string' ? m.version : undefined,
+        runtime: 'subprocess',
+        entrypoint: { argv: ep.argv.slice() },
+        subscriptions: subs,
+        capabilities: caps,
+        manifestDir: node_path_1.default.dirname(manifestPath),
+        manifestPath,
+    };
+}

package/dist/core/v4/hooks/registry.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/hooks/registry.ts — v4.9.0 Slice 12a.
+ *
+ * Scans `~/.aiden/hooks/<name>/HOOK.yaml` (global) and
+ * `<projectRoot>/.aiden/hooks/<name>/HOOK.yaml` (project-scoped),
+ * parses each manifest, computes the entrypoint SHA256, and
+ * UPSERTs into the `hooks` + `hook_subscriptions` +
+ * `hook_capability_grants` tables.
+ *
+ * Drift detection: if a row already exists for the same
+ * `manifest_path` and the new `code_hash` differs from the
+ * stored one, the row is marked `trust_state='drifted'` and
+ * `enabled=0`. (Slice 12b's CLI surfaces these for explicit
+ * re-trust.) New entries land with `enabled=0` and
+ * `trust_state='untrusted'` — explicit user action to trust.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanAndLoadHooks = scanAndLoadHooks;
+exports.listHooks = listHooks;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = __importDefault(require("node:path"));
+const identity_1 = require("../identity");
+const manifest_1 = require("./manifest");
+async function sha256File(p) {
+    try {
+        const raw = await node_fs_1.promises.readFile(p);
+        return (0, node_crypto_1.createHash)('sha256').update(raw).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+async function safeReaddir(dir) {
+    try {
+        return await node_fs_1.promises.readdir(dir);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+}
+/**
+ * Scan global + (optional) project hook directories. Returns a counts
+ * summary. Per-manifest errors are accumulated, NOT thrown — a bad
+ * hook never blocks loading the rest.
+ */
+async function scanAndLoadHooks(db, opts) {
+    const log = opts.log ?? (() => { });
+    const result = { loaded: 0, errored: 0, drifted: 0, errors: [] };
+    const sources = [
+        { dir: node_path_1.default.join(opts.aidenRoot, 'hooks'), source: 'global' },
+    ];
+    if (opts.projectRoot) {
+        sources.push({ dir: node_path_1.default.join(opts.projectRoot, '.aiden', 'hooks'), source: 'project' });
+    }
+    for (const src of sources) {
+        const entries = await safeReaddir(src.dir);
+        for (const entry of entries) {
+            const candidate = node_path_1.default.join(src.dir, entry, 'HOOK.yaml');
+            try {
+                await node_fs_1.promises.access(candidate);
+            }
+            catch {
+                continue; /* not a hook directory */
+            }
+            try {
+                const manifest = await (0, manifest_1.parseHookManifest)(candidate);
+                const entrypointAbs = node_path_1.default.resolve(manifest.manifestDir, manifest.entrypoint.argv[manifest.entrypoint.argv.length - 1]);
+                const codeHash = (await sha256File(entrypointAbs))
+                    ?? (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(manifest.entrypoint.argv)).digest('hex');
+                const drifted = upsertHook(db, manifest, codeHash, src.source);
+                if (drifted)
+                    result.drifted += 1;
+                result.loaded += 1;
+                log('info', `[hooks] loaded ${manifest.id} (${src.source})${drifted ? ' — DRIFTED, disabled' : ''}`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                result.errored += 1;
+                result.errors.push({ path: candidate, message: msg });
+                log('warn', `[hooks] failed to load ${candidate}: ${msg}`);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * UPSERT the hooks row + its subscriptions + capability grants.
+ * Returns true when an existing row was found with a different
+ * `code_hash` (drift case).
+ */
+function upsertHook(db, m, codeHash, source) {
+    const now = new Date().toISOString();
+    // Look up existing row by manifest_path.
+    const existing = db.prepare(`SELECT * FROM hooks WHERE manifest_path = ?`).get(m.manifestPath);
+    let drifted = false;
+    let hookId;
+    if (existing) {
+        hookId = existing.hook_id;
+        if (existing.code_hash !== codeHash) {
+            drifted = true;
+            db.prepare(`UPDATE hooks SET name=?, version=?, source=?, runtime=?, code_hash=?,
+                          trust_state='drifted', enabled=0, updated_at=?
+          WHERE hook_id = ?`).run(m.name, m.version ?? null, source, m.runtime, codeHash, now, hookId);
+        }
+        else {
+            db.prepare(`UPDATE hooks SET name=?, version=?, source=?, runtime=?, updated_at=? WHERE hook_id = ?`).run(m.name, m.version ?? null, source, m.runtime, now, hookId);
+        }
+    }
+    else {
+        hookId = (0, identity_1.newHookId)();
+        db.prepare(`INSERT INTO hooks
+         (hook_id, name, version, source, runtime, manifest_path, code_hash, enabled, trust_state, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 0, 'untrusted', ?, ?)`).run(hookId, m.name, m.version ?? null, source, m.runtime, m.manifestPath, codeHash, now, now);
+    }
+    // Replace subscriptions wholesale — simpler than diffing.
+    db.prepare(`DELETE FROM hook_subscriptions WHERE hook_id = ?`).run(hookId);
+    for (const s of m.subscriptions) {
+        db.prepare(`INSERT INTO hook_subscriptions
+         (subscription_id, hook_id, event, matcher_json, authority, mode, priority, timeout_ms, on_error, on_timeout, enabled)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)`).run((0, identity_1.newHookSubId)(), hookId, s.event, s.matcher ? JSON.stringify(s.matcher) : null, s.authority, s.mode, s.priority ?? 0, s.timeout_ms, s.on_error, s.on_timeout);
+    }
+    // Capability grants are warn-only — store but don't enforce.
+    db.prepare(`DELETE FROM hook_capability_grants WHERE hook_id = ?`).run(hookId);
+    if (m.capabilities) {
+        for (const [cap, scope] of Object.entries(m.capabilities)) {
+            db.prepare(`INSERT INTO hook_capability_grants
+           (grant_id, hook_id, capability, scope_json, granted_by, granted_at)
+         VALUES (?, ?, ?, ?, ?, ?)`).run((0, identity_1.newHookId)(), hookId, cap, JSON.stringify(scope), null, now);
+        }
+    }
+    return drifted;
+}
+/** Read all rows for diagnostic / dispatcher use. */
+function listHooks(db) {
+    return db.prepare(`SELECT * FROM hooks ORDER BY name`).all();
+}