@kylecheng3146/agent-ops 0.1.2 → 0.1.4

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);
 }

package/dist/runtime/src/security/permissions.js

@@ -241,7 +241,9 @@ async function readWindowsProcessIdentity(processId) {
         ], {
             encoding: "utf8",
             maxBuffer: 4096,
-            timeout: 2000,
+            // ponytail: cold PowerShell start on a loaded machine routinely
+            // passes two seconds; the lock budget above still bounds the wait.
+            timeout: 10_000,
             windowsHide: true
         });
         const startedAt = result.stdout.trim();
@@ -251,10 +253,27 @@ async function readWindowsProcessIdentity(processId) {
         return null;
     }
 }
+/**
+ * A live process cannot change its own start time, so a successful self
+ * lookup never expires. Every other entry keeps the short TTL: foreign
+ * process IDs get recycled, and a failed self lookup must stay retryable
+ * instead of pinning the fallback identity for the whole run.
+ */
+export function reuseCachedProcessIdentity(entry, processId, selfProcessId, now) {
+    if (entry === undefined) {
+        return false;
+    }
+    if (processId === selfProcessId &&
+        entry.identity !== null &&
+        !entry.identity.startsWith("runtime:")) {
+        return true;
+    }
+    return now - entry.checkedAt <= PROCESS_IDENTITY_CACHE_MS;
+}
 async function readProcessIdentity(processId) {
     const cached = processIdentityCache.get(processId);
-    if (cached !== undefined &&
-        Date.now() - cached.checkedAt <= PROCESS_IDENTITY_CACHE_MS) {
+    if (reuseCachedProcessIdentity(cached, processId, process.pid, Date.now()) &&
+        cached !== undefined) {
         return cached.identity;
     }
     let identity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Evidence-driven development loops for Codex and Claude Code",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,8 @@
     "docs/zh-TW/spec/",
     "README.md",
     "LICENSE",
-    "SECURITY.md"
+    "SECURITY.md",
+    "postinstall.cjs"
   ],
   "publishConfig": {
     "access": "public"
@@ -30,7 +31,8 @@
     "test:compile": "node scripts/clean.mjs .tmp && tsc -p tsconfig.test.json",
     "test": "npm run test:compile && node scripts/run-tests.mjs .tmp/test-dist/tests",
     "build": "node scripts/clean.mjs dist && tsc -p tsconfig.build.json",
-    "package:check": "node scripts/package-check.mjs"
+    "package:check": "node scripts/package-check.mjs",
+    "postinstall": "node postinstall.cjs"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/postinstall.cjs

@@ -0,0 +1,102 @@
+"use strict";
+
+const { closeSync, existsSync, openSync, readFileSync } = require("node:fs");
+const { join, resolve } = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { isatty } = require("node:tty");
+
+const PACKAGE_NAME = "@kylecheng3146/agent-ops";
+const packageRoot = __dirname;
+const installRoot = resolve(process.env.INIT_CWD ?? process.cwd());
+
+function isDirectDependency() {
+  try {
+    const packageJson = JSON.parse(
+      readFileSync(join(installRoot, "package.json"), "utf8")
+    );
+    return [
+      packageJson.dependencies,
+      packageJson.devDependencies,
+      packageJson.optionalDependencies,
+      packageJson.peerDependencies
+    ].some(
+      (dependencies) =>
+        dependencies !== null &&
+        typeof dependencies === "object" &&
+        dependencies[PACKAGE_NAME] !== undefined
+    );
+  } catch {
+    return false;
+  }
+}
+
+function openTerminal() {
+  if (process.stdin.isTTY === true && process.stdout.isTTY === true) {
+    return { stdio: "inherit", close() {} };
+  }
+
+  const inputPath = process.platform === "win32" ? "CONIN$" : "/dev/tty";
+  const outputPath = process.platform === "win32" ? "CONOUT$" : "/dev/tty";
+  let inputFd;
+  let outputFd;
+  try {
+    inputFd = openSync(inputPath, "r");
+    outputFd = process.platform === "win32" ? openSync(outputPath, "a") : inputFd;
+    if (!isatty(inputFd) || !isatty(outputFd)) {
+      throw new Error("Interactive terminal is unavailable.");
+    }
+    return {
+      stdio: [inputFd, outputFd, outputFd],
+      close() {
+        if (outputFd !== inputFd) {
+          closeSync(outputFd);
+        }
+        closeSync(inputFd);
+      }
+    };
+  } catch {
+    if (outputFd !== undefined && outputFd !== inputFd) {
+      closeSync(outputFd);
+    }
+    if (inputFd !== undefined) {
+      closeSync(inputFd);
+    }
+    return null;
+  }
+}
+
+if (
+  installRoot === resolve(packageRoot) ||
+  process.env.CI !== undefined ||
+  !isDirectDependency()
+) {
+  process.exit(0);
+}
+
+const terminal = openTerminal();
+if (terminal === null) {
+  process.exit(0);
+}
+
+const cliPath = join(packageRoot, "dist", "packages", "cli", "src", "bin.js");
+if (!existsSync(cliPath)) {
+  process.stderr.write(
+    "agent-ops init was skipped because the installed CLI is unavailable.\n"
+  );
+  terminal.close();
+  process.exit(0);
+}
+
+const result = spawnSync(process.execPath, [cliPath], {
+  cwd: installRoot,
+  env: process.env,
+  stdio: terminal.stdio
+});
+terminal.close();
+
+if (result.error !== undefined || result.status !== 0) {
+  process.stderr.write(
+    "agent-ops init was not applied; package installation completed. " +
+      "Run `agent-ops` to retry.\n"
+  );
+}

package/schemas/manifest.schema.json

@@ -26,6 +26,12 @@
       "items": {
         "$ref": "#/$defs/managedMarker"
       }
+    },
+    "hooks": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/managedHook"
+      }
     }
   },
   "$defs": {
@@ -104,6 +110,33 @@
         }
       }
     },
+    "managedHook": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "path", "harness", "events", "owner"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "path": {
+          "$ref": "#/$defs/relativePath"
+        },
+        "harness": {
+          "enum": ["codex", "claude"]
+        },
+        "events": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": ["SessionStart", "PreToolUse", "Stop"]
+          }
+        },
+        "owner": {
+          "const": "agent-ops"
+        }
+      }
+    },
     "nonEmptyString": {
       "type": "string",
       "pattern": "[^\\s\\u0000]",