agent-relay-server 0.122.1 → 0.123.0

package/runner/src/launch-assembly.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from "node:fs";
 import { resolve, join } from "node:path";
-import type { AgentProfile, AgentProfileBase, ProvisioningMcpServer, SpawnProvider } from "agent-relay-sdk";
+import type { AgentProfile, AgentProfileBase, ProvisioningHookSet, ProvisioningMcpServer, SpawnProvider } from "agent-relay-sdk";
 import { shellQuote } from "agent-relay-sdk/shell-utils";
 import {
   profileAllowsRelayFeature,
@@ -17,17 +17,21 @@ import {
   providerProvisioningHomePathFor,
 } from "./profile-home";
 import { getManifest } from "agent-relay-providers";
+import { codexHooksSupported } from "./codex-version";
 import { claudeLaunchPromptGateSettings } from "./claude-prompt-gates";
 import {
   materializeResolvedAssets,
+  renderProvisionedHookSet,
   resolveClaudeProjectSkills,
   resolveClaudeHostSkills,
   resolveProjectClaudeSettings,
   resolveClaudeProvisionedPlugins,
   resolveClaudeProvisionedSkills,
   resolveCodexProvisionedSkills,
+  resolveProvisionedHooks,
   resolveProjectMcpServers,
   profileProvisioning,
+  writeCodexHooksJson,
 } from "./provisioning";
 import {
   claudeMcpLaunchArgs,
@@ -134,6 +138,20 @@ export interface AssembledLaunch {
   hostSkills: AssembledAsset[];
   /** Project `.claude/settings.json` sanitized and injected for this Claude launch (#669). */
   projectSettings: { applied: boolean; keys: string[]; ignoredKeys: string[]; file?: string };
+  /** Relay-provisioned hooks materialized for this launch. Empty when hooks were resolved
+   *  but could not be delivered — see `hooksSuppressed` (the anti-lie invariant, #1096). */
+  hooks: AssembledAsset[];
+  /** #1096 review — set when this launch RESOLVED provisioned hooks (incl. a baseline safety
+   *  guard) that could NOT be delivered: caller `--settings` was unmergeable (Claude), a
+   *  host-base Codex agent has no managed CODEX_HOME, or the installed Codex is too old to
+   *  consume hooks.json. Drives a LOUD projection warning so a baseline guard is never
+   *  SILENTLY absent while the report says "applied". */
+  hooksSuppressed?: { reason: string; names: string[] };
+  /** #1096 review — Claude only: true when the caller's own `--settings` was folded into the
+   *  relay-emitted `--settings` (relay hooks/projectSettings/statusLine merged in). The adapter
+   *  must then STRIP the caller's `--settings` from the provider args so exactly one reaches the
+   *  launch. False when relay emitted its own settings standalone or added none. */
+  callerSettingsConsumed: boolean;
   /** Relay-provisioned plugins (Claude --plugin-dir). Empty for Codex (no plugin surface). */
   plugins: AssembledAsset[];
   /** Host/global provider plugin dirs explicitly inherited without enabling host MCP. */
@@ -196,17 +214,115 @@ function claudeStatusLineProbePath(): string {
   return resolve(import.meta.dir, "../plugins/claude/claude-statusline-probe.cjs");
 }
 
+export interface ClaudeSettingsResolution {
+  args: string[];
+  /** The caller's own --settings was merged in and must be stripped from the provider args. */
+  callerSettingsConsumed: boolean;
+  /** Provisioned hook names that could NOT be delivered (caller --settings unmergeable). */
+  suppressedHookNames: string[];
+}
+
+// #1096 review, finding 1 — when the caller (spawn providerArgs / provider defaultArgs) already
+// carries `--settings`, DO NOT silently drop relay's settings (which used to skip the baseline
+// safety hooks + projectSettings + statusLine while projection still claimed "applied"). Merge
+// relay's settings into the caller's INLINE JSON so the guard survives, and signal the adapter to
+// strip the caller's now-redundant `--settings`. If the caller's `--settings` is a FILE PATH or
+// malformed JSON (unmergeable), relay's provisioned hooks are reported as SUPPRESSED (a loud
+// projection warning) rather than a silent absence with an "applied" lie.
 function claudeSettingsArgs(
   projectSettings: Record<string, unknown>,
+  provisionedHooks: ProvisioningHookSet,
+  hookNames: string[],
   includeStatusLine: boolean,
   ...argLists: string[][]
-): string[] {
-  if (argLists.some(hasSettingsArg)) return [];
-  const settings = {
+): ClaudeSettingsResolution {
+  const relaySettings: Record<string, unknown> = {
     ...projectSettings,
+    ...(Object.keys(provisionedHooks).length ? { hooks: provisionedHooks } : {}),
     ...(includeStatusLine ? relayStatusLineSettings() : {}),
   };
-  return Object.keys(settings).length ? ["--settings", JSON.stringify(settings)] : [];
+  const hasProvisionedHooks = Object.keys(provisionedHooks).length > 0;
+  const caller = extractCallerSettings(argLists);
+  if (!caller) {
+    return {
+      args: Object.keys(relaySettings).length ? ["--settings", JSON.stringify(relaySettings)] : [],
+      callerSettingsConsumed: false,
+      suppressedHookNames: [],
+    };
+  }
+  if (caller.settings) {
+    const merged = mergeClaudeSettings(caller.settings, relaySettings);
+    return { args: ["--settings", JSON.stringify(merged)], callerSettingsConsumed: true, suppressedHookNames: [] };
+  }
+  // Unmergeable caller --settings (a file path or malformed JSON): relay cannot fold its
+  // settings in without clobbering the caller's file, so the provisioned hooks don't reach
+  // the launch. Report them suppressed (loud) — never claim "applied".
+  return { args: [], callerSettingsConsumed: false, suppressedHookNames: hasProvisionedHooks ? hookNames : [] };
+}
+
+// The caller's `--settings` value, parsed as inline JSON when possible. `settings` is null for a
+// file-path / malformed value (an inline object is required to merge relay settings in).
+function extractCallerSettings(argLists: string[][]): { settings: Record<string, unknown> | null } | null {
+  for (const list of argLists) {
+    for (let i = 0; i < list.length; i += 1) {
+      const arg = list[i];
+      if (arg === "--settings") return { settings: parseInlineSettings(list[i + 1]) };
+      if (arg?.startsWith("--settings=")) return { settings: parseInlineSettings(arg.slice("--settings=".length)) };
+    }
+  }
+  return null;
+}
+
+function parseInlineSettings(value: string | undefined): Record<string, unknown> | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{")) return null; // a settings file path, not inline JSON
+  try {
+    const parsed = JSON.parse(trimmed);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Merge relay settings into the caller's inline settings. The safety-critical `hooks` map is
+// UNIONED per event (caller entries first, relay's baseline guard appended) so both fire; every
+// other relay key is fill-if-absent (the caller's explicit value wins), preserving the historical
+// "caller --settings wins" spirit for non-safety settings.
+function mergeClaudeSettings(caller: Record<string, unknown>, relay: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...caller };
+  for (const [key, value] of Object.entries(relay)) {
+    if (key === "hooks") out.hooks = mergeHookSets(caller.hooks, value);
+    else if (!(key in out)) out[key] = value;
+  }
+  return out;
+}
+
+function mergeHookSets(caller: unknown, relay: unknown): ProvisioningHookSet {
+  const base: ProvisioningHookSet = isHookSet(caller) ? { ...caller } : {};
+  if (!isHookSet(relay)) return base;
+  for (const [event, entries] of Object.entries(relay)) {
+    base[event] = [...(base[event] ?? []), ...entries];
+  }
+  return base;
+}
+
+function isHookSet(value: unknown): value is ProvisioningHookSet {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+// Strip every `--settings <json>` / `--settings=<json>` occurrence from a provider arg list. The
+// adapter applies this to the caller args once the assembler has folded them into its own merged
+// `--settings` (callerSettingsConsumed), so exactly one `--settings` reaches the launch (#1096).
+export function stripSettingsArgs(args: string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--settings") { i += 1; continue; }
+    if (arg?.startsWith("--settings=")) continue;
+    if (arg !== undefined) result.push(arg);
+  }
+  return result;
 }
 
 // ── Instruction disposition (the vanilla floor's effect on the host instruction cascade) ──
@@ -255,6 +371,24 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
     : [];
   const projectSettings = resolveProjectClaudeSettings(config);
   const provisionedPlugins = assetHome ? resolveClaudeProvisionedPlugins(assetHome, config) : [];
+  const hookHome = configHome ?? assetHome;
+  const provisionedHooks = hookHome ? resolveProvisionedHooks(hookHome, config) : [];
+  const provisionedHookSet = renderProvisionedHookSet(provisionedHooks);
+  const settings = claudeSettingsArgs(
+    projectSettings.settings,
+    provisionedHookSet,
+    provisionedHooks.map((h) => h.name),
+    statusLine,
+    hostDefaultArgs,
+    config.providerArgs,
+  );
+  // The anti-lie invariant (#1096): only report hooks as materialized when they actually reach
+  // the launch. If the caller's --settings suppressed them, empty the reported set and surface a
+  // loud suppression reason instead of an "applied" report.
+  const hooksSuppressed = settings.suppressedHookNames.length
+    ? { reason: "caller-provided --settings could not be merged (file path or malformed JSON); relay hooks were not injected", names: settings.suppressedHookNames }
+    : undefined;
+  const deliveredHooks = hooksSuppressed ? [] : provisionedHooks;
 
   // Plugin dirs (--plugin-dir loads explicitly, independent of --setting-sources):
   //   relay-bundled plugin → only when relay.plugins (carries the relay monitor +
@@ -332,7 +466,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
       hostServers: hostMcp,
       strict: strictMcp,
     }),
-    ...claudeSettingsArgs(projectSettings.settings, statusLine, hostDefaultArgs, config.providerArgs),
+    ...settings.args,
     ...(config.systemPromptAppend ? ["--append-system-prompt", config.systemPromptAppend] : []),
   ];
 
@@ -355,6 +489,9 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
       ignoredKeys: projectSettings.ignoredKeys,
       ...(projectSettings.file ? { file: projectSettings.file } : {}),
     },
+    hooks: deliveredHooks.map((h) => ({ name: h.name, dir: h.dir })),
+    ...(hooksSuppressed ? { hooksSuppressed } : {}),
+    callerSettingsConsumed: settings.callerSettingsConsumed,
     plugins: provisionedPlugins.map((p) => ({ name: p.name, dir: p.dir })),
     hostPluginDirs,
     mcp: {
@@ -367,7 +504,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
   };
 }
 
-function assembleCodex(config: RunnerSpawnConfig, _providerConfig: ProviderConfig): AssembledLaunch {
+function assembleCodex(config: RunnerSpawnConfig, providerConfig: ProviderConfig): AssembledLaunch {
   const configHome = providerHomePathFor("codex", config);
   const assetHome = providerProvisioningHomePathFor("codex", config);
   const vanilla = profileIsVanillaBase(config);
@@ -375,6 +512,22 @@ function assembleCodex(config: RunnerSpawnConfig, _providerConfig: ProviderConfi
   const relayEndpoint = profileAllowsRelayFeature(config, "mcp");
 
   const provisionedSkills = assetHome ? resolveCodexProvisionedSkills(assetHome, config) : [];
+  // #1096 review, findings 3 & 4 — Codex delivers hooks via CODEX_HOME/hooks.json, so a launch
+  // can only carry them when it has an isolated CODEX_HOME (host-base profiles reuse the real
+  // ~/.codex, which relay must not clobber) AND the installed Codex is new enough to consume the
+  // file. Resolve the profile's hook definitions to decide whether there was anything to deliver;
+  // any absence is reported LOUDLY (hooksSuppressed) instead of a silent "not-applicable".
+  const resolvedHookDefs = profileProvisioning(config).hooks ?? [];
+  const hooksSupported = codexHooksSupported(providerConfig.command);
+  const provisionedHooks = configHome && hooksSupported ? resolveProvisionedHooks(configHome, config) : [];
+  const hooksSuppressed = resolvedHookDefs.length && provisionedHooks.length === 0
+    ? {
+      reason: !configHome
+        ? "Codex host-base profile has no managed CODEX_HOME; relay will not overwrite the host ~/.codex/hooks.json, so the baseline guard cannot be delivered"
+        : "installed Codex is older than 0.124 and ignores CODEX_HOME/hooks.json (set AGENT_RELAY_CODEX_VERSION to override the probe)",
+      names: resolvedHookDefs.map((h) => h.name),
+    }
+    : undefined;
   const bundledSkillDirs = !config.agentProfile && relaySkills ? bundledCodexSkillDirs() : [];
   const skillDirs = [...bundledSkillDirs, ...provisionedSkills.map((s) => s.dir)];
 
@@ -429,6 +582,9 @@ function assembleCodex(config: RunnerSpawnConfig, _providerConfig: ProviderConfi
     hostSkills: [],
     projectSkills: [],
     projectSettings: { applied: false, keys: [], ignoredKeys: [] },
+    hooks: provisionedHooks.map((h) => ({ name: h.name, dir: h.dir })),
+    ...(hooksSuppressed ? { hooksSuppressed } : {}),
+    callerSettingsConsumed: false,
     plugins: [],
     hostPluginDirs: [],
     mcp: {
@@ -472,13 +628,23 @@ function materializeClaudeAssets(config: RunnerSpawnConfig): void {
     const hostSkills = resolveClaudeHostSkills(configHome, config, new Set(skills.map((s) => s.name)));
     materializeResolvedAssets(hostSkills);
     materializeResolvedAssets(resolveClaudeProjectSkills(configHome, config, new Set([...skills, ...hostSkills].map((s) => s.name))));
+    materializeResolvedAssets(resolveProvisionedHooks(configHome, config));
   }
   if (assetHome) materializeResolvedAssets(resolveClaudeProvisionedPlugins(assetHome, config));
+  if (!configHome && assetHome) materializeResolvedAssets(resolveProvisionedHooks(assetHome, config));
 }
 
 function materializeCodexAssets(config: RunnerSpawnConfig): void {
   const assetHome = providerProvisioningHomePathFor("codex", config);
   if (assetHome) materializeResolvedAssets(resolveCodexProvisionedSkills(assetHome, config));
+  const configHome = providerHomePathFor("codex", config);
+  // #1096 review, finding 4 — don't write CODEX_HOME/hooks.json for a Codex that would ignore it;
+  // keep disk == report (the assembler reports these hooks suppressed for such a launch).
+  if (configHome && codexHooksSupported(config.providerConfig.command)) {
+    const hooks = resolveProvisionedHooks(configHome, config);
+    materializeResolvedAssets(hooks);
+    writeCodexHooksJson(configHome, renderProvisionedHookSet(hooks));
+  }
 }
 
 /**
@@ -494,8 +660,8 @@ export function assembleLaunch(provider: SpawnProvider, config: RunnerSpawnConfi
 }
 
 /**
- * Write the provisioned assets the assembly describes (Claude skills + plugins, Codex
- * skills). Driven by the SAME resolvers `assembleLaunch` uses, so disk == launch ==
+ * Write the provisioned assets the assembly describes (skills/plugins/hooks and Codex
+ * hooks.json). Driven by the SAME resolvers `assembleLaunch` uses, so disk == launch ==
  * report. Idempotent; the isolated home must already exist (prepare*ProfileHome). No-op
  * for a host-base profile.
  */

package/runner/src/profile-projection.ts

@@ -33,6 +33,7 @@ export function agentProfileProjectionReport(input: AgentProfileProjectionInput)
   add(hooksEntry(assembled));
   add(provisioningSkillsEntry(assembled));
   add(provisioningPluginsEntry(assembled));
+  add(provisioningHooksEntry(assembled));
   add(hostSkillsEntry(assembled));
   add(hostPluginsEntry(assembled));
   add(provisioningMcpEntry(assembled));
@@ -168,6 +169,24 @@ function provisioningPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEnt
   return applied("provisioning.plugins", `${count}`, `Relay-provisioned plugins passed to ${label} via the plugin dir mechanism${names}.`);
 }
 
+function provisioningHooksEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  // #1096 review — the anti-lie invariant: hooks that RESOLVED but did NOT reach the launch
+  // (baseline safety guard included) are reported LOUDLY as a warning, never "applied" and never
+  // a benign "not-applicable". `hooksSuppressed` is set only when there were hooks to deliver.
+  if (a.hooksSuppressed?.names.length) {
+    return partial(
+      "provisioning.hooks",
+      "suppressed",
+      `Relay-provisioned hooks were NOT applied (${a.hooksSuppressed.names.join(", ")}): ${a.hooksSuppressed.reason}. A baseline safety guard is absent for this launch.`,
+    );
+  }
+  const count = a.hooks.length;
+  if (!count) return notApplicable("provisioning.hooks", "none", "No relay-provisioned hooks materialized for this launch.");
+  const names = ` (${a.hooks.map((h) => h.name).join(", ")})`;
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  return applied("provisioning.hooks", `${count}`, `Relay-provisioned hooks materialized for ${label} from the managed provider config home${names}.`);
+}
+
 function hostSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
   const optedIn = Boolean(a.profile?.hostAssets?.skills);
   if (!optedIn) return notApplicable("hostAssets.skills", "off", "Host/global skill inheritance is off for this resolved profile.");

package/runner/src/provisioning.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
-import type { ProvisioningAssetFile, ProvisioningMcpServer, ResolvedProvisioning } from "agent-relay-sdk";
+import type { ProvisioningAssetFile, ProvisioningHookSet, ProvisioningMcpServer, ResolvedProvisioning } from "agent-relay-sdk";
 import type { RunnerSpawnConfig } from "./adapter";
 import { profileAllowsHostAssets, providerSourceHome } from "./profile-home";
 
@@ -17,12 +17,12 @@ import { profileAllowsHostAssets, providerSourceHome } from "./profile-home";
 // materialize* writers consume the same resolved entries, so what's written can never
 // drift from what's reported either. One resolution, three consumers.
 
-const EMPTY: ResolvedProvisioning = { skills: [], plugins: [], mcpServers: {} };
+const EMPTY: ResolvedProvisioning = { skills: [], plugins: [], hooks: [], mcpServers: {} };
 
 export function profileProvisioning(config: Pick<RunnerSpawnConfig, "agentProfile">): ResolvedProvisioning {
   const p = config.agentProfile?.provisioning;
   if (!p) return EMPTY;
-  return { skills: p.skills ?? [], plugins: p.plugins ?? [], mcpServers: p.mcpServers ?? {}, ...(p.skipped?.length ? { skipped: p.skipped } : {}) };
+  return { skills: p.skills ?? [], plugins: p.plugins ?? [], hooks: p.hooks ?? [], mcpServers: p.mcpServers ?? {}, ...(p.skipped?.length ? { skipped: p.skipped } : {}) };
 }
 
 // The `mcpServers` keys a Claude `.mcp.json` entry may carry; coerced into the
@@ -194,6 +194,10 @@ export interface ResolvedAsset {
   source: ResolvedAssetSource;
 }
 
+export interface ResolvedHookAsset extends ResolvedAsset {
+  hooks: ProvisioningHookSet;
+}
+
 function assetDirName(name: string): string {
   return sanitizeFsName(name, { replacement: "-", collapse: false, maxLen: 120, fallback: "asset" });
 }
@@ -211,9 +215,11 @@ function hasRootSkillManifest(files: ProvisioningAssetFile[]): boolean {
 // registry entry. Shared by every files-source materialization.
 function writeInlineFiles(dir: string, files: ProvisioningAssetFile[]): void {
   mkdirSync(dir, { recursive: true });
+  const root = resolve(dir);
   for (const file of files) {
     const dest = resolve(dir, file.path);
-    if (!dest.startsWith(resolve(dir))) continue;
+    const rel = relative(root, dest);
+    if (rel.startsWith("..") || isAbsolute(rel)) continue;
     mkdirSync(dirname(dest), { recursive: true });
     writeFileSync(dest, file.content, { mode: 0o600 });
   }
@@ -303,6 +309,54 @@ export function resolveCodexProvisionedSkills(codexHome: string, config: RunnerS
   return resolved;
 }
 
+export function resolveProvisionedHooks(home: string, config: RunnerSpawnConfig): ResolvedHookAsset[] {
+  const { hooks } = profileProvisioning(config);
+  const parent = join(home, "relay-provisioned-hooks");
+  const resolved: ResolvedHookAsset[] = [];
+  for (const hook of hooks ?? []) {
+    const dir = join(parent, assetDirName(hook.name));
+    if (hook.files?.length) {
+      resolved.push({ name: hook.name, dir, hooks: hook.hooks, source: { kind: "files", files: hook.files } });
+      continue;
+    }
+    if (hook.dir) {
+      const source = resolveExistingDir(hook.dir, config.cwd);
+      if (source) resolved.push({ name: hook.name, dir: source, hooks: hook.hooks, source: { kind: "inPlace" } });
+      continue;
+    }
+    resolved.push({ name: hook.name, dir, hooks: hook.hooks, source: { kind: "inPlace" } });
+  }
+  return resolved;
+}
+
+export function renderProvisionedHookSet(hooks: ResolvedHookAsset[]): ProvisioningHookSet {
+  const out: ProvisioningHookSet = {};
+  for (const hook of hooks) {
+    for (const [event, entries] of Object.entries(hook.hooks)) {
+      out[event] = [
+        ...(out[event] ?? []),
+        ...entries.map((entry) => ({
+          ...entry,
+          hooks: entry.hooks.map((command) => ({
+            ...command,
+            command: command.command.replaceAll("${HOOK_DIR}", hook.dir),
+          })),
+        })),
+      ];
+    }
+  }
+  return out;
+}
+
+export function writeCodexHooksJson(codexHome: string, hooks: ProvisioningHookSet): void {
+  mkdirSync(codexHome, { recursive: true });
+  if (!Object.keys(hooks).length) {
+    rmSync(join(codexHome, "hooks.json"), { force: true });
+    return;
+  }
+  writeFileSync(join(codexHome, "hooks.json"), JSON.stringify({ hooks }, null, 2), { mode: 0o600 });
+}
+
 // Write the resolved assets to disk; returns the dirs that materialized successfully,
 // in resolution order. Idempotent — safe to re-run against an existing home.
 export function materializeResolvedAssets(assets: ResolvedAsset[]): string[] {

package/runner/src/relay-injection-events.ts

@@ -36,6 +36,7 @@ function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInj
   if (!isSpawnProvider(input.provider)) return events;
   const assembled = assembleLaunch(input.provider, input.config, input.providerConfig);
   const toolCount = assembled.skills.length + assembled.plugins.length + assembled.mcp.servers.length
+    + assembled.hooks.length
     + assembled.projectSkills.length
     + assembled.mcp.projectServers.length
     + (assembled.projectSettings.applied ? 1 : 0)
@@ -52,6 +53,7 @@ function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInj
     assembled.skills.length ? `${assembled.skills.length} skill${assembled.skills.length === 1 ? "" : "s"}` : "",
     assembled.projectSkills.length ? `${assembled.projectSkills.length} project skill${assembled.projectSkills.length === 1 ? "" : "s"}` : "",
     assembled.projectSettings.applied ? "project settings" : "",
+    assembled.hooks.length ? `${assembled.hooks.length} hook${assembled.hooks.length === 1 ? "" : "s"}` : "",
     assembled.plugins.length ? `${assembled.plugins.length} plugin${assembled.plugins.length === 1 ? "" : "s"}` : "",
     assembled.mcp.servers.length ? `${assembled.mcp.servers.length} MCP server${assembled.mcp.servers.length === 1 ? "" : "s"}` : "",
     assembled.mcp.projectServers.length ? `${assembled.mcp.projectServers.length} project MCP server${assembled.mcp.projectServers.length === 1 ? "" : "s"}` : "",
@@ -73,6 +75,7 @@ function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInj
         skills: assembled.skills,
         projectSkills: assembled.projectSkills,
         projectSettings: assembled.projectSettings,
+        hooks: assembled.hooks,
         plugins: assembled.plugins,
         mcp: assembled.mcp,
       },

package/runner/src/runner-helpers.ts

@@ -356,7 +356,7 @@ export function appliedAgentProfileMetadata(
     skills: profile.skills.filter((item) => item.enabled).length,
     plugins: profile.plugins.filter((item) => item.enabled).length,
     mcp: { mode: profile.mcp.mode },
-    hooks: { mode: profile.hooks.mode },
+    hooks: { mode: profile.hooks.mode, refs: profile.hooks.refs?.filter((item) => item.enabled).length ?? 0 },
     permissions: profile.permissions,
     projection,
   };

package/runner/src/version.ts

@@ -38,6 +38,7 @@ export function runtimeMetadata(provider?: string) {
       ...RUNTIME_CAPABILITIES,
       ...(manifest?.provisioning?.bundledPlugin ? { bundledPlugin: true } : {}),
       ...(manifest?.provisioning?.bundledSkills ? { bundledSkills: true } : {}),
+      ...(manifest?.provisioning?.bundledHooks?.length ? { bundledHooks: true } : {}),
     },
   };
 }

package/src/config-store.ts

@@ -335,6 +335,7 @@ function agentProfileDefaults(input: Pick<AgentProfile, "name" | "base"> & Omit<
     },
     hooks: {
       mode: input.hooks?.mode ?? (isolated ? "none" : "host"),
+      ...(input.hooks?.refs?.length ? { refs: input.hooks.refs } : {}),
     },
     permissions: {
       mode: input.permissions?.mode,
@@ -419,6 +420,7 @@ function validateAgentProfile(key: string, value: unknown, opts: { allowBuiltIn?
     },
     hooks: {
       mode: hooks.mode === undefined ? defaults.hooks.mode : cleanEnum(hooks.mode, "hooks.mode", VALID_PROFILE_CATEGORY_MODES),
+      refs: cleanAgentProfileAssetArray(hooks.refs, "hooks.refs"),
     },
     permissions: {
       mode: permissions.mode === undefined || permissions.mode === null

package/src/db/provisioning-registry.ts

@@ -9,6 +9,7 @@ import { parseJson } from "../utils";
 import { errMessage, isRecord, SPAWN_PROVIDERS } from "agent-relay-sdk";
 import type {
   AgentProfileProvider,
+  HookAssetDefinition,
   McpAssetDefinition,
   PluginAssetDefinition,
   ProvisioningCapability,
@@ -26,7 +27,7 @@ import type {
 // the launch. #557 (per-profile assembly) is meant to be a thin unifier on top, so
 // this stays the single home for asset definition + resolution — not three modules.
 
-const PROVISIONING_ASSET_KINDS = ["skill", "mcp", "plugin"] as const;
+const PROVISIONING_ASSET_KINDS = ["skill", "mcp", "plugin", "hook"] as const;
 const PROVISIONING_PROVIDERS = [...SPAWN_PROVIDERS, "any"];
 const GITHUB_API = "https://api.github.com";
 const DEFAULT_MAX_FILE_BYTES = 256 * 1024;
@@ -213,6 +214,10 @@ function assertDefinition(kind: ProvisioningAssetKind, definition: ResolvedAsset
     const metadata = isRecord(def.metadata) ? def.metadata : {};
     if (isRecord(metadata.callmuxServer)) assertCallmuxServerPlaceholders(metadata.callmuxServer as ProvisioningMcpServer, def.name);
   }
+  if (kind === "hook") {
+    const def = definition as HookAssetDefinition;
+    if (!isRecord(def.hooks) || !Object.keys(def.hooks).length) throw new ValidationError("hook definition requires a hooks object");
+  }
   if ((kind === "skill" || kind === "plugin")) {
     const def = definition as SkillAssetDefinition | PluginAssetDefinition;
     if (!def.files?.length && !def.dir) throw new ValidationError(`${kind} definition requires files or dir`);
@@ -470,6 +475,24 @@ function mcpDefinitionFromFiles(name: string, files: VendoredFile[], mcpServerNa
   return { kind: "mcp", name, server: coerceMcpServer(parsed) };
 }
 
+function hookDefinitionFromFiles(name: string, files: Array<{ path: string; content: string }>): HookAssetDefinition {
+  const preferred = files.find((file) => file.path === "hooks.json")
+    ?? files.find((file) => file.path.endsWith("/hooks.json"))
+    ?? files.find((file) => file.path === `${name}.json`);
+  if (!preferred) throw new ValidationError("hook imports require hooks.json");
+  let parsed: Record<string, unknown>;
+  try {
+    const value = JSON.parse(preferred.content);
+    if (!isRecord(value)) throw new Error("not an object");
+    parsed = value;
+  } catch {
+    throw new ValidationError(`${preferred.path} must be valid JSON object`);
+  }
+  const hooks = isRecord(parsed.hooks) ? parsed.hooks : parsed;
+  if (!isRecord(hooks) || !Object.keys(hooks).length) throw new ValidationError("hook import requires a non-empty hooks object");
+  return { kind: "hook", name, hooks: hooks as HookAssetDefinition["hooks"], files: files.map(({ path, content }) => ({ path, content })) };
+}
+
 function definitionFromVendoredFiles(input: ImportProvisioningAssetFromGitHubInput, files: VendoredFile[], provider: AgentProfileProvider): ResolvedAssetDefinition {
   if (input.kind === "skill") {
     assertRootSkill(files);
@@ -479,6 +502,7 @@ function definitionFromVendoredFiles(input: ImportProvisioningAssetFromGitHubInp
     assertPlugin(files, provider);
     return { kind: "plugin", name: input.name, files: files.map(({ path, content }) => ({ path, content })) };
   }
+  if (input.kind === "hook") return hookDefinitionFromFiles(input.name, files);
   return mcpDefinitionFromFiles(input.name, files, input.mcpServerName);
 }
 
@@ -529,7 +553,7 @@ function updateBundledAssetMetadata(asset: ProvisioningAsset, root: string, file
 }
 
 function upsertBundledProvisioningAsset(input: {
-  kind: "skill" | "plugin";
+  kind: "skill" | "plugin" | "hook";
   name: string;
   provider: AgentProfileProvider;
   files: BundledFile[];
@@ -538,7 +562,10 @@ function upsertBundledProvisioningAsset(input: {
   description: string;
 }): void {
   if (!input.files.length) return;
-  const definition = { kind: input.kind, name: input.name, files: input.files.map(({ path, content }) => ({ path, content })) } as SkillAssetDefinition | PluginAssetDefinition;
+  const files = input.files.map(({ path, content }) => ({ path, content }));
+  const definition = input.kind === "hook"
+    ? hookDefinitionFromFiles(input.name, input.files)
+    : { kind: input.kind, name: input.name, files } as SkillAssetDefinition | PluginAssetDefinition;
   assertDefinition(input.kind, definition);
   const asset = upsertProvisioningAsset({ kind: input.kind, name: input.name, provider: input.provider, definition });
   updateBundledAssetMetadata(asset, input.root, input.files, input.title, input.description);
@@ -552,12 +579,16 @@ export function seedBundledProvisioningAssets(): void {
       const plugin = provisioning.bundledPlugin;
       upsertBundledProvisioningAsset({ kind: "plugin", name: plugin.ref, provider, root: plugin.dir, files: readBundledFiles(resolve(import.meta.dir, "../../", plugin.dir), { omitFiles: plugin.omitFiles, fileOverrides: plugin.fileOverrides }), title: plugin.title, description: plugin.description });
     }
-    if (!provisioning.bundledSkills) continue;
-    const skills = provisioning.bundledSkills;
-    const skillsDir = resolve(import.meta.dir, "../../", skills.dir);
-    for (const ref of bundledSkillRefs(skills)) {
-      const skillName = ref.slice(skills.refPrefix.length);
-      upsertBundledProvisioningAsset({ kind: "skill", name: ref, provider, root: posix.join(skills.dir, skillName), files: readBundledFiles(join(skillsDir, skillName)), title: `${skills.titlePrefix}${skillName}`, description: skills.description });
+    if (provisioning.bundledSkills) {
+      const skills = provisioning.bundledSkills;
+      const skillsDir = resolve(import.meta.dir, "../../", skills.dir);
+      for (const ref of bundledSkillRefs(skills)) {
+        const skillName = ref.slice(skills.refPrefix.length);
+        upsertBundledProvisioningAsset({ kind: "skill", name: ref, provider, root: posix.join(skills.dir, skillName), files: readBundledFiles(join(skillsDir, skillName)), title: `${skills.titlePrefix}${skillName}`, description: skills.description });
+      }
+    }
+    for (const hook of provisioning.bundledHooks ?? []) {
+      upsertBundledProvisioningAsset({ kind: "hook", name: hook.ref, provider, root: hook.dir, files: readBundledFiles(resolve(import.meta.dir, "../../", hook.dir), { omitFiles: hook.omitFiles, fileOverrides: hook.fileOverrides }), title: hook.title, description: hook.description });
     }
   }
 }