@humwick/runner 0.0.0-stage → 0.130.0

package/src/provisioning.ts

@@ -0,0 +1,703 @@
+import { providerIntegrationFiles, projectClaudePermissionRules } from "./provider-integration";
+import { runnerMcpGeneration } from "./relay-mcp";
+import { writeChildEnv } from "@humwick/sdk/env";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { RETIRED_SHARED_MCP_SERVER_NAMES, isRelayMcpServerName, mcpServerInfo, wireToolName, type ToolGeneration, coerceProjectMcpServer, fffMcpBinaryPath, PROJECT_MCP_FILE, profileProjectSourceEnabled } from "@humwick/sdk";
+import { getManifest } from "@humwick/providers";
+import type { ProvisioningAssetFile, ProvisioningHookSet, ProvisioningMcpServer, ResolvedProvisioning } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+import { humwickHome } from "./config";
+import { preflightProvisionedMcpServers } from "./mcp-preflight";
+import { tomlInlineValue, tomlString } from "./relay-mcp";
+import { profileAllowsHostGlobalInstructions, providerSourceHome } from "./profile-home";
+import { hostSourcesFor, skillDirsUnder } from "./host-asset-plan";
+
+// Runner-side materialization of the relay-resolved provisioning bundle
+// (#554/#555/#556). The relay resolves a profile's refs against the DB registry and
+// attaches the concrete definitions to profile.provisioning; here we turn those into
+// real on-disk dirs (skills/plugins). MCP is handled in relay-mcp.ts.
+//
+// #557 — split into PURE RESOLUTION (resolve* → where each asset lands, no writes) and
+// MATERIALIZATION (materialize* → the disk writes). The single launch assembler
+// (launch-assembly.ts) calls the resolvers to build BOTH the launch args and the
+// projection report, so what's reported can never drift from what's written; the
+// 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: [], 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 ?? [], hooks: p.hooks ?? [], mcpServers: p.mcpServers ?? {}, ...(p.skipped?.length ? { skipped: p.skipped } : {}) };
+}
+
+// The fff search-redirect hook is bundled per provider manifest; it only needs the binary path in env.
+function providerBundlesFffRedirect(provider: RunnerSpawnConfig["provider"]): boolean {
+  return Boolean(getManifest(provider)?.provisioning?.bundledHooks?.some((hook) => hook.ref === "agent-relay-fff-search-redirect"));
+}
+
+// #2729 — provisioned stdio commands authored on another host are swapped for this host's
+// provisioned descriptor or dropped here, never emitted broken. #2809 — the fff path rewrite
+// lives here too so every provider launch gets it before the preflight judges the path.
+export function launchProvisionedMcpServers(
+  config: Pick<RunnerSpawnConfig, "agentProfile">,
+  servers: Record<string, ProvisioningMcpServer> = profileProvisioning(config).mcpServers,
+): Record<string, ProvisioningMcpServer> {
+  const fff = servers.fff;
+  const binary = fff?.command && !fff.url ? fffMcpBinaryPath(humwickHome()) : undefined;
+  return preflightProvisionedMcpServers(binary ? { ...servers, fff: { ...fff, command: binary } } : servers, {
+    sharedListener: Boolean(config.agentProfile?.sharedMcp),
+    // The fff binary is downloaded after launch resolution, so its (rewritten) path is exempt.
+    skip: binary ? ["fff"] : [],
+    home: humwickHome(),
+  });
+}
+
+export function fffMcpHookEnv(config: Pick<RunnerSpawnConfig, "agentProfile" | "provider">): Record<string, string> {
+  return writeChildEnv({}, { AGENT_RELAY_FFF_MCP_BINARY: providerBundlesFffRedirect(config.provider)
+    ? launchProvisionedMcpServers(config).fff?.command ?? "" : "" });
+}
+
+/** The resolved source matrix decides project MCP/skill projection (see profileProjectSourceEnabled). */
+export function projectSourceEnabled(
+  config: Pick<RunnerSpawnConfig, "agentProfile">,
+  capability: "mcp" | "skills",
+): boolean {
+  return profileProjectSourceEnabled(config.agentProfile, capability);
+}
+
+/**
+ * Project settings are currently the `projectSettings`/`localSettings` sibling of the source
+ * matrix (see ProfileCellSiblings), rather than a Project capability cell.  It is nevertheless
+ * resolved profile policy: the runner must not require, or consult, a spawn-time override.
+ */
+export function projectSettingsEnabled(config: Pick<RunnerSpawnConfig, "agentProfile">): boolean {
+  return Boolean(config.agentProfile?.projectSettings);
+}
+
+// #667 — project `.mcp.json` MCP projection. OPT-IN via the resolved profile's `projectMcp`
+// (set per-spawn or by profile, relay-side). Reads the spawn cwd's COMMITTED `.mcp.json` and
+// returns its `mcpServers` as a provider-neutral record, so the launch assembler injects them
+// through the CONTROLLED `--mcp-config` (Claude) / `-c mcp_servers.*` (Codex) path that
+// survives `--strict-mcp-config` — the project's own servers travel with the repo like they do
+// for a human who clones it, WITHOUT enabling Claude's ambient project-discovery trust modal
+// (which wedges headless agents, the reason #662 made every managed launch strict). The runner
+// is the filesystem authority for the spawn cwd (relay may run on another host), so the read
+// lands here. Best-effort: a missing/malformed file (or one with no `mcpServers`) yields {} and
+// never aborts the launch. Returns {} when projection is OFF.
+export function resolveProjectMcpServers(
+  config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">,
+): Record<string, ProvisioningMcpServer> {
+  const profile = config.agentProfile;
+  if (!projectSourceEnabled(config, "mcp")) return {};
+  // N7 — a stamped source matrix is the only trust-gated project MCP path. The
+  // server decides roots/pinned/any against its registry and carries the result
+  // through the spawn-scoped profile. Missing/denied decisions fail closed.
+  if (profile?.sources?.project && !profile.projectGates?.mcp?.allowed) return {};
+  // #3043 — a project role's entries were read at one commit; the working tree never applies.
+  if (profile?.pinnedProjectMcp) return { ...profile.pinnedProjectMcp.servers };
+  const file = join(config.cwd, PROJECT_MCP_FILE);
+  if (!existsSync(file)) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    console.warn(`project .mcp.json projection: failed to parse ${file}: ${(err as Error).message}`);
+    return {};
+  }
+  const servers = (parsed as { mcpServers?: unknown } | null)?.mcpServers;
+  if (!servers || typeof servers !== "object") return {};
+  const out: Record<string, ProvisioningMcpServer> = {};
+  for (const [name, raw] of Object.entries(servers as Record<string, unknown>)) {
+    const server = coerceProjectMcpServer(raw);
+    if (server) out[name] = server;
+  }
+  return out;
+}
+
+export function resolveClaudeProjectSkills(
+  claudeHome: string,
+  config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">,
+  reservedNames: ReadonlySet<string> = new Set(),
+): ResolvedAsset[] {
+  if (!projectSourceEnabled(config, "skills")) return [];
+  return linkedSkillAssets(join(config.cwd, ".claude", "skills"), claudeHome, reservedNames);
+}
+
+// Skill dirs (including symlinked ones) under `skillsRoot`, linked into `claudeHome/skills`.
+function linkedSkillAssets(skillsRoot: string, claudeHome: string, reservedNames: ReadonlySet<string>): ResolvedAsset[] {
+  const targetRoot = join(claudeHome, "skills");
+  return skillDirsUnder(skillsRoot)
+    .map((source) => ({ name: basename(source), source }))
+    .filter(({ name }) => !reservedNames.has(name))
+    .map(({ name, source }) => ({ name, dir: join(targetRoot, assetDirName(name)), source: { kind: "link" as const, source } }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function resolveClaudeHostSkills(
+  claudeHome: string,
+  config: Pick<RunnerSpawnConfig, "agentProfile">,
+  reservedNames: ReadonlySet<string> = new Set(),
+  provider: string = "claude",
+): ResolvedAsset[] {
+  if (!hostSourcesFor(config).skills) return [];
+  // #2513 — keyed by provider id so a dedicatedHome claude-family provider (claude-b)
+  // resolves host skills from ITS OWN source home, never ~/.claude's.
+  return linkedSkillAssets(join(providerSourceHome(provider), "skills"), claudeHome, reservedNames);
+}
+
+export interface ResolvedSourceShadow {
+  source: "host" | "project" | "agent-relay";
+  capability: "mcp" | "hooks" | "skills" | "plugins";
+  name: string;
+}
+
+export interface ResolvedClaudeSkillSources {
+  relay: ResolvedAsset[];
+  project: ResolvedAsset[];
+  host: ResolvedAsset[];
+  shadows: ResolvedSourceShadow[];
+}
+
+/** Resolve the skill union once, preserving the actual lower-precedence collisions. */
+export function resolveClaudeSkillSources(claudeHome: string, config: RunnerSpawnConfig, provider: string = "claude"): ResolvedClaudeSkillSources {
+  const relay = resolveClaudeProvisionedSkills(claudeHome, config);
+  const relayNames = new Set(relay.map((asset) => asset.name));
+  const projectAll = resolveClaudeProjectSkills(claudeHome, config);
+  const project = projectAll.filter((asset) => !relayNames.has(asset.name));
+  const projectNames = new Set(project.map((asset) => asset.name));
+  const hostAll = resolveClaudeHostSkills(claudeHome, config, new Set(), provider);
+  const host = hostAll.filter((asset) => !relayNames.has(asset.name) && !projectNames.has(asset.name));
+  return {
+    relay,
+    project,
+    host,
+    shadows: [
+      ...projectAll.filter((asset) => relayNames.has(asset.name)).map((asset) => ({ source: "project" as const, capability: "skills" as const, name: asset.name })),
+      ...hostAll.filter((asset) => relayNames.has(asset.name) || projectNames.has(asset.name)).map((asset) => ({ source: "host" as const, capability: "skills" as const, name: asset.name })),
+    ],
+  };
+}
+
+export function resolveMcpSourceShadows(
+  projectRaw: Record<string, unknown>,
+  provisioned: Record<string, unknown>,
+  host: Record<string, unknown>,
+  declared: Record<string, unknown>,
+  shared: Record<string, unknown>,
+  relayEndpoint: boolean,
+): ResolvedSourceShadow[] {
+  const wins = new Set([...Object.keys(provisioned), ...Object.keys(shared), ...RETIRED_SHARED_MCP_SERVER_NAMES]);
+  return [
+    ...Object.keys(projectRaw).filter((name) => (isRelayMcpServerName(name) && relayEndpoint) || wins.has(name)).map((name) => ({ source: "project" as const, capability: "mcp" as const, name })),
+    ...Object.keys(host).filter((name) => (isRelayMcpServerName(name) && relayEndpoint) || name in declared || wins.has(name)).map((name) => ({ source: "host" as const, capability: "mcp" as const, name })),
+  ];
+}
+
+const UNSAFE_PROJECT_CLAUDE_SETTINGS = new Set([
+  "apiKeyHelper",
+  "allowDangerouslySkipPermissions",
+  "allowedTools",
+  "disabledMcpjsonServers",
+  "disallowedTools",
+  "enableAllProjectMcpServers",
+  "enabledMcpjsonServers",
+  "env",
+  "mcpServers",
+  "permissionMode",
+  "permissions",
+  "statusLine",
+  "tools",
+]);
+
+export interface ResolvedProjectClaudeSettings {
+  applied: boolean;
+  settings: Record<string, unknown>;
+  keys: string[];
+  ignoredKeys: string[];
+  file?: string;
+}
+
+export function resolveProjectClaudeSettings(
+  config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">,
+): ResolvedProjectClaudeSettings {
+  if (!projectSettingsEnabled(config)) return { applied: false, settings: {}, keys: [], ignoredKeys: [] };
+  const file = join(config.cwd, ".claude", "settings.json");
+  if (!existsSync(file)) return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    console.warn(`project .claude/settings.json projection: failed to parse ${file}: ${(err as Error).message}`);
+    return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  }
+  const settings: Record<string, unknown> = {};
+  const ignoredKeys: string[] = [];
+  for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (key === "hooks") {
+      if (config.agentProfile?.sources?.project?.hooks?.enabled && config.agentProfile.projectGates?.hooks?.allowed) settings[key] = value;
+      else ignoredKeys.push(key);
+      continue;
+    }
+    if (UNSAFE_PROJECT_CLAUDE_SETTINGS.has(key)) {
+      ignoredKeys.push(key);
+      continue;
+    }
+    settings[key] = value;
+  }
+  return {
+    applied: true,
+    settings,
+    keys: Object.keys(settings).sort(),
+    ignoredKeys: ignoredKeys.sort(),
+    file,
+  };
+}
+
+// A resolved provisioning asset: WHERE it lands (`dir`) and HOW it materializes
+// (`source`). `files` writes the inline set into `dir`; `link` symlinks a pre-existing
+// source dir at `dir`; `inPlace` uses the source dir as-is (no write, dir IS the source).
+export type ResolvedAssetSource =
+  | { kind: "files"; files: ProvisioningAssetFile[] }
+  | { kind: "link"; source: string }
+  | { kind: "inPlace" };
+export interface ResolvedAsset {
+  name: string;
+  dir: string;
+  source: ResolvedAssetSource;
+  provenance?: "relay" | "project";
+}
+
+export interface ResolvedHookAsset extends ResolvedAsset {
+  hooks: ProvisioningHookSet;
+}
+
+function assetDirName(name: string): string {
+  return sanitizeFsName(name, { replacement: "-", collapse: false, maxLen: 120, fallback: "asset" });
+}
+
+function resolveExistingDir(dir: string, cwd: string): string | null {
+  const abs = isAbsolute(dir) ? dir : resolve(cwd, dir);
+  return existsSync(abs) ? abs : null;
+}
+
+function hasRootSkillManifest(files: ProvisioningAssetFile[]): boolean {
+  return files.some((f) => f.path === "SKILL.md");
+}
+
+// Write an inline file set into <dir>, guarding against path escapes from a malformed
+// 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);
+    const rel = relative(root, dest);
+    if (rel.startsWith("..") || isAbsolute(rel)) continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, file.content, { mode: 0o600 });
+  }
+}
+
+// Perform the disk write a resolved asset describes. files → write inline; link →
+// (re)create the symlink; inPlace → nothing (the dir already exists at the source).
+// Best-effort for links: a failed link must not abort the launch.
+function materializeAsset(asset: ResolvedAsset): boolean {
+  if (asset.source.kind === "files") {
+    writeInlineFiles(asset.dir, asset.source.files);
+    return true;
+  }
+  if (asset.source.kind === "link") {
+    try {
+      mkdirSync(dirname(asset.dir), { recursive: true });
+      if (existsSync(asset.dir)) rmSync(asset.dir, { recursive: true, force: true });
+      symlinkSync(asset.source.source, asset.dir);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return existsSync(asset.dir);
+}
+
+// #554 (Claude) — each provisioned skill lands at <claudeHome>/skills/<name> so it's
+// auto-discovered under the launch's `--setting-sources "user"` scope (host skills
+// never bleed). Inline files are written there; a pre-existing dir is symlinked in.
+export function resolveClaudeProvisionedSkills(claudeHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { skills } = profileProvisioning(config);
+  const skillsRoot = join(claudeHome, "skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const skill of skills) {
+    const dir = join(skillsRoot, assetDirName(skill.name));
+    if (skill.files?.length) {
+      resolved.push({ name: skill.name, dir, source: { kind: "files", files: providerIntegrationFiles(skill.name, skill.files, runnerMcpGeneration(config.env)) } });
+      continue;
+    }
+    if (skill.dir) {
+      const source = resolveExistingDir(skill.dir, config.cwd);
+      if (source) resolved.push({ name: skill.name, dir, source: { kind: "link", source } });
+    }
+  }
+  return resolved;
+}
+
+// #556 (Claude) — each provisioned plugin resolves to a --plugin-dir. Inline plugins
+// materialize under <claudeHome>/relay-provisioned-plugins/<name>; declared dirs are
+// used in place. The resolved `dir` is appended to the launch's --plugin-dir set.
+export function resolveClaudeProvisionedPlugins(claudeHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { plugins } = profileProvisioning(config);
+  const parent = join(claudeHome, "relay-provisioned-plugins");
+  const resolved: ResolvedAsset[] = [];
+  for (const plugin of plugins) {
+    if (plugin.files?.length) {
+      resolved.push({ name: plugin.name, dir: join(parent, assetDirName(plugin.name)), source: { kind: "files", files: providerIntegrationFiles(plugin.name, plugin.files, runnerMcpGeneration(config.env)) } });
+      continue;
+    }
+    if (plugin.dir) {
+      const source = resolveExistingDir(plugin.dir, config.cwd);
+      if (source) resolved.push({ name: plugin.name, dir: source, source: { kind: "inPlace" } });
+    }
+  }
+  return resolved;
+}
+
+// #554 (Codex) — each provisioned skill resolves to a dir for `-c skills.config`.
+// Inline skills materialize under <codexHome>/relay-provisioned-skills/<name>; declared
+// dirs are used in place. Codex requires a SKILL.md at the dir root to register it, so
+// inline sets without one and dirs missing it are dropped at resolution time.
+export function resolveCodexProvisionedSkills(codexHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { skills } = profileProvisioning(config);
+  const parent = join(codexHome, "relay-provisioned-skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const skill of skills) {
+    if (skill.files?.length) {
+      if (!hasRootSkillManifest(skill.files)) continue;
+      resolved.push({ name: skill.name, dir: join(parent, assetDirName(skill.name)), source: { kind: "files", files: providerIntegrationFiles(skill.name, skill.files, runnerMcpGeneration(config.env)) } });
+      continue;
+    }
+    if (skill.dir) {
+      const source = resolveExistingDir(skill.dir, config.cwd);
+      if (source && existsSync(join(source, "SKILL.md"))) resolved.push({ name: skill.name, dir: source, source: { kind: "inPlace" } });
+    }
+  }
+  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 });
+  writeCodexHookTrustState(codexHome, hooks);
+}
+
+const CODEX_HOOK_EVENT_STATE_KEYS: Record<string, string> = {
+  PreToolUse: "pre_tool_use",
+  PermissionRequest: "permission_request",
+  PostToolUse: "post_tool_use",
+  PreCompact: "pre_compact",
+  PostCompact: "post_compact",
+  SessionStart: "session_start",
+  UserPromptSubmit: "user_prompt_submit",
+  SubagentStart: "subagent_start",
+  SubagentStop: "subagent_stop",
+  Stop: "stop",
+};
+
+interface CodexHookTrustEntry {
+  key: string;
+  trustedHash: string;
+}
+
+export function codexHookTrustEntries(codexHome: string, hooks: ProvisioningHookSet): CodexHookTrustEntry[] {
+  // Codex keys hooks.state on the canonicalized CODEX_HOME; a symlinked ancestor (macOS
+  // /var → /private/var) would leave a lexical-only key untrusted and the hook skipped.
+  return hookTrustEntries([...new Set([codexHome, realpathOr(codexHome)])].map((home) => join(home, "hooks.json")), hooks);
+}
+
+// #3025 — Codex also reads TOML hooks and their trust state from the `-c` session-flags layer,
+// keyed on this synthetic source, so a launch can carry hooks while keeping any CODEX_HOME.
+const CODEX_SESSION_FLAGS_SOURCE = "/<session-flags>/config.toml";
+
+export function codexSessionHookArgs(hooks: ProvisioningHookSet): string[] {
+  const state = Object.fromEntries(hookTrustEntries([CODEX_SESSION_FLAGS_SOURCE], hooks).map((entry) => [entry.key, { trusted_hash: entry.trustedHash }]));
+  return ["-c", `hooks=${tomlInlineValue({ ...hooks, state })}`];
+}
+
+function hookTrustEntries(sourcePaths: string[], hooks: ProvisioningHookSet): CodexHookTrustEntry[] {
+  const entries: CodexHookTrustEntry[] = [];
+  for (const [eventName, groups] of Object.entries(hooks)) {
+    const eventKey = CODEX_HOOK_EVENT_STATE_KEYS[eventName];
+    if (!eventKey) continue;
+    groups.forEach((group, groupIndex) => {
+      group.hooks.forEach((handler, handlerIndex) => {
+        if (handler.type !== "command") return;
+        const trustedHash = codexCommandHookHash(eventKey, group.matcher, group, handler);
+        for (const sourcePath of sourcePaths) {
+          entries.push({ key: `${sourcePath}:${eventKey}:${groupIndex}:${handlerIndex}`, trustedHash });
+        }
+      });
+    });
+  }
+  return entries;
+}
+
+function realpathOr(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function writeCodexHookTrustState(codexHome: string, hooks: ProvisioningHookSet): void {
+  const entries = codexHookTrustEntries(codexHome, hooks);
+  if (!entries.length) return;
+  const configPath = join(codexHome, "config.toml");
+  let config = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  for (const entry of entries) {
+    config = upsertCodexHookTrustEntry(config, entry);
+  }
+  writeFileSync(configPath, config, { mode: 0o600 });
+}
+
+function upsertCodexHookTrustEntry(config: string, entry: CodexHookTrustEntry): string {
+  const header = `[hooks.state.${tomlString(entry.key)}]`;
+  const lines = config.length ? config.split(/\n/) : [];
+  const headerIndex = lines.findIndex((line) => line.trim() === header);
+  if (headerIndex < 0) {
+    const prefix = config.endsWith("\n") || config.length === 0 ? config : `${config}\n`;
+    return `${prefix}\n${header}\ntrusted_hash = ${tomlString(entry.trustedHash)}\n`;
+  }
+
+  let nextHeaderIndex = lines.length;
+  for (let i = headerIndex + 1; i < lines.length; i += 1) {
+    if (/^\s*\[.*\]\s*$/.test(lines[i] ?? "")) {
+      nextHeaderIndex = i;
+      break;
+    }
+  }
+
+  const trustedHashLine = `trusted_hash = ${tomlString(entry.trustedHash)}`;
+  const existingIndex = lines
+    .slice(headerIndex + 1, nextHeaderIndex)
+    .findIndex((line) => /^\s*trusted_hash\s*=/.test(line));
+  if (existingIndex >= 0) {
+    lines[headerIndex + 1 + existingIndex] = trustedHashLine;
+  } else {
+    lines.splice(nextHeaderIndex, 0, trustedHashLine);
+  }
+  return lines.join("\n");
+}
+
+function codexCommandHookHash(
+  eventKey: string,
+  matcher: string | undefined,
+  group: ProvisioningHookSet[string][number],
+  handler: ProvisioningHookSet[string][number]["hooks"][number],
+): string {
+  // Mirrors Codex's command_hook_hash: hash the normalized hook identity, not the source file.
+  const normalizedHandler: Record<string, unknown> = {
+    type: "command",
+    command: handler.command,
+    async: false,
+    timeout: Math.max(1, handler.timeout ?? 600),
+  };
+  if (handler.statusMessage !== undefined) normalizedHandler.statusMessage = handler.statusMessage;
+
+  const identity: Record<string, unknown> = {
+    event_name: eventKey,
+    hooks: [normalizedHandler],
+  };
+  if (matcher !== undefined) identity.matcher = matcher;
+
+  const canonical = canonicalJson(identity);
+  const hash = createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+  return `sha256:${hash}`;
+}
+
+function canonicalJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalJson);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, val]) => [key, canonicalJson(val)]),
+    );
+  }
+  return value;
+}
+
+// #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 });
+  const path = join(claudeHome, "settings.json");
+  if (!Object.keys(settings).length) {
+    rmSync(path, { force: true });
+    return;
+  }
+  // Claude can read this file while a replacement starts. Publish a complete JSON snapshot
+  // in one rename so it never observes a truncated or half-written settings file.
+  const pending = `${path}.relay-${process.pid}-${randomUUID()}.tmp`;
+  try {
+    writeFileSync(pending, JSON.stringify(settings, null, 2), { mode: 0o600 });
+    renameSync(pending, path);
+  } finally {
+    rmSync(pending, { force: true });
+  }
+}
+
+// T3182 — merge a permissions.deny entry into a managed Claude settings payload WITHOUT
+// clobbering permissions the payload already carries (deny lists union, everything else passes
+// through). Pure — the caller composes and writes.
+export function mergeClaudeSettingsDeny(settings: Record<string, unknown>, deny: string[]): Record<string, unknown> {
+  const permissions = typeof settings.permissions === "object" && settings.permissions !== null && !Array.isArray(settings.permissions)
+    ? settings.permissions as Record<string, unknown>
+    : {};
+  const existing = Array.isArray(permissions.deny) ? permissions.deny : [];
+  return { ...settings, permissions: { ...permissions, deny: [...new Set([...existing, ...deny])] } };
+}
+
+/** Merge Relay-owned guarded control-plane grants without replacing caller-authored permissions. */
+export function mergeClaudeSettingsAllow(settings: Record<string, unknown>, allow: string[]): Record<string, unknown> {
+  const permissions = typeof settings.permissions === "object" && settings.permissions !== null && !Array.isArray(settings.permissions)
+    ? settings.permissions as Record<string, unknown>
+    : {};
+  const existing = Array.isArray(permissions.allow) ? permissions.allow : [];
+  return { ...settings, permissions: { ...permissions, allow: [...new Set([...existing, ...allow])] } };
+}
+
+export const CLAUDE_GUARDED_RELAY_TOOLS = [
+  "mcp__agent-relay__relay_send_message",
+  "mcp__agent-relay__relay_reply",
+  "mcp__agent-relay__relay_task_set_status",
+  "mcp__agent-relay__relay_task_comment",
+  "mcp__agent-relay__relay_task_deliver",
+];
+
+function guardedRelayTools(generation: ToolGeneration): string[] {
+  return CLAUDE_GUARDED_RELAY_TOOLS.map(name => `mcp__${mcpServerInfo(generation).name}__${wireToolName(name.split("__").at(-1)!, generation)}`);
+}
+
+export function claudeGuardedRelaySettings(approvalMode: string | undefined, generation: ToolGeneration = "relay"): Record<string, unknown> {
+  return approvalMode === "guarded" ? { permissions: { allow: guardedRelayTools(generation) } } : {};
+}
+
+// #3388 — Claude's project scan loads CLAUDE.md, CLAUDE.local.md, .claude/CLAUDE.md and .claude/rules/**
+// from EVERY ancestor of the cwd, so host files above the repo (~/.claude/CLAUDE.md, ~/CLAUDE.md,
+// ~/projects/CLAUDE.md) reach an agent despite the isolated CLAUDE_CONFIG_DIR. Host instructions
+// `ignore` excludes them through the supported `claudeMdExcludes` setting. Rule: the repo root
+// (nearest ancestor holding .git, else the cwd) and below are repo instructions and keep loading;
+// everything strictly above it is host-level. The walk starts from the physical cwd, which is what
+// the provider process sees.
+export function claudeHostInstructionExcludeSettings(config: { agentProfile?: RunnerSpawnConfig["agentProfile"]; cwd: string }): Record<string, unknown> {
+  if (profileAllowsHostGlobalInstructions(config)) return {};
+  const excludes: string[] = [];
+  for (const home of new Set([homedir(), realpathOr(homedir())])) excludes.push(...claudeUserDirPatterns(home));
+  for (let dir = dirname(repoRootOf(realpathOr(resolve(config.cwd)))); ; dir = dirname(dir)) {
+    excludes.push(...claudeUserDirPatterns(dir), join(globLiteral(dir), "CLAUDE.md"), join(globLiteral(dir), "CLAUDE.local.md"));
+    if (dirname(dir) === dir) break;
+  }
+  return { claudeMdExcludes: [...new Set(excludes)] };
+}
+
+// claudeMdExcludes entries are picomatch globs, and Claude rewrites every backslash to "/" before
+// matching, so backslash escapes break: wrap each metacharacter in a bracket literal instead.
+function globLiteral(path: string): string {
+  return path.replace(/[*?[\](){}!+@]/g, "[$&]");
+}
+
+function claudeUserDirPatterns(dir: string): string[] {
+  const claudeDir = join(globLiteral(dir), ".claude");
+  return [join(claudeDir, "CLAUDE.md"), join(claudeDir, "rules", "**")];
+}
+
+function repoRootOf(cwd: string): string {
+  const start = resolve(cwd);
+  for (let dir = start; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    if (dirname(dir) === dir) return start;
+  }
+}
+
+/** Claude Code 2.1.282 persists bypass acceptance in user settings.json. */
+export function claudeBypassPermissionSettings(approvalMode: string | undefined): Record<string, unknown> {
+  return approvalMode === "open" ? { skipDangerousModePermissionPrompt: true } : {};
+}
+
+export function mergeClaudeRelayPermissions(settings: Record<string, unknown>, relayPermissions: unknown): Record<string, unknown> {
+  const candidate = typeof relayPermissions === "object" && relayPermissions !== null && !Array.isArray(relayPermissions)
+    ? relayPermissions as Record<string, unknown>
+    : {};
+  const allow = Array.isArray(candidate.allow) ? candidate.allow.filter((item): item is string => typeof item === "string") : [];
+  return mergeClaudeSettingsAllow(settings, allow);
+}
+
+export function withManagedClaudePermissions(settings: Record<string, unknown>, approvalMode: string | undefined, generation: ToolGeneration = "relay"): Record<string, unknown> {
+  const guarded = approvalMode === "guarded" ? mergeClaudeSettingsAllow(settings, guardedRelayTools(generation)) : settings;
+  return projectClaudePermissionRules(mergeClaudeSettingsDeny({ ...guarded, ...claudeBypassPermissionSettings(approvalMode), idleCompaction: false }, ["SendFeedback"]), generation);
+}
+
+// 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[] {
+  const dirs: string[] = [];
+  for (const asset of assets) {
+    if (materializeAsset(asset)) dirs.push(asset.dir);
+  }
+  return dirs;
+}