@humwick/runner 0.0.0-stage → 0.130.1

package/src/profile-projection.ts

@@ -0,0 +1,411 @@
+import type {
+  AgentProfile,
+  AgentProfileProjectionAsset,
+  AgentProfileProjectionEntry,
+  AgentProfileProjectionReport,
+  AgentProfileProjectionTrust,
+  SpawnProvider,
+} from "@humwick/sdk";
+import { isRecord, mcpServerInfo } from "@humwick/sdk";
+import { getManifest } from "@humwick/providers";
+import type { AssembledLaunch } from "./launch-assembly";
+import { projectSourceEnabled, type ResolvedSourceShadow } from "./provisioning";
+import { RELAY_MCP_SERVER_NAME, SHARED_MCP_METAONLY_CONFIG_FILENAME } from "./relay-mcp";
+
+/**
+ * The projection is a report of assembled launch facts.  In particular, it is not a second
+ * resolver: a source cell is authoritative only for the assets/flags the assembler put on the
+ * launch.  The profile is used below only for labels and registry provenance, never for a
+ * category mode (the old mode fields were declarations, not launch facts).
+ */
+interface AgentProfileProjectionInput {
+  assembled: AssembledLaunch;
+  generatedAt?: number;
+}
+
+type MatrixSource = "host" | "project" | "agent-relay";
+type MatrixCapability = "instructions" | "mcp" | "hooks" | "skills" | "plugins";
+
+const MATRIX_SOURCES: readonly MatrixSource[] = ["host", "project", "agent-relay"];
+const MATRIX_CAPABILITIES: readonly MatrixCapability[] = ["instructions", "mcp", "hooks", "skills", "plugins"];
+
+export function agentProfileProjectionReport(input: AgentProfileProjectionInput): AgentProfileProjectionReport {
+  const { assembled } = input;
+  const entries: AgentProfileProjectionEntry[] = [
+    ...matrixEntries(assembled),
+    relayStatusLineEntry(assembled),
+    configHomeEntry(assembled),
+    launchShapeEntry(assembled),
+    localSettingsEntry(assembled),
+    filesystemEntry(assembled.profile),
+    envEntry(assembled.profile),
+    nativeMemoryEntry(assembled),
+    sharedMcpEntry(assembled),
+    ...provisioningEntries(assembled),
+  ];
+  const warnings = entries
+    .filter((entry) => entry.result === "partial" || entry.result === "unenforceable" || entry.result === "not-implemented")
+    .map((entry) => `${entry.capability}: ${entry.detail}`);
+  const unsupported = entries
+    .filter((entry) => entry.result === "unenforceable")
+    .map((entry) => entry.capability);
+  return {
+    profileName: assembled.profile?.name ?? "default",
+    provider: assembled.provider,
+    base: assembled.base,
+    generatedAt: input.generatedAt ?? Date.now(),
+    entries,
+    warnings,
+    unsupported,
+  };
+}
+
+function matrixEntries(a: AssembledLaunch): AgentProfileProjectionEntry[] {
+  const cells: Record<`${MatrixSource}.${MatrixCapability}`, AgentProfileProjectionEntry> = {
+    "host.instructions": hostInstructions(a),
+    "host.mcp": hostMcp(a),
+    "host.hooks": hostHooks(a),
+    "host.skills": hostSkills(a),
+    "host.plugins": hostPlugins(a),
+    "project.instructions": projectInstructions(a),
+    "project.mcp": projectMcp(a),
+    "project.hooks": projectHooks(a),
+    "project.skills": projectSkills(a),
+    "project.plugins": projectPlugins(a),
+    "agent-relay.instructions": relayInstructions(a),
+    "agent-relay.mcp": relayMcp(a),
+    "agent-relay.hooks": relayHooks(a),
+    "agent-relay.skills": relaySkills(a),
+    "agent-relay.plugins": relayPlugins(a),
+  };
+  addCrossSourceShadows(cells, a);
+  return MATRIX_SOURCES.flatMap((source) => MATRIX_CAPABILITIES.map((capability) => cells[`${source}.${capability}`]));
+}
+
+/**
+ * The resolver's additive-union precedence is visible in the report even when two provider
+ * surfaces happen to accept the same name: reserved/registry/bundled Relay assets outrank
+ * Project, which outranks Host.  This is observational only; the launch object remains the
+ * authority for what was actually emitted.
+ */
+function addCrossSourceShadows(
+  cells: Record<`${MatrixSource}.${MatrixCapability}`, AgentProfileProjectionEntry>,
+  a: AssembledLaunch,
+): void {
+  for (const shadow of a.sourceShadows ?? []) {
+    const entry = cells[`${shadow.source}.${shadow.capability === "hooks" ? "hooks" : shadow.capability}`];
+    const provenance = shadow.source === "agent-relay"
+      ? relayProvenance(a, sourceKind(shadow.capability), shadow.name)
+      : shadow.source;
+    entry.shadowed = dedupeAssets([...(entry.shadowed ?? []), asset(shadow.name, provenance)]);
+  }
+}
+
+function sourceKind(capability: ResolvedSourceShadow["capability"]): "skill" | "plugin" | "hook" | "mcp" {
+  if (capability === "skills") return "skill";
+  if (capability === "plugins") return "plugin";
+  if (capability === "hooks") return "hook";
+  return "mcp";
+}
+
+function dedupeAssets(items: AgentProfileProjectionAsset[]): AgentProfileProjectionAsset[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const key = `${item.name}\u0000${item.provenance}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function hostInstructions(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (a.instructions.global === "allow") return scalarCell("host.instructions", "allow", "applied", "allow", "provider default/global instruction cascade", "Host/global provider instructions remain available.");
+  if (a.instructions.global === "isolated") return scalarCell("host.instructions", "ignore", "disabled", "off", "isolated provider config home", "The managed provider home excludes host/global instructions.");
+  return scalarCell("host.instructions", "ignore", "unenforceable", "unknown", "no provider lever", "Host/global instruction exclusion was requested but no launch lever enforced it.");
+}
+
+function hostMcp(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (!a.configHome) return assetCell("host.mcp", "available", "applied", "host config", "provider host configuration", "Ambient host MCP is available in the provider's normal config home.", [], "untrusted");
+  const assets = a.mcp.hostServers.map((name) => asset(name, "host"));
+  if (assets.length) return assetCell("host.mcp", "available", "applied", assets, "controlled MCP config injection", `Host MCP servers were re-injected into the managed home (${a.mcp.hostServers.join(", ")}).`, [], "untrusted");
+  return assetCell("host.mcp", "available", "disabled", [], "isolated provider config home", "Ambient host MCP is not loaded by this managed provider home.", [], "untrusted");
+}
+
+function hostHooks(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (!a.configHome) return assetCell("host.hooks", "available", "applied", "ambient", "provider host config", "Ambient host hooks remain available in the provider's normal config home.", [], "untrusted");
+  if (!a.hostHooksEnforceable) {
+    return assetCell("host.hooks", "available", "unenforceable", "unknown", "provider hook capability", "The installed provider cannot honor host hooks in this isolated config home; H.hooks is unenforceable for this launch.", [], "unknown");
+  }
+  // A host hook artifact must not make missing Relay hooks look applied. This is a launch-wide
+  // fact: callers can suppress the Relay hook set while H.hooks was successfully re-injected.
+  if (a.hooksSuppressed) {
+    return assetCell("host.hooks", "available", "partial", "suppressed", "hook delivery withheld", `Relay hooks were not delivered: ${a.hooksSuppressed.reason}.`, [], "unknown");
+  }
+  if (a.hostHooks) {
+    return assetCell("host.hooks", "available", "applied", "host", "controlled settings/hooks.json injection", "Host provider hooks were re-injected into the managed provider home.", [], "untrusted");
+  }
+  return assetCell("host.hooks", "available", "disabled", "off", "isolated provider config home", "Ambient host hooks are excluded from the managed provider home.", [], "untrusted");
+}
+
+function hostSkills(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const assets = a.hostSkills.map((item) => asset(item.name, "host"));
+  return assetCell("host.skills", assets.length ? "available" : "off", assets.length ? "applied" : "disabled", assets, "host skill directories copied into managed home", assets.length ? `Host skills materialized (${assets.map((item) => item.name).join(", ")}).` : "No host skill directories reached this launch.", [], "untrusted");
+}
+
+function hostPlugins(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const assets = a.hostPluginDirs.map((dir) => asset(dir, "host"));
+  return assetCell("host.plugins", assets.length ? "available" : "off", assets.length ? "applied" : "disabled", assets, "host plugin directories passed to provider", assets.length ? `Host plugins reached the launch (${assets.map((item) => item.name).join(", ")}).` : "No host plugin directories reached this launch.", [], "untrusted");
+}
+
+function projectInstructions(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (a.instructions.repo === "allow") return scalarCell("project.instructions", "allow", "applied", "allow", projectInstructionMechanism(a), "Project/repo instructions remain available.");
+  // #2086 — the native project scope was dropped to gate ambient hooks, but P.instructions
+  // re-injected the repo CLAUDE.md/AGENTS.md through the controlled append-system-prompt channel.
+  // Report it as applied+honored (trusted), NOT suppressed, so the launch shape is not misreported.
+  if (a.instructions.repo === "reinjected") return scalarCell("project.instructions", "allow", "applied", "reinjected", "controlled append-system-prompt re-injection", "Repo CLAUDE.md/AGENTS.md are re-injected through Relay's controlled channel because the native project scope is dropped to gate ambient hooks.", "trusted");
+  if (a.instructions.repo === "suppressed") return scalarCell("project.instructions", "ignore", "disabled", "off", projectInstructionMechanism(a), "Project/repo instructions are excluded by the emitted launch shape.");
+  return scalarCell("project.instructions", "ignore", "unenforceable", "unknown", "no provider lever", "Project/repo instruction exclusion was requested but was not enforced by this launch.");
+}
+
+function reviewInfo(a: AssembledLaunch, gate?: { observed?: string; repoKey?: string; reviewMode?: "fingerprint" | "commit" }): AgentProfileProjectionEntry["review"] {
+  if (!gate?.observed || !gate.repoKey || !gate.reviewMode || !a.profile?.name) return undefined;
+  return { profileName: a.profile.name, repoKey: gate.repoKey, mode: gate.reviewMode, observed: gate.observed };
+}
+
+function projectMcp(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const projectMcpEnabled = projectSourceEnabled({ agentProfile: a.profile }, "mcp");
+  if (projectMcpEnabled && a.profile?.projectGates?.mcp && !a.profile.projectGates.mcp.allowed) {
+    return { ...assetCell("project.mcp", "enabled", "partial", "suppressed", "project trust gate", a.profile.projectGates.mcp.detail, [], "unknown"), review: reviewInfo(a, a.profile.projectGates.mcp) };
+  }
+  const assets = a.mcp.projectServers.map((name) => asset(name, "project"));
+  return { ...assetCell("project.mcp", assets.length ? "available" : "off", assets.length ? "applied" : "disabled", assets, "controlled project MCP config injection", assets.length ? `Committed project MCP servers reached the launch (${a.mcp.projectServers.join(", ")}).` : "No committed project MCP server reached this launch.", [], "trusted"), review: reviewInfo(a, a.profile?.projectGates?.mcp) };
+}
+
+function projectHooks(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (!hasSettingSourceSurface(a)) return assetCell("project.hooks", "available", "not-applicable", "n/a", "provider has no project hook surface", "This provider has no project settings/hook surface.", [], "unknown");
+  if (a.projectHooksSuppressed) return { ...assetCell("project.hooks", "enabled", "partial", "suppressed", "project trust gate", a.projectHooksSuppressed.reason, [], "unknown"), review: reviewInfo(a, a.profile?.projectGates?.hooks) };
+  if (a.profile?.sources?.project?.hooks?.enabled) {
+    const assets = a.projectHooks.map((item) => asset(item.name, "project"));
+    return { ...assetCell("project.hooks", assets.length ? "enabled" : "off", assets.length ? "applied" : "disabled", assets, "controlled project hook settings injection", assets.length ? `Committed project hooks reached the launch (${assets.map((item) => item.name).join(", ")}).` : "No committed project hook reached this launch.", [], "trusted"), review: reviewInfo(a, a.profile?.projectGates?.hooks) };
+  }
+  if (settingSourceLoaded(a, "project")) return assetCell("project.hooks", "available", "applied", "ambient", "Claude --setting-sources project", "The project settings hook source loads ambiently; Relay does not govern its execution.", [], "untrusted");
+  return assetCell("project.hooks", "available", "disabled", "off", settingSourceMechanism(a), "The project settings hook source is excluded by the emitted launch shape.", [], "untrusted");
+}
+
+function projectSkills(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const assets = a.projectSkills.map((item) => asset(item.name, "project"));
+  return assetCell("project.skills", assets.length ? "available" : "off", assets.length ? "applied" : "disabled", assets, "committed project skill directories materialized into managed home", assets.length ? `Project skills reached the launch (${assets.map((item) => item.name).join(", ")}).` : "No committed project skill directory reached this launch.", [], "trusted");
+}
+
+function projectPlugins(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (!hasSettingSourceSurface(a)) return assetCell("project.plugins", "available", "not-applicable", "n/a", "provider has no project plugin lever", "This provider has no project plugin surface.", [], "unknown");
+  return assetCell("project.plugins", "available", "not-implemented", "none", "no provider launch lever", "Project plugin provisioning has no provider launch lever yet.", [], "trusted");
+}
+
+function relayInstructions(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (a.relayContextPending || a.launchContextPending) {
+    return scalarCell("agent-relay.instructions", "enabled", "applied", "pending first provider turn", "runner provider-delivery injection", "Relay-authored instructions are available and will be prepended to the first provider turn; no provider turn has been emitted at launch.");
+  }
+  const active = a.relayContext || a.instructions.systemPromptAppend;
+  return scalarCell("agent-relay.instructions", active ? "enabled" : "disabled", active ? "applied" : "disabled", active ? "injected" : "off", "runner context/prompt injection", active ? "Relay-authored instructions reached the provider turn." : "No Relay-authored instruction material was emitted.");
+}
+
+function relayMcp(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const assets = [
+    ...(a.mcp.relayEndpoint ? [asset(mcpServerInfo(a.mcp.generation ?? "relay").name, "reserved")] : []),
+    ...a.mcp.servers.map((name) => asset(name, relayProvenance(a, "mcp", name))),
+  ];
+  return assetCell("agent-relay.mcp", assets.length ? "enabled" : "disabled", assets.length ? "applied" : "disabled", assets, "Relay MCP endpoint / controlled MCP config", assets.length ? `Relay MCP assets reached the launch (${assets.map((item) => item.name).join(", ")}).` : "No Relay MCP asset reached this launch.", relayShadows(a, "mcp", assets), "trusted");
+}
+
+function relayHooks(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (a.hooksSuppressed?.names.length) return assetCell("agent-relay.hooks", "enabled", "partial", [], "hook delivery withheld", `Relay hooks were resolved but suppressed: ${a.hooksSuppressed.reason}.`, [], "trusted");
+  const assets = a.hooks.map((item) => asset(item.name, relayProvenance(a, "hook", item.name)));
+  return assetCell("agent-relay.hooks", assets.length ? "enabled" : "disabled", assets.length ? "applied" : "disabled", assets, "provider hook settings/hooks.json", assets.length ? `Relay hooks reached the launch (${assets.map((item) => item.name).join(", ")}).` : "No Relay hook reached this launch.", relayShadows(a, "hook", assets), "trusted");
+}
+
+function relaySkills(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const assets = [
+    ...(a.relaySkills ? [asset("agent-relay", "bundled")] : []),
+    ...a.skills.map((item) => asset(item.name, relayProvenance(a, "skill", item.name))),
+  ];
+  return assetCell("agent-relay.skills", assets.length ? "enabled" : "disabled", assets.length ? "applied" : "disabled", assets, "bundled skills config / Relay plugin", assets.length ? `Relay skill assets reached the launch (${assets.map((item) => item.name).join(", ")}).` : "No Relay skill asset reached this launch.", relayShadows(a, "skill", assets), "trusted");
+}
+
+function relayPlugins(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const assets = [
+    ...(a.relayPlugin ? [asset(getManifest(a.provider)?.provisioning?.bundledPlugin?.ref ?? "agent-relay", "bundled")] : []),
+    ...a.plugins.map((item) => asset(item.name, relayProvenance(a, "plugin", item.name))),
+  ];
+  return assetCell("agent-relay.plugins", assets.length ? "enabled" : "disabled", assets.length ? "applied" : "disabled", assets, "provider plugin-dir launch args", assets.length ? `Relay plugin assets reached the launch (${assets.map((item) => item.name).join(", ")}).` : "No Relay plugin asset reached this launch.", relayShadows(a, "plugin", assets), "trusted");
+}
+
+function relayStatusLineEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  return scalarCell("relay.statusLine", a.statusLine ? "enabled" : "disabled", a.statusLine ? "applied" : "disabled", a.statusLine ? "enabled" : "off", "Claude --settings statusLine", a.statusLine ? "Relay status-line settings reached the launch." : "Relay status-line settings were not emitted.");
+}
+
+function configHomeEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  return scalarCell("provider.configHome", a.configHome ? "isolated" : "host", "applied", a.configHome ? "isolated" : "host", a.configHome ? "CLAUDE_CONFIG_DIR/CODEX_HOME" : "provider default config home", a.configHome ? `The launch uses the managed isolated config home ${a.configHome}.` : "The launch uses the provider's host config home.");
+}
+
+function launchShapeEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  // #2367 — argv can contain the full system prompt and inlined config. The old cell copied that
+  // string into requested, effective, and detail, turning a ~68 KiB launch into ~203 KiB of static
+  // agent meta that every status frame then carried through a read/merge/stringify/write cycle.
+  // The projection is diagnostic, not the launch authority: retain its useful shape/size facts and
+  // keep the actual argv solely in the assembled launch that the adapter consumes.
+  const bytes = new TextEncoder().encode(JSON.stringify(a.args)).byteLength;
+  const summary = a.args.length ? `${a.args.length} argv entries (${bytes} bytes)` : "provider defaults (0 argv entries)";
+  return scalarCell("provider.launchShape", "assembled", "applied", summary, "provider launch arguments emitted by assembler", `The assembler emitted ${summary}. Argument values stay in the launch artifact, not the agent profile projection.`);
+}
+
+function localSettingsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (!hasSettingSourceSurface(a)) return scalarCell("local.settings", "n/a", "not-applicable", "n/a", "provider has no local settings surface", "This provider has no Claude local settings surface.");
+  if (settingSourceLoaded(a, "local")) return scalarCell("local.settings", "ambient", "applied", "ambient", "Claude --setting-sources local", "Local settings load ambiently and are not part of the profile matrix.", "untrusted");
+  return scalarCell("local.settings", "off", "disabled", "off", settingSourceMechanism(a), "The local settings source is excluded by the emitted launch shape.", "untrusted");
+}
+
+function filesystemEntry(profile: AgentProfile | undefined): AgentProfileProjectionEntry {
+  const requested = profile?.permissions.filesystem ?? "host";
+  if (requested === "host") return scalarCell("permissions.filesystem", requested, "applied", "host", "orchestrator cwd containment", "No provider-level filesystem sandbox was requested.");
+  return scalarCell("permissions.filesystem", requested, "partial", requested, "orchestrator cwd containment", "Relay constrains the spawn cwd; provider-level filesystem projection is incomplete.");
+}
+
+function envEntry(profile: AgentProfile | undefined): AgentProfileProjectionEntry {
+  const count = Object.keys(profile?.env ?? {}).length;
+  return scalarCell("env", count ? `${count} vars` : "none", "applied", count ? `${count} vars` : "none", "runner environment", count ? "Profile environment variables reached the runner." : "No profile environment variables were requested.");
+}
+
+function nativeMemoryEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const lever = a.nativeMemory;
+  if (lever.suppressed) {
+    const effective = lever.applied.length ? lever.applied.join(", ") : "provider default (on)";
+    return scalarCell("nativeMemory", lever.policy, "partial", effective, "native-memory launch lever withheld", `Native-memory policy ${lever.policy} was only partially delivered; suppressed ${lever.suppressed.levers.join(", ")}: ${lever.suppressed.reason}.`);
+  }
+  if (lever.policy === "default") return scalarCell("nativeMemory", "absent", "not-applicable", "provider default", "no native-memory flag", `No native-memory policy was emitted; ${a.provider}'s native memory keeps its default.`);
+  const effective = lever.applied.length ? lever.applied.join(", ") : "provider default (on)";
+  return scalarCell("nativeMemory", lever.policy, "applied", effective, "native-memory launch lever", `Native-memory policy ${lever.policy} reached the launch (${effective}).`);
+}
+
+function sharedMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const listener = a.mcp.sharedListener;
+  if (!listener) return scalarCell("sharedMcp", "off", "not-applicable", "off", "no shared listener", "Shared host-listener MCP is off for this launch.");
+  const route = listener.metaOnly
+    ? `callmux --config <home>/${SHARED_MCP_METAONLY_CONFIG_FILENAME}`
+    : `callmux bridge --cwd "$WORKTREE"`;
+  const relayNote = listener.relayFronted ? " Relay's identity endpoint is also fronted on-demand through the runner proxy." : " Relay's identity endpoint stays per-agent.";
+  return scalarCell("sharedMcp", "on", "applied", "on", route, `Shared MCP routes through ${listener.url} via ${route}.${relayNote}`);
+}
+
+function provisioningEntries(a: AssembledLaunch): AgentProfileProjectionEntry[] {
+  const entries: AgentProfileProjectionEntry[] = [];
+  for (const item of a.skills) entries.push(assetCell(`provisioning.skill.${item.name}`, "enabled", "applied", [asset(item.name, relayProvenance(a, "skill", item.name))], "provider skill launch", `Provisioned skill ${item.name} reached the launch.`));
+  for (const item of a.plugins) entries.push(assetCell(`provisioning.plugin.${item.name}`, "enabled", "applied", [asset(item.name, relayProvenance(a, "plugin", item.name))], "provider plugin-dir launch", `Provisioned plugin ${item.name} reached the launch.`));
+  for (const item of a.hooks) entries.push(assetCell(`provisioning.hook.${item.name}`, "enabled", "applied", [asset(item.name, relayProvenance(a, "hook", item.name))], "provider hook settings/hooks.json", `Provisioned hook ${item.name} reached the launch.`));
+  for (const name of a.mcp.servers) entries.push(assetCell(`provisioning.mcp.${name}`, "enabled", "applied", [asset(name, relayProvenance(a, "mcp", name))], "controlled MCP config", `Provisioned MCP server ${name} reached the launch.`));
+  for (const item of a.profile?.provisioning?.skipped ?? []) entries.push(scalarCell(`provisioning.${item.kind}.${item.ref}`, item.reason, "partial", "suppressed", "provider variant resolution", item.detail));
+  return entries;
+}
+
+function scalarCell(capability: string, requested: string, result: AgentProfileProjectionEntry["result"], effective: string, mechanism: string, detail: string, trust?: AgentProfileProjectionTrust): AgentProfileProjectionEntry {
+  return { capability, requested, result, effective, mechanism, ...(trust ? { trust } : {}), detail };
+}
+
+function assetCell(capability: string, requested: string, result: AgentProfileProjectionEntry["result"], effective: string | AgentProfileProjectionAsset[], mechanism: string, detail: string, shadowed: AgentProfileProjectionAsset[] = [], trust?: AgentProfileProjectionTrust): AgentProfileProjectionEntry {
+  return { capability, requested, result, effective, mechanism, ...(shadowed.length ? { shadowed } : {}), ...(trust ? { trust } : {}), detail };
+}
+
+function asset(name: string, provenance: string): AgentProfileProjectionAsset {
+  return { name, provenance };
+}
+
+function hasSettingSourceSurface(a: AssembledLaunch): boolean {
+  return Boolean(getManifest(a.provider)?.provisioning?.bundledPlugin);
+}
+
+function settingSourceLoaded(a: AssembledLaunch, scope: string): boolean {
+  return !a.settingSources || a.settingSources.includes(scope);
+}
+
+function settingSourceMechanism(a: AssembledLaunch): string {
+  return `Claude --setting-sources ${(a.settingSources ?? ["user", "project", "local"]).join(",")}`;
+}
+
+function projectInstructionMechanism(a: AssembledLaunch): string {
+  if (a.settingSources) return settingSourceMechanism(a);
+  return a.vanilla ? "provider vanilla project-doc suppression" : "provider default project instruction cascade";
+}
+
+type ProvenanceTier = "reserved" | "registry" | "bundled";
+interface RelaySourceKindTiers { reserved: string[]; registry: string[]; bundled: string[] }
+
+function relayRegistryRefs(refs: AgentProfile["skills"] | undefined): string[] {
+  return (refs ?? []).filter((ref) => ref.source === "relay" && ref.enabled).map((ref) => ref.ref);
+}
+
+function relaySourceKindTiers(a: AssembledLaunch): Record<"skill" | "plugin" | "hook" | "mcp", RelaySourceKindTiers> {
+  const profile = a.profile;
+  const provisioning = getManifest(a.provider)?.provisioning;
+  const bundledHooks = provisioning?.bundledHooks ?? [];
+  const skippedMcpRefs = new Set(
+    (profile?.provisioning?.skipped ?? [])
+      .filter((item) => item.kind === "mcp")
+      .map((item) => item.ref),
+  );
+  const mcpRegistry = Object.values(profile?.mcp.servers ?? {})
+    .filter((value): value is { source: string; ref: string } => isRecord(value) && value.source === "relay" && typeof value.ref === "string" && !skippedMcpRefs.has(value.ref))
+    .map((value) => value.ref);
+  return {
+    skill: { reserved: [], registry: relayRegistryRefs(profile?.skills), bundled: a.relaySkills ? ["agent-relay"] : [] },
+    plugin: { reserved: [], registry: relayRegistryRefs(profile?.plugins), bundled: a.relayPlugin && provisioning?.bundledPlugin ? [provisioning.bundledPlugin.ref] : [] },
+    hook: { reserved: bundledHooks.filter((hook) => hook.baseline).map((hook) => hook.ref), registry: relayRegistryRefs(profile?.hooks?.refs), bundled: bundledHooks.filter((hook) => !hook.baseline).map((hook) => hook.ref) },
+    mcp: { reserved: a.mcp.relayEndpoint ? [RELAY_MCP_SERVER_NAME] : [], registry: mcpRegistry, bundled: [] },
+  };
+}
+
+function relayProvenance(a: AssembledLaunch, kind: "skill" | "plugin" | "hook" | "mcp", name: string): string {
+  const tiers = relaySourceKindTiers(a)[kind];
+  if (tiers.reserved.includes(name)) return "reserved";
+  const ref = profileAssetRef(a, kind, name);
+  // MCP registry entries are keyed by the profile-facing server name, while the
+  // registry tier is keyed by the canonical ref. Preserve that ref when the
+  // effective server uses an alias.
+  if (ref?.source === "relay") {
+    return tiers.registry.includes(ref.ref) ? `registry:${ref.ref}` : "unknown";
+  }
+  if (tiers.registry.includes(name)) return `registry:${name}`;
+  if (tiers.bundled.includes(name)) return "bundled";
+  if (ref?.source && ref.source !== "relay") return ref.source;
+  return "unknown";
+}
+
+function profileAssetRef(a: AssembledLaunch, kind: "skill" | "plugin" | "hook" | "mcp", name: string): { source: string; ref: string } | undefined {
+  if (kind === "mcp") {
+    const value = a.profile?.mcp.servers?.[name];
+    return isRecord(value) && typeof value.source === "string" && typeof value.ref === "string"
+      ? { source: value.source, ref: value.ref }
+      : undefined;
+  }
+  const refs = kind === "skill"
+    ? a.profile?.skills
+    : kind === "plugin"
+      ? a.profile?.plugins
+      : a.profile?.hooks.refs;
+  const ref = refs?.find((candidate) => candidate.enabled && candidate.ref === name);
+  return ref ? { source: ref.source, ref: ref.ref } : undefined;
+}
+
+function relayShadows(a: AssembledLaunch, kind: "skill" | "plugin" | "hook" | "mcp", effective: AgentProfileProjectionAsset[]): AgentProfileProjectionAsset[] {
+  const tiers = relaySourceKindTiers(a)[kind];
+  const rank: Record<ProvenanceTier, number> = { reserved: 0, registry: 1, bundled: 2 };
+  const winner = new Map<string, ProvenanceTier>();
+  for (const tier of ["reserved", "registry", "bundled"] as const) for (const name of tiers[tier]) {
+    const existing = winner.get(name);
+    if (existing === undefined || rank[tier] < rank[existing]) winner.set(name, tier);
+  }
+  const out: AgentProfileProjectionAsset[] = [];
+  for (const tier of ["reserved", "registry", "bundled"] as const) for (const name of tiers[tier]) {
+    if (winner.get(name) !== tier && effective.some((item) => item.name === name)) out.push(asset(name, tier === "registry" ? `registry:${name}` : tier));
+  }
+  return out;
+}

package/src/project-hooks.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ProvisioningHookCommand, ProvisioningHookMatcher, ProvisioningHookSet } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+import type { ResolvedHookAsset } from "./provisioning";
+
+function validCommand(value: unknown): value is ProvisioningHookCommand {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const command = (value as Record<string, unknown>).command;
+  return typeof command === "string" && command.trim().length > 0;
+}
+
+export function parseHookSet(value: unknown): ProvisioningHookSet {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const out: ProvisioningHookSet = {};
+  for (const [event, rawMatchers] of Object.entries(value as Record<string, unknown>)) {
+    if (!Array.isArray(rawMatchers)) continue;
+    const matchers: ProvisioningHookMatcher[] = [];
+    for (const rawMatcher of rawMatchers) {
+      if (!rawMatcher || typeof rawMatcher !== "object" || Array.isArray(rawMatcher)) continue;
+      const matcher = rawMatcher as Record<string, unknown>;
+      if (!Array.isArray(matcher.hooks)) continue;
+      const commands = matcher.hooks.filter(validCommand).map((command) => ({
+        ...command,
+        ...(typeof command.timeout === "number" ? { timeout: command.timeout } : {}),
+        ...(typeof command.statusMessage === "string" ? { statusMessage: command.statusMessage } : {}),
+        ...(typeof command.suppressOutput === "boolean" ? { suppressOutput: command.suppressOutput } : {}),
+      }));
+      if (!commands.length) continue;
+      matchers.push({
+        ...(typeof matcher.matcher === "string" ? { matcher: matcher.matcher } : {}),
+        hooks: commands,
+      });
+    }
+    if (matchers.length) out[event] = matchers;
+  }
+  return out;
+}
+
+/** Resolve the committed project `.claude/settings.json` hook surface. The
+ * source is tagged as `project` so reports/materializers can distinguish it from
+ * Relay-owned hooks. Trust decisions are server-stamped on the in-flight profile;
+ * missing decisions fail closed. */
+export function resolveProjectHooks(config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">): ResolvedHookAsset[] {
+  const profile = config.agentProfile;
+  if (!profile?.sources?.project?.hooks?.enabled) return [];
+  if (!profile.projectGates?.hooks?.allowed) return [];
+  const file = join(config.cwd, ".claude", "settings.json");
+  if (!existsSync(file)) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return [];
+  }
+  const hooks = parseHookSet((parsed as Record<string, unknown> | null)?.hooks);
+  if (!Object.keys(hooks).length) return [];
+  return [{
+    name: "project-hooks",
+    dir: join(config.cwd, ".claude"),
+    source: { kind: "inPlace" },
+    provenance: "project",
+    hooks,
+  }];
+}

package/src/project-instructions.ts

@@ -0,0 +1,119 @@
+import { sanitizeLaunchText } from "@humwick/sdk";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import type { RunnerSpawnConfig } from "./adapter";
+import { projectSettingSourcesOn } from "./profile-home";
+
+// The repo instruction docs Claude's native project cascade loads from the spawn cwd
+// (walking is Claude's job; the profile matrix governs only whether the scope loads).
+// Codex's sibling is AGENTS.md via project_doc — but Codex has no P.hooks→scope-drop
+// interference (only a vanilla base suppresses its project doc), so this resolver is
+// the Claude re-injection channel and lists both names the cwd may carry.
+const REPO_INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"] as const;
+
+// Bound each re-injected file so a pathological repo doc can't balloon the launch argv
+// (append-system-prompt rides the command line). Mirrors the spirit of Codex's
+// project_doc_max_bytes default; oversized content is truncated with a loud marker
+// rather than silently dropped.
+const REPO_INSTRUCTIONS_MAX_BYTES = 64 * 1024;
+
+export interface ResolvedProjectInstructions {
+  /** The composed append-system-prompt block, ready to fold into the launch. */
+  text: string;
+  /** The repo instruction filenames that actually contributed (for the report). */
+  files: string[];
+}
+
+export interface ComposedSystemPromptAppend {
+  /** The caller's systemPromptAppend and any re-injected repo instructions, joined. */
+  text: string;
+  /** Whether repo instructions were re-injected (drives the launch's repo disposition). */
+  reinjected: boolean;
+}
+
+/**
+ * Fold the caller's `systemPromptAppend` together with any #2086 repo re-injection into the single
+ * `--append-system-prompt` value the launch emits. The two channels are distinct in reporting
+ * (relay-authored append vs. repo-doc re-injection), so `reinjected` is returned separately.
+ */
+export function composeSystemPromptAppend(config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd" | "systemPromptAppend">): ComposedSystemPromptAppend {
+  const reinjected = resolveProjectInstructions(config);
+  const text = [config.systemPromptAppend && sanitizeLaunchText(config.systemPromptAppend, "systemPromptAppend"), reinjected?.text]
+    .filter((part): part is string => Boolean(part && part.trim()))
+    .join("\n\n");
+  return { text, reinjected: Boolean(reinjected) };
+}
+
+/**
+ * #2086 — the instructions sibling of {@link resolveProjectHooks}. When `P.hooks` is
+ * named, the runner drops the ENTIRE native project setting-source scope so ambient repo
+ * hooks can never bypass the trust gate (profile-home `projectSettingSourcesOn`). That drop
+ * also strips the repo CLAUDE.md/AGENTS.md cascade even when `P.instructions` is on, silently
+ * defeating it. This resolver re-injects those repo docs through Relay's controlled channel
+ * (append-system-prompt) so `P.instructions=on` is honored regardless of `P.hooks`.
+ *
+ * Unlike hooks (executing surfaces gated by `projectGates`), repo instructions are inert
+ * text that already loaded ambiently whenever the project scope was present — so re-injection
+ * carries no new trust decision and needs no gate. It fires ONLY when the scope is dropped, so
+ * a launch that still loads the project scope natively never double-injects.
+ */
+export function resolveProjectInstructions(config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">): ResolvedProjectInstructions | undefined {
+  if (!projectInstructionsReinjected(config)) return undefined;
+  if (!config.cwd) return undefined;
+  const blocks: string[] = [];
+  const files: string[] = [];
+  // Dedupe by realpath (AGENTS.md -> CLAUDE.md) and by content (a plain copy).
+  const seenReal = new Map<string, string>();
+  const seenContent = new Map<string, string>();
+  for (const name of REPO_INSTRUCTION_FILES) {
+    const file = join(config.cwd, name);
+    if (!existsSync(file)) continue;
+    let content: string;
+    try {
+      const real = realpathSync(file);
+      const sameFile = seenReal.get(real);
+      if (sameFile) {
+        files.push(`${name} (same as ${sameFile})`);
+        continue;
+      }
+      seenReal.set(real, name);
+      content = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    if (!content.trim()) continue;
+    const sameContent = seenContent.get(content);
+    if (sameContent) {
+      files.push(`${name} (same as ${sameContent})`);
+      continue;
+    }
+    seenContent.set(content, name);
+    blocks.push(renderRepoInstructionBlock(name, sanitizeLaunchText(content, name)));
+    files.push(name);
+  }
+  if (!blocks.length) return undefined;
+  return { text: `${REPO_INSTRUCTIONS_PREAMBLE}\n\n${blocks.join("\n\n")}`, files };
+}
+
+/**
+ * Whether this launch must re-inject the repo instruction docs — i.e. `P.instructions` is
+ * enabled but the native project scope is dropped (today only `P.hooks=on` forces that). Kept
+ * general (`!projectSettingSourcesOn`) so it stays correct if the scope-drop set ever widens.
+ */
+export function projectInstructionsReinjected(config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">): boolean {
+  if (!config.agentProfile?.sources?.project?.instructions?.enabled) return false;
+  return !projectSettingSourcesOn(config);
+}
+
+const REPO_INSTRUCTIONS_PREAMBLE =
+  "[agent-relay] The repository instruction docs below are re-injected by Relay because the " +
+  "native project setting-source scope was dropped to gate ambient project hooks. Follow them " +
+  "as the repository's CLAUDE.md/AGENTS.md guidance.";
+
+function renderRepoInstructionBlock(name: string, content: string): string {
+  const bytes = Buffer.byteLength(content, "utf8");
+  const body = bytes > REPO_INSTRUCTIONS_MAX_BYTES
+    ? `${Buffer.from(content, "utf8").subarray(0, REPO_INSTRUCTIONS_MAX_BYTES).toString("utf8")}\n[agent-relay: ${name} truncated at ${REPO_INSTRUCTIONS_MAX_BYTES} bytes]`
+    : content.replace(/\s+$/, "");
+  return `<repo-instructions source="${name}">\n${body}\n</repo-instructions>`;
+}