@kylecheng3146/agent-ops 0.1.2 → 0.1.3

package/dist/packages/cli/src/context.js

@@ -0,0 +1,102 @@
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadConfigFile } from "../../../runtime/src/config/load.js";
+import { mergeConfigLayers } from "../../../runtime/src/config/merge.js";
+import { sha256 } from "../../../runtime/src/fs/hash.js";
+import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
+import { localStatePaths } from "../../../runtime/src/security/permissions.js";
+import { calculateTrustBinding, FileTrustStore } from "../../../runtime/src/security/trust.js";
+export const DEFAULT_CONFIG = {
+    schemaVersion: 1,
+    profiles: [],
+    verification: { commands: [] },
+    pathMappings: [],
+    securityExceptions: []
+};
+function defaultConfigLayer() {
+    return {
+        source: "default",
+        sourcePath: "built-in defaults",
+        config: DEFAULT_CONFIG
+    };
+}
+async function loadOptionalConfig(path) {
+    try {
+        return await loadConfigFile(path);
+    }
+    catch (error) {
+        if (error instanceof AgentOpsError &&
+            error.code === "CONFIG_READ_FAILED" &&
+            typeof error.cause === "object" &&
+            error.cause !== null &&
+            "code" in error.cause &&
+            error.cause.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function loadEffectiveConfig(root, scope) {
+    const home = process.env.AGENT_OPS_HOME ?? homedir();
+    const userPath = join(home, ".agent-ops", "config.json");
+    const projectPath = join(root, ".agent-ops", "config.json");
+    const layers = [defaultConfigLayer()];
+    if (scope === "user") {
+        const user = await loadOptionalConfig(userPath);
+        if (user !== null) {
+            layers.push({
+                source: "user",
+                sourcePath: user.sourcePath,
+                config: user.config
+            });
+        }
+        return mergeConfigLayers(layers);
+    }
+    if (projectPath !== userPath) {
+        const user = await loadOptionalConfig(userPath);
+        if (user !== null) {
+            layers.push({
+                source: "user",
+                sourcePath: user.sourcePath,
+                config: user.config
+            });
+        }
+    }
+    const project = await loadOptionalConfig(projectPath);
+    if (project !== null) {
+        layers.push({
+            source: "project",
+            sourcePath: project.sourcePath,
+            config: project.config
+        });
+    }
+    return mergeConfigLayers(layers);
+}
+export function repositoryRemoteUrl(root) {
+    try {
+        return execFileSync("git", ["config", "--get", "remote.origin.url"], {
+            cwd: root,
+            encoding: "utf8"
+        }).trim();
+    }
+    catch {
+        return `local:${root}`;
+    }
+}
+export async function repositoryTrust(root, config, cliVersion) {
+    const home = process.env.AGENT_OPS_HOME ?? homedir();
+    const state = localStatePaths(home);
+    try {
+        const binding = await calculateTrustBinding({
+            repositoryPath: root,
+            remoteUrl: repositoryRemoteUrl(root),
+            configHash: sha256(JSON.stringify(config)),
+            runtimeHash: sha256(cliVersion)
+        });
+        return (await new FileTrustStore(state.trustStore, state.anchorDirectory).status(binding)).status;
+    }
+    catch {
+        return "UNTRUSTED";
+    }
+}

package/dist/packages/cli/src/hook-entry.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Entry point registered in Claude settings as:
+//   node <this file> <harness> <event> --managed-by=agent-ops
+import { CLI_VERSION } from "./version.js";
+import { runHookProcess } from "./hook-process.js";
+process.exitCode = await runHookProcess(process.argv.slice(2), {
+    stdin: process.stdin,
+    writeStdout: (value) => process.stdout.write(value),
+    writeStderr: (value) => process.stderr.write(value)
+}, CLI_VERSION);

package/dist/packages/cli/src/hook-process.js

@@ -0,0 +1,54 @@
+import { runHookCommand, HOOK_EVENTS } from "./commands/hook.js";
+import { loadEffectiveConfig, repositoryTrust } from "./context.js";
+const HARNESSES = new Set(["codex", "claude"]);
+const MAX_HOOK_INPUT_BYTES = 1024 * 1024;
+async function readStdin(stream) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk)
+            ? chunk
+            : Buffer.from(String(chunk), "utf8");
+        total += buffer.byteLength;
+        if (total > MAX_HOOK_INPUT_BYTES) {
+            return "";
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, total).toString("utf8");
+}
+/**
+ * Runs one hook invocation. Always resolves to exit code 0: a hook that
+ * cannot answer must never block the harness it advises.
+ */
+export async function runHookProcess(argv, io, cliVersion) {
+    const [harness, event] = argv;
+    if (harness === undefined ||
+        !HARNESSES.has(harness) ||
+        event === undefined ||
+        !HOOK_EVENTS.includes(event)) {
+        io.writeStderr("Usage: agent-ops hook <codex|claude> <SessionStart|PreToolUse|Stop>\n");
+        return 0;
+    }
+    try {
+        const root = process.cwd();
+        const config = (await loadEffectiveConfig(root, "project")).config;
+        const output = await runHookCommand({
+            harness: harness,
+            event: event,
+            stdin: await readStdin(io.stdin),
+            config,
+            trusted: (await repositoryTrust(root, config, cliVersion)) === "TRUSTED"
+        });
+        if (output.stdout.length > 0) {
+            io.writeStdout(output.stdout);
+        }
+        if (output.stderr.length > 0) {
+            io.writeStderr(output.stderr);
+        }
+    }
+    catch {
+        // ponytail: fail-open by design; hook failures stay invisible to the harness.
+    }
+    return 0;
+}

package/dist/packages/cli/src/ui.js

@@ -0,0 +1,132 @@
+// figlet "agent-ops" -f Standard, trimmed of trailing blank lines/columns.
+const BANNER = [
+    "                         _",
+    "   __ _  __ _  ___ _ __ | |_       ___  _ __  ___ ",
+    "  / _\` |/ _\` |/ _ \\ '_ \\| __|____ / _ \\| '_ \\/ __|",
+    " | (_| | (_| |  __/ | | | ||_____| (_) | |_) \\__ \\",
+    "  \\__,_|\\__, |\\___|_| |_|\\__|     \\___/| .__/|___/",
+    "        |___/                          |_|"
+].join("\n");
+const TAGLINE = "loop engineering toolkit";
+const MIN_BANNER_COLUMNS = 54;
+const RAIL = "\u2502";
+const DIAMOND = "\u25c6";
+const DOT_ON = "\u25cf";
+const DOT_OFF = "\u25cb";
+function envColorPreference() {
+    if (process.env.NO_COLOR !== undefined) {
+        return "off";
+    }
+    if (process.env.FORCE_COLOR !== undefined) {
+        return "on";
+    }
+    return undefined;
+}
+function useColor(output) {
+    const preference = envColorPreference();
+    return preference === undefined ? output.isTTY : preference === "on";
+}
+function paint(output, code, text) {
+    return useColor(output) ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+const dim = (output, text) => paint(output, "2", text);
+const bold = (output, text) => paint(output, "1", text);
+const green = (output, text) => paint(output, "32", text);
+const cyan = (output, text) => paint(output, "36", text);
+/**
+ * Decorative only: skipped for --json output, non-interactive runs, and
+ * terminals too narrow to render the wordmark without wrapping.
+ */
+export function writeBanner(output) {
+    if (!output.isTTY || (output.columns ?? 0) < MIN_BANNER_COLUMNS) {
+        return;
+    }
+    output.write(`${cyan(output, BANNER)}\n${dim(output, TAGLINE)}\n\n`);
+}
+function eraseLines(write, count) {
+    for (let index = 0; index < count; index += 1) {
+        write("\u001b[1A\u001b[2K");
+    }
+}
+function renderChoice(outputLike, question, value) {
+    const yes = value
+        ? bold(outputLike, green(outputLike, `${DOT_ON} Yes`))
+        : dim(outputLike, `${DOT_OFF} Yes`);
+    const no = !value
+        ? bold(outputLike, green(outputLike, `${DOT_ON} No`))
+        : dim(outputLike, `${DOT_OFF} No`);
+    return [
+        `${bold(outputLike, DIAMOND)}  ${question}`,
+        `${dim(outputLike, RAIL)}  ${yes} / ${no}`
+    ].join("\n");
+}
+async function typedFallback(question, io, defaultValue) {
+    const { createInterface } = await import("node:readline/promises");
+    const readline = createInterface({ input: io.input, output: io.output });
+    try {
+        const suffix = defaultValue ? "Y/n" : "y/N";
+        const answer = (await readline.question(`${question} [${suffix}]: `)).trim().toLowerCase();
+        if (answer === "") {
+            return defaultValue;
+        }
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        readline.close();
+    }
+}
+/**
+ * Arrow-key Yes/No selector. Falls back to a typed y/N prompt when stdin
+ * cannot enter raw mode (piped input, or a stub stream in tests), so the
+ * same call works under both a real terminal and test harnesses.
+ */
+export async function selectYesNo(question, io, defaultValue = false) {
+    if (typeof io.input.setRawMode !== "function" ||
+        io.input.isTTY !== true) {
+        return await typedFallback(question, io, defaultValue);
+    }
+    const outputLike = {
+        isTTY: true,
+        columns: io.output.columns,
+        write: (value) => io.output.write(value)
+    };
+    const { emitKeypressEvents } = await import("node:readline");
+    emitKeypressEvents(io.input);
+    io.input.setRawMode(true);
+    io.input.resume();
+    let value = defaultValue;
+    let rendered = renderChoice(outputLike, question, value);
+    io.output.write(`${rendered}\n`);
+    return await new Promise((resolve) => {
+        const cleanup = () => {
+            io.input.setRawMode?.(false);
+            io.input.pause();
+            io.input.removeListener("keypress", onKeypress);
+        };
+        const redraw = () => {
+            eraseLines((value_) => io.output.write(value_), rendered.split("\n").length);
+            rendered = renderChoice(outputLike, question, value);
+            io.output.write(`${rendered}\n`);
+        };
+        const onKeypress = (_chunk, key) => {
+            if (key?.ctrl === true && key.name === "c") {
+                cleanup();
+                process.exit(130);
+            }
+            if (key?.name === "left" ||
+                key?.name === "right" ||
+                key?.name === "tab" ||
+                key?.name === "h" ||
+                key?.name === "l") {
+                value = !value;
+                redraw();
+                return;
+            }
+            if (key?.name === "return" || key?.name === "space") {
+                cleanup();
+                resolve(value);
+            }
+        };
+        io.input.on("keypress", onKeypress);
+    });
+}

package/dist/packages/cli/src/version.js

@@ -0,0 +1,3 @@
+// Single source of the published CLI version. Release preparation updates
+// this constant; bin.ts and the hook entry both read it from here.
+export const CLI_VERSION = "0.1.3";

package/dist/runtime/src/adapters/claude/config.js

@@ -83,6 +83,25 @@ function hookRecord(settings) {
     }
     return settings.hooks;
 }
+/**
+ * Removes every agent-ops owned handler and leaves foreign hooks untouched.
+ */
+export function stripClaudeManagedHooks(existing) {
+    if (!isRecord(existing)) {
+        throw new AgentOpsError("CLAUDE_SETTINGS_INVALID", "Claude settings must be a JSON object.");
+    }
+    const existingHooks = hookRecord(existing);
+    const hooks = {};
+    for (const [eventName, groups] of Object.entries(existingHooks)) {
+        const preserved = groups
+            .map(withoutOwnedHandlers)
+            .filter((group) => group !== null);
+        if (preserved.length > 0) {
+            hooks[eventName] = preserved;
+        }
+    }
+    return { ...existing, hooks };
+}
 export function mergeClaudeSettings(existing, managed) {
     if (!isRecord(existing)) {
         throw new AgentOpsError("CLAUDE_SETTINGS_INVALID", "Claude settings must be a JSON object.");

package/dist/runtime/src/adapters/codex/config.js

@@ -67,6 +67,22 @@ function hookRecord(value) {
     }
     return value.hooks;
 }
+/**
+ * Removes every agent-ops owned handler and leaves foreign hooks untouched.
+ */
+export function stripCodexManagedHooks(existing) {
+    const existingHooks = hookRecord(existing);
+    const hooks = {};
+    for (const [eventName, groups] of Object.entries(existingHooks)) {
+        const preserved = groups
+            .map(withoutOwnedHandlers)
+            .filter((group) => group !== null);
+        if (preserved.length > 0) {
+            hooks[eventName] = preserved;
+        }
+    }
+    return { ...existing, hooks };
+}
 export function mergeCodexHookConfig(existing, managed) {
     if (!isRecord(existing)) {
         throw new AgentOpsError("CODEX_HOOK_CONFIG_INVALID", "Codex hook configuration must be a JSON object.");

package/dist/runtime/src/install/harness.js

@@ -57,7 +57,7 @@ export function commonHarnessAdapters() {
         };
     });
 }
-function requestedHarnessIds(harness) {
+export function requestedHarnessIds(harness) {
     return harness === "both" ? ["codex", "claude"] : [harness];
 }
 function selectAdapter(id, adapters) {

package/dist/runtime/src/install/hooks.js

@@ -0,0 +1,77 @@
+import { buildClaudeHookSettings, mergeClaudeSettings, stripClaudeManagedHooks } from "../adapters/claude/config.js";
+import { buildCodexHookConfig, mergeCodexHookConfig, stripCodexManagedHooks } from "../adapters/codex/config.js";
+import { AgentOpsError } from "../fs/paths.js";
+export const CLAUDE_HOOK_PATH = ".claude/settings.json";
+export const CODEX_HOOK_PATH = ".codex/hooks.json";
+function format(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function parseSettings(path, source) {
+    if (source === null || source.trim().length === 0) {
+        return {};
+    }
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new AgentOpsError("HOOK_SETTINGS_INVALID_JSON", `Hook settings are not valid JSON: ${path}`, { cause: error });
+    }
+}
+export function hookRegistrationPath(harness, scope) {
+    // ponytail: user scope resolves against AGENT_OPS_HOME, so the same
+    // relative path serves both scopes.
+    void scope;
+    return harness === "claude" ? CLAUDE_HOOK_PATH : CODEX_HOOK_PATH;
+}
+/**
+ * Builds the merged settings file for one harness, preserving foreign hooks.
+ * Returns null when the selected capabilities register no events at all.
+ */
+export function planHookRegistration(options) {
+    const path = hookRegistrationPath(options.harness, options.scope);
+    const managed = options.harness === "claude"
+        ? buildClaudeHookSettings(options.capabilities, options.runtimePath)
+        : buildCodexHookConfig(options.capabilities);
+    const events = Object.keys(managed.hooks);
+    if (events.length === 0) {
+        return null;
+    }
+    const existing = parseSettings(path, options.currentSource);
+    const merged = options.harness === "claude"
+        ? mergeClaudeSettings(existing, managed)
+        : mergeCodexHookConfig(existing, managed);
+    return {
+        content: format(merged),
+        record: {
+            id: `${options.harness}-hooks`,
+            path,
+            harness: options.harness,
+            events,
+            owner: "agent-ops"
+        }
+    };
+}
+function onlyManagedRemains(harness, value) {
+    const ownKeys = new Set(harness === "codex" ? ["hooks", "description"] : ["hooks"]);
+    const hooks = value.hooks;
+    return (Object.keys(value).every((key) => ownKeys.has(key)) &&
+        typeof hooks === "object" &&
+        hooks !== null &&
+        Object.keys(hooks).length === 0);
+}
+/**
+ * Strips owned handlers from a hook settings file. The file is removed only
+ * when nothing but agent-ops content is left, so foreign settings survive.
+ */
+export function planHookRemoval(record, currentSource) {
+    const existing = parseSettings(record.path, currentSource);
+    const stripped = record.harness === "claude"
+        ? stripClaudeManagedHooks(existing)
+        : stripCodexManagedHooks(existing);
+    return {
+        path: record.path,
+        content: onlyManagedRemains(record.harness, stripped)
+            ? null
+            : format(stripped)
+    };
+}

package/dist/runtime/src/install/ownership.js

@@ -1,6 +1,7 @@
 import { applyManagedBlock, managedBlockMarkers } from "../fs/managed-block.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { COMMON_AGENTS_BLOCK, COMMON_CLAUDE_BLOCK } from "./harness.js";
+import { hookRegistrationPath } from "./hooks.js";
 function selectedHarnesses(manifest) {
     return manifest.harness === "both"
         ? ["codex", "claude"]
@@ -24,6 +25,24 @@ function expectedMarker(manifest, id) {
 function manifestOwnershipError() {
     return new AgentOpsError("MANIFEST_OWNERSHIP_INVALID", "The manifest does not match a supported managed installation shape.");
 }
+/**
+ * Hook records are optional: installations without hook capabilities, and
+ * manifests written before hook registration existed, carry none.
+ */
+function assertSupportedHookRecords(manifest, harnesses) {
+    const selected = new Set(harnesses);
+    const seen = new Set();
+    for (const hook of manifest.hooks ?? []) {
+        if (!selected.has(hook.harness) ||
+            seen.has(hook.harness) ||
+            hook.id !== `${hook.harness}-hooks` ||
+            hook.path !== hookRegistrationPath(hook.harness, manifest.scope) ||
+            hook.events.length === 0) {
+            throw manifestOwnershipError();
+        }
+        seen.add(hook.harness);
+    }
+}
 export function assertSupportedManifestOwnership(manifest) {
     const harnesses = selectedHarnesses(manifest);
     const expectedArtifacts = new Map([
@@ -53,6 +72,7 @@ export function assertSupportedManifestOwnership(manifest) {
             throw manifestOwnershipError();
         }
     }
+    assertSupportedHookRecords(manifest, harnesses);
     return expectedMarkers;
 }
 function exactMarkerCount(source, marker) {

package/dist/runtime/src/install/plan.js

@@ -5,7 +5,8 @@ import { applyManagedBlock, managedBlockMarkers } from "../fs/managed-block.js";
 import { formatInstallManifest, parseInstallManifest } from "../fs/manifest.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { validateConfig } from "../schema/validate.js";
-import { planHarnessContributions } from "./harness.js";
+import { planHarnessContributions, requestedHarnessIds } from "./harness.js";
+import { hookRegistrationPath, planHookRegistration } from "./hooks.js";
 import { resolveProfiles } from "./profiles.js";
 const CONFIG_PATH = ".agent-ops/config.json";
 const MANIFEST_PATH = ".agent-ops/manifest.json";
@@ -233,12 +234,36 @@ export async function createInstallPlan(options) {
     }
     const plannedBlocks = await planBlocks(options.root, contribution.blocks);
     operations.push(...plannedBlocks.operations);
+    const hooks = [];
+    if (options.hookRuntimePath !== undefined) {
+        for (const harness of requestedHarnessIds(options.harness)) {
+            const current = await readCurrentFile(options.root, hookRegistrationPath(harness, options.scope));
+            const planned = planHookRegistration({
+                harness,
+                scope: options.scope,
+                capabilities: resolved.capabilities,
+                runtimePath: options.hookRuntimePath,
+                currentSource: current?.content ?? null
+            });
+            if (planned === null) {
+                continue;
+            }
+            operations.push({
+                kind: "write",
+                path: planned.record.path,
+                content: planned.content,
+                expectedHash: current?.hash ?? null
+            });
+            hooks.push(planned.record);
+        }
+    }
     const manifest = {
         schemaVersion: SCHEMA_VERSION,
         scope: options.scope,
         harness: options.harness,
         artifacts,
-        markers: plannedBlocks.records
+        markers: plannedBlocks.records,
+        ...(hooks.length === 0 ? {} : { hooks })
     };
     operations.push({
         kind: "write",

package/dist/runtime/src/install/uninstall.js

@@ -5,6 +5,7 @@ import { removeManagedBlock } from "../fs/managed-block.js";
 import { parseInstallManifest } from "../fs/manifest.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { FileTransaction } from "../fs/transaction.js";
+import { planHookRemoval } from "./hooks.js";
 import { assertExpectedManagedBlock, assertSupportedManifestOwnership } from "./ownership.js";
 const MANIFEST_PATH = ".agent-ops/manifest.json";
 const MAX_UNINSTALL_FILE_BYTES = 1024 * 1024;
@@ -130,6 +131,25 @@ export async function createUninstallPlan(root) {
         });
     }
     operations.push(...await planMarkerFiles(root, manifest.markers, expectedMarkers));
+    for (const hook of manifest.hooks ?? []) {
+        const current = await readCurrentFile(root, hook.path);
+        if (current === null) {
+            continue;
+        }
+        const removal = planHookRemoval(hook, current.content);
+        operations.push(removal.content === null
+            ? {
+                kind: "remove",
+                path: hook.path,
+                expectedHash: current.hash
+            }
+            : {
+                kind: "write",
+                path: hook.path,
+                content: removal.content,
+                expectedHash: current.hash
+            });
+    }
     operations.push({
         kind: "remove",
         path: MANIFEST_PATH,
@@ -149,6 +169,7 @@ function allowedPaths(plan) {
     return new Set([
         ...plan.manifest.artifacts.map(({ path }) => path.toLowerCase()),
         ...plan.manifest.markers.map(({ path }) => path.toLowerCase()),
+        ...(plan.manifest.hooks ?? []).map(({ path }) => path.toLowerCase()),
         MANIFEST_PATH
     ]);
 }
@@ -187,6 +208,13 @@ async function validateUninstalled(root, manifest) {
             throw new AgentOpsError("UNINSTALL_VALIDATION_FAILED", `Managed block still exists: ${marker.path}`);
         }
     }
+    for (const hook of manifest.hooks ?? []) {
+        const current = await readCurrentFile(root, hook.path);
+        if (current !== null &&
+            planHookRemoval(hook, current.content).content !== current.content) {
+            throw new AgentOpsError("UNINSTALL_VALIDATION_FAILED", `Managed hook handlers still exist: ${hook.path}`);
+        }
+    }
     if (await readCurrentFile(root, MANIFEST_PATH) !== null) {
         throw new AgentOpsError("UNINSTALL_VALIDATION_FAILED", "Installation manifest still exists.");
     }

package/dist/runtime/src/install/update.js

@@ -107,6 +107,9 @@ export async function createUpdatePlan(options) {
         profiles: configPreview.migrated.profiles,
         adapters: options.adapters,
         toolkitVersion: targetVersion,
+        ...(options.hookRuntimePath === undefined
+            ? {}
+            : { hookRuntimePath: options.hookRuntimePath }),
         existingConfig: {
             value: configPreview.migrated,
             sourceHash: configPreview.sourceHash

package/dist/runtime/src/schema/validate.js

@@ -6,6 +6,12 @@ const PROFILE_VALUES = new Set(["advisory", "core", "guardrails"]);
 const EVIDENCE_KINDS = new Set(["exit-code", "file", "test-count"]);
 const SCOPE_VALUES = new Set(["project", "user"]);
 const HARNESS_VALUES = new Set(["both", "claude", "codex"]);
+const HOOK_HARNESS_VALUES = new Set(["claude", "codex"]);
+const HOOK_EVENT_VALUES = new Set([
+    "SessionStart",
+    "PreToolUse",
+    "Stop"
+]);
 const MAX_TIMEOUT_MS = 2_147_483_647;
 const MAX_EXIT_CODE = 4_294_967_295;
 function failure(code, path, message) {
@@ -520,10 +526,40 @@ function validateManagedMarker(value, path) {
     }
     return success(value);
 }
+function validateManagedHook(value, path) {
+    if (!isRecord(value)) {
+        return failure("INVALID_TYPE", path, "Expected a managed hook record.");
+    }
+    const unknown = unknownFieldFailure(value, ["events", "harness", "id", "owner", "path"], path);
+    if (unknown !== undefined) {
+        return unknown;
+    }
+    if (!isIdentifier(value.id)) {
+        return failure("INVALID_ID", `${path}.id`, "Invalid managed entry ID.");
+    }
+    if (!isSafeRelativePath(value.path) || value.path === ".") {
+        return failure("INVALID_RELATIVE_PATH", `${path}.path`, "Managed paths must be project-relative.");
+    }
+    if (typeof value.harness !== "string" ||
+        !HOOK_HARNESS_VALUES.has(value.harness)) {
+        return failure("INVALID_HARNESS", `${path}.harness`, "Hook records must name a single harness.");
+    }
+    if (!isStringArray(value.events) ||
+        value.events.length === 0 ||
+        new Set(value.events).size !== value.events.length ||
+        value.events.some((event) => !HOOK_EVENT_VALUES.has(event))) {
+        return failure("INVALID_HOOK_EVENTS", `${path}.events`, "Hook records must list distinct supported events.");
+    }
+    if (value.owner !== "agent-ops") {
+        return failure("INVALID_OWNER", `${path}.owner`, "Managed entries must be owned by agent-ops.");
+    }
+    return success(value);
+}
 export function validateManifest(value) {
     const root = validateRoot(value, [
         "artifacts",
         "harness",
+        "hooks",
         "markers",
         "schemaVersion",
         "scope"
@@ -580,5 +616,26 @@ export function validateManifest(value) {
         markerBoundaries.add(startBoundary);
         markerBoundaries.add(endBoundary);
     }
+    if (root.hooks !== undefined) {
+        if (!Array.isArray(root.hooks)) {
+            return failure("INVALID_TYPE", "$.hooks", "hooks must be an array.");
+        }
+        const hookPaths = new Set();
+        for (const [index, hookValue] of root.hooks.entries()) {
+            const hook = validateManagedHook(hookValue, `$.hooks[${index}]`);
+            if (!hook.ok) {
+                return hook;
+            }
+            const hookPathKey = hook.value.path.toLowerCase();
+            if (entryIds.has(hook.value.id)) {
+                return failure("DUPLICATE_ID", `$.hooks[${index}].id`, `Duplicate manifest entry ID: ${hook.value.id}`);
+            }
+            if (artifactPaths.has(hookPathKey) || hookPaths.has(hookPathKey)) {
+                return failure("DUPLICATE_OWNERSHIP", `$.hooks[${index}].path`, `Hook path is owned more than once: ${hook.value.path}`);
+            }
+            entryIds.add(hook.value.id);
+            hookPaths.add(hookPathKey);
+        }
+    }
     return success(root);
 }