@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/hooks/cache.js

@@ -1,30 +1,7 @@
-/**
- * Declarative hook caching + timing.
- *
- * Hooks that opt in via `cache:` in hooks.yaml get a generated bash shim
- * (~/.agents/.cache/shims/hooks/<name>.sh) registered with the agent instead
- * of the raw script path. The shim handles:
- *
- *   1. cache lookup — reads ~/.agents/.cache/state/hooks/<name>.<key>.out
- *      and serves it if newer than ttl.
- *   2. stale-while-revalidate — when prefetch=background, serves stale cache
- *      and refreshes the cache file in a detached child.
- *   3. timing — appends one JSONL line per fire to events-YYYY-MM-DD.jsonl.
- *
- * The shim is regenerated whenever the registrar runs; if its content doesn't
- * change (idempotent), mtime is preserved. Stale shims for removed hooks are
- * cleaned by the registrar's garbage collection (shims dir is in
- * managedPrefixes).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { getHookCacheDir, getHookShimsDir, getLogsDir, getPerfDir } from '../state.js';
-/**
- * Parse a `cache:` value from hooks.yaml into the canonical config form.
- * Accepts the shorthand string ("5m", "30s-bg") or the full object form.
- * Returns null if the value is missing or unparseable.
- */
 export function parseCacheConfig(raw) {
     if (raw == null)
         return null;
@@ -52,7 +29,6 @@ function parseShorthand(s) {
         return null;
     return { ttl: ttlSec, key: 'global', prefetch };
 }
-/** Parse "30s" | "5m" | "1h" | "7d" | plain seconds. Returns seconds, or null on failure. */
 export function parseDuration(d) {
     if (d == null)
         return null;
@@ -73,11 +49,7 @@ export function parseDuration(d) {
         return value * 60;
     return value;
 }
-/**
- * Reject hook names that could escape the shims directory when interpolated
- * into a filename. Mirrors the containment gate on hook script resolution in
- * hooks.ts (`resolveContainedHookPath`).
- */
+// Shim names become path segments; validation is the traversal boundary.
 export function isValidHookShimName(name) {
     return (!!name &&
         name !== '.' &&
@@ -86,7 +58,6 @@ export function isValidHookShimName(name) {
         !/[\/\\\x00]/.test(name) &&
         name.length <= 255);
 }
-/** Resolve shimsDir + `${name}.sh` and assert the result stays inside shimsDir. */
 function resolveContainedHookShimPath(shimsDir, name) {
     if (!isValidHookShimName(name)) {
         throw new Error(`Invalid hook shim name: ${name}`);
@@ -99,20 +70,9 @@ function resolveContainedHookShimPath(shimsDir, name) {
     }
     return resolved;
 }
-/** Absolute path of the generated shim for a hook name. */
 export function getHookShimPath(name) {
     return resolveContainedHookShimPath(getHookShimsDir(), name);
 }
-/**
- * Generate (or refresh) the shim script for a hook. Idempotent — only writes
- * when the content differs from what's on disk. Returns the absolute shim path.
- *
- * A shim is generated when the hook opts into caching (`cache`) and/or declares
- * `matches:` predicates. When `matches` is present the shim gates execution on
- * those predicates before running the underlying script (see `renderShim`);
- * when `cache` is absent the shim is a thin pass-through wrapper that only
- * applies the gate and forwards stdin/stdout unchanged.
- */
 export function generateHookShim(args) {
     const shimsDir = args.paths?.shimsDir ?? getHookShimsDir();
     const cacheDir = args.paths?.cacheDir ?? getHookCacheDir();
@@ -126,13 +86,10 @@ export function generateHookShim(args) {
         try {
             existing = fs.readFileSync(shimPath, 'utf-8');
         }
-        catch { /* rewrite */ }
+        catch { }
     }
+    // Temp-write/chmod/rename keeps a concurrently firing hook from seeing a truncated shim.
     if (existing !== content) {
-        // A hook may fire while a background self-heal repairs another stale shim.
-        // Write in the destination directory and rename only after its mode and
-        // complete contents are ready, so observers see either the old complete
-        // wrapper or the new complete wrapper — never a truncated shell script.
         const tempPath = path.join(shimsDir, `.${path.basename(shimPath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
         try {
             fs.writeFileSync(tempPath, content, { mode: 0o755 });
@@ -140,38 +97,20 @@ export function generateHookShim(args) {
             fs.renameSync(tempPath, shimPath);
         }
         finally {
-            // Rename removes the temp path on success. On a failed write/rename this
-            // best-effort cleanup prevents a bounded repair failure from leaving
-            // growing debris behind for every periodic pass.
             try {
                 fs.unlinkSync(tempPath);
             }
-            catch { /* already renamed or unavailable */ }
+            catch { }
         }
     }
     else {
-        // Ensure exec bit even when content unchanged (file mode can drift).
         try {
             fs.chmodSync(shimPath, 0o755);
         }
-        catch { /* best effort */ }
+        catch { }
     }
     return shimPath;
 }
-/**
- * The matches: gate, as a self-contained Python program run once per fire.
- *
- * Reads the hook's `matches:` block from $MATCHES_JSON and the event JSON from
- * stdin, then prints `FIRE` or `SKIP`. A faithful port of `shouldFire()` in
- * src/lib/hooks/match.ts — all declared predicates AND together, an empty block
- * always fires, and the same ReDoS guard (`isSafeHookRegex`) rejects unsafe
- * regexes to `SKIP`. Kept in double-quotes/apostrophe-free so it survives being
- * embedded in a single-quoted `python -c '...'` argument in the shim. Behavioural
- * parity with shouldFire() is pinned by a conformance test (match-parity.test.ts).
- *
- * On any exception it does NOT print SKIP — the shim treats a missing/garbled
- * verdict as FIRE (fail-open), so a broken gate never silently disables a hook.
- */
 const GATE_PY = `import json, os, re, subprocess, sys
 
 def arr(v):
@@ -323,11 +262,6 @@ def should_fire():
 
 print("FIRE" if should_fire() else "SKIP")
 `;
-/**
- * Gate-only pass-through tail: no caching, just run the underlying script with
- * stdin forwarded and stdout/exit code propagated, plus one timing log line.
- * Used when a hook declares \`matches:\` but no \`cache:\`.
- */
 const PASSTHROUGH_TAIL = `now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
 START_NS=$(now_ns)
 EXIT=0
@@ -350,19 +284,6 @@ printf '{"ts_ms":%s,"kind":"hook.fire","label":"%s","duration_ms":%d,"cache":"%s
   "$TS_MS" "$HOOK_NAME" "$MS" "none" "$EXIT" "$HOST" "$HOOK_EXTRA_JSON" >>"$PERF_SPOOL" 2>/dev/null || true
 
 exit "$EXIT"`;
-/**
- * Render the bash shim. Bash 3.2-compatible (macOS default). Uses Python for
- * hashing + monotonic-ish nanosecond timing + portable mtime, resolved at
- * runtime (python3, then python) so a Windows Microsoft Store `python3` alias
- * stub — which exits non-zero without running — doesn't silently break caching.
- *
- * When `matches` is set, an early gate block evaluates the `matches:` predicates
- * against the event JSON on stdin and exits 0 without running the script when
- * they don't hold — this is the runtime enforcement of the documented `matches:`
- * gating (mirrors `shouldFire()` in match.ts). When `cache` is null the shim is
- * a gate-only pass-through: it forwards stdin to the script and its stdout back,
- * with no cache read/write.
- */
 function renderShim(name, scriptPath, cache, matches, paths, failClosed = false) {
     const ttl = cache ? (typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0)) : 0;
     const key = cache?.key ?? 'global';
@@ -371,7 +292,6 @@ function renderShim(name, scriptPath, cache, matches, paths, failClosed = false)
     const perfSpool = path.join(perfDir, 'spool.jsonl');
     const hasMatches = matches != null && Object.keys(matches).length > 0;
     const matchesJson = hasMatches ? JSON.stringify(matches) : '';
-    // sh-escape: wrap in single quotes, escape any embedded single quotes.
     const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
     const cacheHeader = cache
         ? `# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}`
@@ -398,11 +318,6 @@ FAIL_CLOSED=${failClosed ? 1 : 0}
 
 mkdir -p "$CACHE_DIR" "$LOGS_DIR" "$PERF_DIR"
 
-# Resolve a real Python. On Windows, bare python3 is often a Microsoft Store
-# app-execution alias stub that prints to stderr and exits non-zero (0 bytes on
-# stdout) -- command -v finds it but it cannot run, which silently empties the
-# hash + mtime primitives below and makes EVERY call a cache miss (the hook
-# re-runs every time). Probe by executing, not by lookup, and fall back to python.
 PY=""
 for _cand in python3 python; do
   if command -v "$_cand" >/dev/null 2>&1 && "$_cand" -c 'import sys' >/dev/null 2>&1; then
@@ -411,15 +326,8 @@ for _cand in python3 python; do
 done
 [ -z "$PY" ] && PY=python3
 
-# Read stdin once (Claude/Codex/Gemini pass JSON on stdin to every hook).
 STDIN_PAYLOAD="$(cat || true)"
 
-# cwd + session_id from the hook's own stdin JSON, pre-escaped as a ready-to-
-# splice JSON fragment (e.g. ,"cwd":"/repo","session_id":"abc") so every
-# hook.fire perf-spool line below can carry them without re-parsing stdin per
-# site. This is what lets \`agents perf --project\` (project-key.ts resolves
-# cwd -> project) and session-scoped rollups work for hook.fire samples.
-# Fail-safe: any parse error yields an empty fragment, never breaks the write.
 HOOK_EXTRA_JSON="$(printf '%s' "$STDIN_PAYLOAD" | "$PY" -c '
 import json, sys
 try:
@@ -436,13 +344,7 @@ if isinstance(sid, str) and sid:
 print("".join("," + json.dumps(k) + ":" + json.dumps(v) for k, v in out.items()))
 ' 2>/dev/null || true)"
 
-# --- matches: gate (issue #744 / RUSH-1506) -------------------------------
-# Enforce the hook's declared \`matches:\` predicates at fire time. Mirrors
-# shouldFire() in src/lib/hooks/match.ts: all declared predicates AND together;
-# an empty/absent block always fires. When the predicates don't hold we exit 0
-# WITHOUT running the script (a skipped hook is not an error). Fail-open: any
-# gate-eval error runs the script, so a broken predicate can never silently
-# disable a safety hook (e.g. git-guard).
+# Predicate failures default to FIRE so evaluation errors cannot silently disable a guard.
 if [ -n "$MATCHES_JSON" ]; then
   _GATE="$(printf '%s' "$STDIN_PAYLOAD" | MATCHES_JSON="$MATCHES_JSON" "$PY" -c ${q(GATE_PY)} 2>/dev/null || printf FIRE)"
   [ -z "$_GATE" ] && _GATE=FIRE
@@ -459,14 +361,7 @@ if [ -n "$MATCHES_JSON" ]; then
     exit 0
   fi
 fi
-# A source that is not on disk cannot be executed: bash exits 127, and the
-# harnesses that share the exit-2 deny contract (Claude Code, Codex, Droid)
-# read anything else as "allow" -- a guard silently disabled. Deny instead and
-# name the repair, but only for a PreToolUse firing that the matches: gate
-# above let through: one shim serves every event a hook declares, so a
-# SessionStart or Stop leg of the same hook must not wedge a session, and a
-# fire the predicates would have skipped must not turn into a denial. Other
-# shims keep their existing path (a cached hook still serves its cache).
+# PreToolUse exits 2: these harnesses interpret 127 as allow.
 if [ "$FAIL_CLOSED" = 1 ] && [ ! -f "$SOURCE" ]; then
   _EVT="$(printf '%s' "$STDIN_PAYLOAD" | "$PY" -c 'import json, sys
 try:
@@ -486,11 +381,6 @@ fi
 ${cache ? CACHE_TAIL : PASSTHROUGH_TAIL}
 `;
 }
-/**
- * Cache tail: the full cache lookup / stale-while-revalidate / timing machinery.
- * Emitted only when the hook opts into \`cache:\`. (When only \`matches:\` is set,
- * PASSTHROUGH_TAIL runs instead — no cache read/write.)
- */
 const CACHE_TAIL = `# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
 # \`sha1sum\` is coreutils, missing on macOS. Truncate to 12 hex chars.
 sha1_12() { "$PY" -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().encode()).hexdigest()[:12])'; }
@@ -633,10 +523,6 @@ printf '{"ts_ms":%s,"kind":"hook.fire","label":"%s","duration_ms":%d,"cache":"%s
 
 exit "$EXIT"
 `;
-/**
- * Remove a hook's shim. Called by the registrar's garbage collection when a
- * hook is renamed/deleted or has its `cache:` field removed.
- */
 export function removeHookShim(name, shimsDir) {
     if (!isValidHookShimName(name))
         return;
@@ -646,6 +532,6 @@ export function removeHookShim(name, shimsDir) {
         try {
             fs.unlinkSync(shimPath);
         }
-        catch { /* best effort */ }
+        catch { }
     }
 }

package/dist/lib/hooks/install.d.ts

@@ -1,33 +1,5 @@
-/**
- * Hook management -- discovery, registration, and syncing of event hooks.
- *
- * Hooks are shell scripts in ~/.agents/hooks/ that fire on agent events
- * (tool calls, session start, etc.). Each hook directory contains a manifest
- * (agents.yaml) declaring events, matchers, and timeout. This module handles
- * parsing those manifests, registering hooks into agent-native settings files,
- * and syncing them across version switches.
- */
 export declare function resolveHookScriptPath(script: string): string | null;
-/**
- * Convert an absolute path under HOME to a portable ~/... form with forward
- * slashes. Hook commands stored this way work on both macOS and Windows:
- * absolute Windows paths break in bash because backslashes are stripped as
- * escape characters, whereas ~/... paths expand correctly via the ~/.claude
- * symlink/junction on both platforms.
- *
- * `home` and `sep` are injectable so the Windows behavior (backslash sep,
- * drive-letter home) is unit-testable on a POSIX CI host — pass sep='\\' to
- * simulate Windows. With the defaults this is byte-identical to reading
- * os.homedir()/path.sep at the call site.
- */
 export declare function toPortableCommand(absPath: string, home?: string, sep?: string): string;
-/**
- * Collapse version-scoped registrations by logical resource identity rather
- * than absolute command path. When the same resource is present in several
- * homes, the active home's command wins even if it appears later. Commands
- * outside version homes are user-owned and remain untouched.
- */
-export declare function deduplicateVersionHookCommands(commands: string[], activeVersionHome: string): string[];
 import type { AgentId, HookCacheConfig, HookMatches, InstalledHook, ManifestHook } from '../types.js';
 type HookEntry = {
     name: string;
@@ -49,28 +21,8 @@ export interface DuplicateVersionHook {
     authoritative: VersionHookCopy;
     copies: VersionHookCopy[];
 }
-/**
- * Inspect every installed hooks-capable harness without assuming a native
- * settings format. Same-name copies with one content hash are installation
- * noise; multiple hashes are drift. The active version is always selected as
- * the authoritative copy when it participates in the group.
- */
 export declare function inspectDuplicateVersionHooks(cwd?: string): DuplicateVersionHook[];
-/**
- * List hook entries in a single directory, grouping script + data files by
- * basename. Also discovers scripts in one-level group subdirs
- * (hooks/session-starts/). Exported so doctor-diff can reuse the same grouping
- * the sync path applies; without this, doctor would double-count `foo.sh` and
- * `foo.yaml`. On basename collision, the top-level file wins over a nested one.
- */
 export declare function listHookEntriesFromDir(dir: string): HookEntry[];
-/**
- * Hooks dir for an agent under an arbitrary home (version home or effective
- * home). An agent whose `hooksDir` is configured absolute under `$HOME` (grok,
- * kimi) must be translated to config-dir-relative first — a raw `path.join`
- * would embed the absolute path as a relative segment and produce a hybrid
- * path that never exists (RUSH-2237).
- */
 export declare function getHooksDirInHome(agentId: AgentId, home: string): string;
 export declare function listInstalledHooksWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
@@ -81,27 +33,14 @@ export declare function installHooks(source: string, agents: AgentId[], options?
     installed: string[];
     errors: string[];
 }>;
-/**
- * Path to the hooks dir of a specific version home (not the active one).
- */
 export declare function getVersionHooksDir(agent: AgentId, version: string): string;
-/**
- * List hook entries in a specific version home.
- */
 export declare function listHooksInVersionHome(agent: AgentId, version: string): HookEntry[];
 export interface HookWiringIssue {
-    /** Hook name (script basename minus extension). */
     name: string;
-    /** Native lifecycle event the hook should be wired to (Stop, PreToolUse, …). */
     event: string;
-    /** Matcher group the hook belongs to under `event` (`''` = the catch-all
-     *  group). Real hooks scope by matcher — ask-user-question-guard=AskUserQuestion,
-     *  user-message-guard=Bash — so wiring is verified per (event, matcher). */
     matcher: string;
-    /** The command the harness-native config should reference under `event`. */
     command: string;
 }
-/** A generated, agents-managed hook wrapper and the inputs needed to recreate it. */
 interface ManagedHookRuntimeArtifact {
     agent: AgentId;
     version: string;
@@ -111,72 +50,44 @@ interface ManagedHookRuntimeArtifact {
     cache: HookCacheConfig | null;
     matches?: HookMatches;
 }
-/** A generated hook wrapper that is referenced by managed configuration but cannot run. */
 export interface BrokenManagedHookRuntimeArtifact extends ManagedHookRuntimeArtifact {
-    /** Stable, human-readable filesystem failure; the hook is never executed to find it. */
     reason: string;
 }
-/** Public, doctor-safe shape for a broken generated hook wrapper. */
 export interface HookRuntimeIssue {
     name: string;
     path: string;
     reason: string;
 }
 export interface HookWiringReport {
-    /** Whether this agent's hook config format is understood by the inspector. */
     supported: boolean;
-    /** Absolute path of the settings file inspected (when supported). */
     settingsPath?: string;
-    /** Number of hooks the manifest says should be wired for this version. */
     expected?: number;
-    /** Native hook config does not exist — nothing declared can be wired. */
     settingsMissing?: boolean;
-    /** Native hook config cannot be parsed — wiring can't be verified. */
     settingsUnparseable?: boolean;
-    /** Hooks whose file is present/resolvable but that are NOT referenced in the
-     *  native event group/entry should carry them in. */
     unwired: HookWiringIssue[];
-    /** Expected hooks that ARE referenced in native config (expected − unwired).
-     *  Empty whenever wiring cannot be verified (unsupported family, missing or
-     *  unparseable settings). */
     wired: HookWiringIssue[];
-    /** Generated agents-managed wrappers that are absent or unusable. This is
-     * independent of whether the native config format itself is understood. */
     runtimeBroken: HookRuntimeIssue[];
 }
-/** Inspect managed generated hook wrappers without executing user hook code. */
 export declare function inspectBrokenManagedHookRuntimeArtifacts(filter?: {
     agent?: AgentId;
     version?: string;
 }, platform?: NodeJS.Platform): BrokenManagedHookRuntimeArtifact[];
-/** Outcome of one generation attempt for a unique shim path. */
 export interface HookRuntimeRepairAttempt {
     name: string;
     path: string;
     reasonBefore: string;
-    /** True when generateHookShim ran for this path in this pass. */
     attempted: boolean;
     repaired: boolean;
-    /** Stable failure text when not repaired after an attempt (or dry-run skip). */
     reason?: string;
 }
-/**
- * Result of one bounded repair pass over agents-managed generated hook shims.
- * Shared by self-heal and agents sync; additive types for the doctor track.
- */
 export interface HookRuntimeRepairReport {
-    /** Broken artifacts found before any write (inspect-only snapshot). */
     brokenBefore: BrokenManagedHookRuntimeArtifact[];
-    /** Unique shim paths considered for generation in this pass. */
     attemptedPaths: string[];
     attempts: HookRuntimeRepairAttempt[];
-    /** Human-readable lines for CheckResult.fixed (includes dry-run would-fix). */
     fixed: string[];
-    /** Human-readable lines for CheckResult.needsAttention — stable wording. */
     needsAttention: string[];
 }
 interface RepairManagedHookRuntimeOptions {
-    /** Detect only — never write. Default false. */
     dryRun?: boolean;
     filter?: {
         agent?: AgentId;
@@ -184,33 +95,7 @@ interface RepairManagedHookRuntimeOptions {
     };
     platform?: NodeJS.Platform;
 }
-/**
- * Bounded repair of all broken agents-managed generated hook shims.
- *
- * - Inspect first (read-only, no hook execution).
- * - One generation attempt per unique shim path per call (no retry, no timer).
- * - Canonical owner per shared path: global default, else newest non-isolated.
- * - Post-repair reinspection; unresolved findings become stable needsAttention.
- * - Never recurses into resource sync / registerHooksToSettings.
- *
- * This is the shared routine used by the self-heal `hook-runtime` check and
- * exported for the doctor track.
- */
 export declare function repairManagedHookRuntimeArtifacts(opts?: RepairManagedHookRuntimeOptions): HookRuntimeRepairReport;
-/**
- * Verify that every hook the manifest says should be wired is actually
- * referenced in that version's harness-native config, not merely present as a
- * file on disk.
- *
- * `agents doctor` compares hook FILES against source (see diffHooks in
- * doctor-diff.ts) but never checks the wiring, so a hook whose script is
- * byte-identical to source yet missing from settings.json's PreToolUse/Stop/…
- * array reads as "ok" while it never fires. This closes that blind spot.
- *
- * Read-only by construction: it mirrors registerHooksForClaude's command
- * resolution WITHOUT the shim-generation / chmod side effects that
- * resolveHookCommand performs, so it never mutates the version home.
- */
 export declare function checkVersionHookWiring(agent: AgentId, version: string): HookWiringReport;
 interface VersionHookDiff {
     agent: AgentId;
@@ -220,22 +105,11 @@ interface VersionHookDiff {
     matched: string[];
     orphans: string[];
 }
-/**
- * Compare a version home's hooks against central. Returns the reconciliation diff.
- */
 export declare function diffVersionHooks(agent: AgentId, version: string): VersionHookDiff;
-/**
- * Remove a single hook (script + data file) from a specific version home.
- * Soft-deletes to ~/.agents/.trash/hooks/.
- */
 export declare function removeHookFromVersion(agent: AgentId, version: string, hookName: string): {
     success: boolean;
     error?: string;
 };
-/**
- * Iterate all (agent, version) pairs that support hooks and are installed,
- * optionally scoped to a single agent/version.
- */
 export declare function iterHooksCapableVersions(filter?: {
     agent?: AgentId;
     version?: string;
@@ -247,114 +121,25 @@ export declare function removeHook(name: string, agents: AgentId[]): Promise<{
     removed: string[];
     errors: string[];
 }>;
-/**
- * Get detailed info about a hook from central storage.
- */
 export declare function getHookInfo(name: string): {
     name: string;
     path: string;
     content: string;
 } | null;
 export declare function discoverHooksFromRepo(repoPath: string): string[];
-/**
- * Install hooks to central ~/.agents/hooks/ directory.
- * Shims will symlink this to per-agent directories for synced agents.
- */
 export declare function installHooksCentrally(source: string): Promise<{
     installed: string[];
     errors: string[];
 }>;
-/**
- * List hooks from user (~/.agents/hooks/) and system (~/.agents/.system/hooks/) dirs.
- * User dir takes priority; deduplication preserves first occurrence.
- */
 export declare function listCentralHooks(): HookEntry[];
-/**
- * Normalize a hook `timeout` from agents.yaml into a whole number of seconds.
- *
- * A bare number stays seconds (`timeout: 30` → 30) for backward compatibility.
- * A Go-style duration string is parsed into seconds: `5s`, `2m`, `1h30m`,
- * `90s`, `1h`. Suffixed durations longer than 24 hours are rejected as likely
- * typos, while bare seconds stay uncapped for backward compatibility. This
- * intentionally does NOT reuse {@link parseTimeout} from routines.ts — that one
- * returns milliseconds, has no seconds (`s`) unit, and floors at one minute,
- * none of which fit hook timeouts (typically 5–600s).
- *
- * Returns the seconds value, or `null` when the input is not a positive number,
- * is not parseable, or is a suffixed duration longer than 24 hours — the caller
- * decides how to surface that.
- */
 export declare function normalizeHookTimeoutSeconds(value: unknown): number | null;
-/**
- * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
- * (npm-shipped defaults) and user hooks from the `hooks:` section of
- * ~/.agents/agents.yaml. Merges with user-wins-on-key-collision precedence.
- * A user entry with `enabled: false` disables the system-shipped hook of
- * the same name without forking the system file.
- *
- * Hooks marked `enabled: false` are dropped from the returned map. A hook
- * `timeout` written as a duration string (`5s`, `2m`) is normalized to a
- * seconds number here, so every downstream serializer keeps reading a number.
- */
 export declare function parseHookManifest(opts?: {
     warn?: boolean;
 }): Record<string, ManifestHook>;
 export declare function selectHookManifest(manifest: Record<string, ManifestHook>, selected: string[]): Record<string, ManifestHook>;
-/**
- * Hook files present in a version home but absent from every configured
- * SOURCE — genuine orphans left behind by a removed/renamed source hook.
- *
- * The definition is deliberately source-based, not manifest-based (PHNX-2693).
- * Sync copies EVERY source hook file into a version home — registered hooks AND
- * the helper / test / benchmark scripts that sit alongside them — but only the
- * registered ones appear in `parseHookManifest`. Diffing installed names against
- * the manifest therefore flagged every source-present-but-unregistered file
- * (e.g. `permission-handler`, `verify-work-state`, `*_test`, `benchmark_*`) as
- * an orphan, so `agents prune cleanup` offered to trash ~1000 in-use files. An
- * installed hook is only truly orphaned when NO configured source still carries
- * a file of that name — which is exactly what the `prune`/`doctor` help already
- * promised ("present in a version home but missing from every configured
- * source").
- *
- * Pure on purpose (no disk reads) so it is trivially testable; callers pass the
- * installed hook names and the source hook script paths.
- */
 export declare function unmanagedHookNames(installedHookNames: string[], sourceHookScripts: string[]): string[];
-/**
- * The orphan hooks (see {@link unmanagedHookNames}) sitting in one version home:
- * installed hook files whose name matches no file in any configured source root.
- */
 export declare function listUnmanagedHooksInVersionHome(agent: AgentId, version: string): string[];
-/**
- * Compute the trust hash Codex expects for a single command hook handler, so
- * agents-cli can pre-trust the hooks it registers. Without a matching
- * trusted_hash in [hooks.state], Codex classifies the hook Untrusted and
- * silently drops it in non-interactive (`codex exec`) mode where there is no
- * TUI prompt to approve it.
- *
- * Mirrors command_hook_hash() in codex-rs/hooks/src/engine/discovery.rs +
- * version_for_toml() in codex-rs/config/src/fingerprint.rs:
- *   sha256( canonicalJson( NormalizedHookIdentity ) ) prefixed with "sha256:".
- *
- * The identity passes through TOML on the Codex side, which drops None fields
- * (commandWindows, statusMessage, and matcher when absent). `async` is always
- * false (async hooks are not yet supported) and is always present. `timeout`
- * is normalized to >= 1 (Codex: unwrap_or(600).max(1)).
- */
 export declare function computeCodexHookTrustHash(eventKeyLabel: string, command: string, timeout: number, matcher: string | undefined): string;
-/**
- * Options that narrow `registerHooksToSettings`'s process-global side effects.
- *
- * `skipGlobalShimSweep` — do NOT run {@link sweepOrphanShims}. The sweep deletes
- * every `.sh` in the ONE process-global shim dir (`getHookShimsDir()`,
- * `~/.agents/.cache/shims/hooks/`) whose name is absent from the manifest it is
- * handed. That is correct for a normal install/sync (the manifest is the
- * operator's complete hook set), but catastrophic when the materializer registers
- * a portable PACKAGE's hooks into an isolated output home: that manifest carries
- * only the package's hooks, so the sweep would wipe the operator's unrelated
- * global shims. The materializer sets this so materialization stays isolated
- * (PHNX-3838); every normal caller leaves it unset and keeps the sweep.
- */
 interface RegisterHooksOptions {
     skipGlobalShimSweep?: boolean;
 }
@@ -362,50 +147,12 @@ export declare function registerHooksToSettings(agentId: AgentId, versionHome: s
     registered: string[];
     errors: string[];
 };
-/**
- * The concrete config file(s) `registerHooksToSettings` writes for `agentId` in
- * `home` — the settings/registrar leaves, NOT the per-hook script copies. A
- * caller materializing into an UNTRUSTED home (the portable-agent materializer)
- * uses this to verify none of those leaves is a preplanted symlink before the
- * registrar follows it and overwrites a file outside the home.
- *
- * This MUST mirror the `registerHooksToSettings` dispatch above — each arm's
- * write target is reproduced here, so a new registrar branch adds its leaf here
- * too. It intentionally returns only the primary settings/registrar file(s); the
- * per-event/script files a registrar also writes live under the hooks dir the
- * caller already guards. An agent with no hooks registrar returns `[]`.
- */
 export declare function hookRegistrationTargets(agentId: AgentId, home: string): string[];
-/**
- * Prune every Claude-family (`settings.json`) hook entry whose command lives
- * under a removed version's home
- * (`~/.agents/.history/versions/<agent>/<removedVersion>/home/…`).
- *
- * `agents remove <agent>@<version>` soft-deletes the version's files but leaves
- * the hook entries other version homes registered against it — dead hooks that
- * error on every tool call ("No such file or directory") until the next sync.
- * This clears them from a remaining version's settings immediately. Only the
- * removed version's entries are touched; the current version's entries, system
- * hooks, and the user's own custom hooks are left intact. Returns the number of
- * entries removed.
- */
 export declare function pruneVersionHomeHookEntriesFromSettings(settingsPath: string, agent: AgentId, removedVersion: string): number;
 interface InstallSessionTrackerHookResult {
     installed: boolean;
     error?: string;
 }
-/**
- * Install the shared SessionStart state-writer hook (`packages/session-tracker`)
- * into the harness's native config. Gated by `supports(agent, 'hooks', version)`;
- * unsupported agents return `installed: false` with a reason instead of throwing.
- *
- * This is the bridge that makes bare `claude` / `codex` / `kimi` launches write
- * `~/.agents/.cache/terminals/sessions/<pid>.json`, not just `agents run` launches.
- */
 export declare function installSessionTrackerHook(agent: AgentId, version?: string, home?: string): Promise<InstallSessionTrackerHookResult>;
-/**
- * Synchronous variant for callers that cannot be made async (e.g.
- * `syncResourcesToVersion`). Best-effort: failures are returned, not thrown.
- */
 export declare function installSessionTrackerHookSync(agent: AgentId, version?: string, home?: string): InstallSessionTrackerHookResult;
 export {};