agent-relay-runner 0.122.1 → 0.123.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.122.1",
+  "version": "0.123.1",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,8 +20,8 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-providers": "0.104.3",
-    "agent-relay-sdk": "0.2.114",
+    "agent-relay-providers": "0.104.4",
+    "agent-relay-sdk": "0.2.115",
     "callmux": "0.23.0"
   },
   "devDependencies": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.122.1",
+  "version": "0.123.1",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapters/claude.ts

@@ -12,7 +12,7 @@ import type { LivenessSignal } from "agent-relay-sdk";
 import { collectClaudeSessionEvents } from "./claude-transcript";
 import type { SessionEvent } from "../session-insights";
 import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "../profile-home";
-import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs } from "../launch-assembly";
+import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs, stripSettingsArgs } from "../launch-assembly";
 import { claudeProviderMessageText } from "./claude-delivery";
 import { claudeProbeActivity, readManagedClaudeStatus, resolveClaudePid, type ClaudeProbeActivity } from "./claude-session-probe";
 import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "../claude-prompt-gates";
@@ -294,10 +294,13 @@ export class ClaudeAdapter implements ProviderAdapter {
     const providerArgs = config.headless
       ? claudeLaunchArgs(defaultArgs, config.providerArgs, config.approvalMode)
       : [...defaultArgs, ...config.providerArgs];
+    // #1096 — when the assembler merged the caller's own `--settings` into relay's (so the
+    // baseline hooks/projectSettings/statusLine survive), drop the caller's now-redundant
+    // `--settings` here so exactly ONE reaches the launch (relay's merged copy in assembled.args).
     const args = [
       ...rigPrefix,
       ...assembled.args,
-      ...providerArgs,
+      ...(assembled.callerSettingsConsumed ? stripSettingsArgs(providerArgs) : providerArgs),
     ];
     if (config.model) args.push("--model", config.model);
     // #352: seed the prompt as Claude's positional arg for ALL launches (headless included) —

package/src/codex-version.ts

@@ -0,0 +1,63 @@
+// #1096 review, finding 4 — Codex hooks (CODEX_HOME/hooks.json with Claude-compatible
+// event names) are only consumed by Codex >= 0.124. An older Codex silently ignores the
+// file, so writing it and reporting `provisioning.hooks: applied` would be a lie. This
+// module probes the installed Codex version once and answers whether hook delivery is
+// actually honored, so the assembler can emit a truthful projection (a LOUD warning when
+// the guard cannot fire) instead of a silent absence.
+//
+// TODO(#1096): a post-deploy LIVE check is still owed — assert that a Codex >= 0.124 actually
+// executes CODEX_HOME/hooks.json for these event names (Stop/PreToolUse/…), not just that the
+// version string clears the gate. The version probe is necessary but not sufficient.
+
+import { codexVersionOverrideFromEnv } from "./config";
+
+// Codex releases from this version on ship stable hooks with Claude-compatible events.
+const CODEX_HOOKS_MIN_VERSION = [0, 124, 0] as const;
+
+let cachedProbe: boolean | undefined;
+
+export function codexVersionSupportsHooks(version: string): boolean {
+  const parts = version.split(".").map((n) => parseInt(n, 10));
+  const major = Number.isFinite(parts[0]) ? parts[0]! : 0;
+  const minor = Number.isFinite(parts[1]) ? parts[1]! : 0;
+  const patch = Number.isFinite(parts[2]) ? parts[2]! : 0;
+  const [rMajor, rMinor, rPatch] = CODEX_HOOKS_MIN_VERSION;
+  if (major !== rMajor) return major > rMajor;
+  if (minor !== rMinor) return minor > rMinor;
+  return patch >= rPatch;
+}
+
+export function parseCodexVersion(output: string): string | null {
+  const match = output.match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? match[0] : null;
+}
+
+function probeCodexVersion(command: string): string | null {
+  try {
+    const result = Bun.spawnSync([command, "--version"], { stdout: "pipe", stderr: "ignore" });
+    if (result.exitCode !== 0) return null;
+    return parseCodexVersion(result.stdout.toString());
+  } catch {
+    return null;
+  }
+}
+
+// Whether the installed Codex actually consumes managed hooks. An explicit
+// AGENT_RELAY_CODEX_VERSION override wins (deterministic tests + operator escape hatch);
+// otherwise the real `codex --version` is probed once and cached. An UNKNOWN version (probe
+// failed / Codex not installed) is treated as supported: we neither block launches nor cry
+// wolf on a machine that can't be inspected — we only claim "not applied" when we can PROVE
+// the version is too old.
+export function codexHooksSupported(command = "codex"): boolean {
+  const override = codexVersionOverrideFromEnv();
+  if (override !== undefined) return override.trim() === "" ? true : codexVersionSupportsHooks(override.trim());
+  if (cachedProbe !== undefined) return cachedProbe;
+  const version = probeCodexVersion(command);
+  cachedProbe = version ? codexVersionSupportsHooks(version) : true;
+  return cachedProbe;
+}
+
+// Test-only: drop the memoized probe so a suite can re-probe under a changed environment.
+export function resetCodexHooksProbeCache(): void {
+  cachedProbe = undefined;
+}

package/src/config.ts

@@ -82,6 +82,13 @@ function relayUrlFromEnv(): string | undefined {
   return process.env.AGENT_RELAY_URL;
 }
 
+// #1096 — override for the Codex hooks version gate (finding 4). An explicit version string
+// bypasses the `codex --version` probe: deterministic in tests, and an operator escape hatch
+// when the probe can't run. Empty string means "assume supported".
+export function codexVersionOverrideFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CODEX_VERSION;
+}
+
 function textEnvOrFile(name: string): string | undefined {
   const inline = process.env[name];
   if (inline) return inline;

package/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,22 @@ 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,
+  writeClaudeSettingsJson,
 } from "./provisioning";
 import {
   claudeMcpLaunchArgs,
@@ -134,6 +139,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 +215,137 @@ 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;
+}
+
+// #1096 — the settings.json relay WRITES into an isolated managed Claude home so the provisioned
+// hooks (baseline guard included) land in the DOCUMENTED hook source Claude honors
+// ($CLAUDE_CONFIG_DIR/settings.json — loaded under `--setting-sources "user"` and the default),
+// rather than riding ONLY the inline `--settings` CLI flag. Claude does not document `--settings`
+// as a hook source, and — unlike a file written straight to disk — that flag's JSON must survive
+// shell/tmux launcher transit and passes Claude's "silently ignore settings that fail validation"
+// gate; a written settings.json bypasses both, so the baseline guard can't be silently absent
+// (the #1096 inert-at-runtime symptom). Returns null when:
+//   • there is NO isolated managed home (host base reuses the real ~/.claude — relay must not
+//     clobber it; that path keeps the inline --settings delivery), or
+//   • a caller --settings is present (the merge/suppression path owns hook delivery inline; see
+//     claudeSettingsArgs) — so the file and inline channels never DOUBLE-register the same hook.
+// Both assembleClaude (to keep these hooks OUT of the inline --settings) and materializeClaudeAssets
+// (to write the file) call this, so the launch and the disk agree.
+export function claudeManagedHookSettings(config: RunnerSpawnConfig, configHome: string | undefined): { hooks: ProvisioningHookSet } | null {
+  if (!configHome) return null;
+  const hostDefaultArgs = profileUsesProviderHostGlobals(config) ? config.providerConfig.defaultArgs : [];
+  if (hasSettingsArg(hostDefaultArgs) || hasSettingsArg(config.providerArgs)) return null;
+  const hookSet = renderProvisionedHookSet(resolveProvisionedHooks(configHome, config));
+  return Object.keys(hookSet).length ? { hooks: hookSet } : null;
 }
 
 // ── Instruction disposition (the vanilla floor's effect on the host instruction cascade) ──
@@ -255,6 +394,30 @@ 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);
+  // #1096 — for an isolated managed home with no caller --settings, the provisioned hooks are
+  // delivered through the managed settings.json (the documented, transit-safe hook source), so
+  // keep them OUT of the inline --settings to avoid double-registering the same guard. Host-base
+  // and caller-`--settings` launches keep inline delivery (see claudeManagedHookSettings).
+  const managedHookSettings = claudeManagedHookSettings(config, configHome);
+  const inlineHookSet = managedHookSettings ? {} : provisionedHookSet;
+  const settings = claudeSettingsArgs(
+    projectSettings.settings,
+    inlineHookSet,
+    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 +495,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 +518,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 +533,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 +541,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 +611,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 +657,27 @@ 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));
+    // #1096 — land the provisioned hooks in the managed home's settings.json (the documented
+    // hook source), matching the assembler's decision to keep them out of the inline --settings.
+    const managedHookSettings = claudeManagedHookSettings(config, configHome);
+    if (managedHookSettings) writeClaudeSettingsJson(configHome, managedHookSettings);
   }
   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 +693,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/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/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,69 @@ 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 });
+}
+
+// #1096 — write relay-owned settings into an ISOLATED Claude managed home's `settings.json`
+// (the DOCUMENTED hook source Claude honors under `--setting-sources "user"` or the default,
+// unlike the inline `--settings` CLI flag). The managed home is relay-owned and freshly keyed
+// per spawn, so an unconditional write is safe (profile-home seeds only `.claude.json`/`CLAUDE.md`,
+// never `settings.json`). Removes the file when there is nothing relay-owned to deliver so disk
+// stays == report. Never called for a host-base launch (which reuses the real `~/.claude`).
+export function writeClaudeSettingsJson(claudeHome: string, settings: Record<string, unknown>): void {
+  mkdirSync(claudeHome, { recursive: true });
+  if (!Object.keys(settings).length) {
+    rmSync(join(claudeHome, "settings.json"), { force: true });
+    return;
+  }
+  writeFileSync(join(claudeHome, "settings.json"), JSON.stringify(settings, 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/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/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/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 } : {}),
     },
   };
 }