agent-relay-runner 0.10.19 → 0.10.21

package/src/index.ts

@@ -1,58 +1,99 @@
 #!/usr/bin/env bun
+import { hostname } from "node:os";
 import { basename } from "node:path";
 import { isatty } from "node:tty";
 import { ClaudeAdapter } from "./adapters/claude";
 import { CodexAdapter } from "./adapters/codex";
 import { AgentRunner } from "./runner";
 import { loadGlobalConfig, loadProviderConfig, resolveCwd, runnerId } from "./config";
+import { VERSION } from "./version";
+import type { AgentProfile, WorkspaceMetadata } from "agent-relay-sdk";
 
 interface CliOptions {
   provider: "claude" | "codex";
+  model?: string;
+  effort?: string;
   headless: boolean;
   interactive: boolean;
   cwd?: string;
   rig?: string;
+  profile?: string;
   relayUrl?: string;
   token?: string;
   approvalMode?: string;
   label?: string;
   agentId?: string;
   prompt?: string;
+  systemPromptAppend?: string;
   tags: string[];
   caps: string[];
   providerArgs: string[];
 }
 
 export async function main(argv = process.argv): Promise<void> {
+  if (isVersionRequest(argv)) {
+    console.log(VERSION);
+    return;
+  }
   const opts = parseArgs(argv);
   const globalConfig = loadGlobalConfig();
   const providerConfig = loadProviderConfig(opts.provider);
   const cwd = resolveCwd(opts.cwd, globalConfig.defaultCwd);
   const id = runnerId(opts.provider, cwd, opts.label);
   const adapter = opts.provider === "claude" ? new ClaudeAdapter() : new CodexAdapter();
+  const relayUrl = opts.relayUrl ?? globalConfig.relayUrl;
+  const runtimeAuth = await resolveRunnerToken({
+    interactive: opts.interactive,
+    relayUrl,
+    token: opts.token ?? globalConfig.token,
+    runtimeTokenProfile: process.env.AGENT_RELAY_TOKEN_PROFILE,
+    runtimeTokenJti: process.env.AGENT_RELAY_TOKEN_JTI,
+    runtimeTokenExpiresAt: parseTokenExpiresAt(process.env.AGENT_RELAY_TOKEN_EXPIRES_AT),
+    provider: opts.provider,
+    cwd,
+    runnerId: id,
+    agentId: opts.agentId ?? id,
+    label: opts.label,
+  });
 
   let exitResolve: (code: number) => void;
   const exitPromise = new Promise<number>((resolve) => { exitResolve = resolve; });
 
+  const approvalMode = opts.approvalMode
+    ?? detectApprovalModeFromArgs(opts.provider, providerConfig.defaultArgs, opts.providerArgs)
+    ?? providerConfig.defaultApprovalMode;
+
   const runner = new AgentRunner({
     provider: opts.provider,
+    model: opts.model,
+    effort: opts.effort,
     runnerId: id,
     instanceId: crypto.randomUUID(),
     agentId: opts.agentId,
-    relayUrl: opts.relayUrl ?? globalConfig.relayUrl,
-    token: opts.token ?? globalConfig.token,
+    relayUrl,
+    token: runtimeAuth.token,
+    tokenJti: runtimeAuth.jti,
+    tokenProfileId: runtimeAuth.profileId,
+    tokenExpiresAt: runtimeAuth.expiresAt,
+    rootTokenFallback: runtimeAuth.rootFallback,
     cwd,
     headless: opts.headless,
-    approvalMode: opts.approvalMode ?? providerConfig.defaultApprovalMode,
+    approvalMode,
     label: opts.label,
     rig: opts.rig,
+    profile: opts.profile ?? process.env.AGENT_RELAY_AGENT_PROFILE,
+    agentProfile: parseAgentProfileEnv(process.env.AGENT_RELAY_AGENT_PROFILE_JSON),
+    workspace: parseWorkspaceEnv(process.env.AGENT_RELAY_WORKSPACE_JSON),
     prompt: opts.prompt,
+    systemPromptAppend: opts.systemPromptAppend,
+    tmuxSession: process.env.AGENT_RELAY_TMUX_SESSION,
     tags: opts.tags,
     capabilities: opts.caps,
     providerArgs: opts.providerArgs,
     policyName: process.env.AGENT_RELAY_POLICY,
     spawnRequestId: process.env.AGENT_RELAY_SPAWN_REQUEST_ID,
-    tmuxSession: process.env.AGENT_RELAY_TMUX_SESSION,
+    automationId: process.env.AGENT_RELAY_AUTOMATION_ID,
+    automationRunId: process.env.AGENT_RELAY_AUTOMATION_RUN_ID,
     startedAt: Date.now(),
     providerConfig,
     adapter,
@@ -65,6 +106,108 @@ export async function main(argv = process.argv): Promise<void> {
   process.exit(code);
 }
 
+export async function resolveRunnerToken(input: {
+  interactive: boolean;
+  relayUrl: string;
+  token?: string;
+  runtimeTokenProfile?: string;
+  runtimeTokenJti?: string;
+  runtimeTokenExpiresAt?: number;
+  provider: string;
+  cwd: string;
+  runnerId: string;
+  agentId: string;
+  label?: string;
+}): Promise<{ token?: string; jti?: string; profileId?: string; expiresAt?: number; rootFallback?: boolean }> {
+  if (!input.token) return {};
+  const claims = decodeComponentTokenClaims(input.token);
+  if (input.runtimeTokenProfile) {
+    return {
+      token: input.token,
+      jti: input.runtimeTokenJti ?? claims?.jti,
+      profileId: input.runtimeTokenProfile,
+      expiresAt: input.runtimeTokenExpiresAt ?? claims?.exp,
+    };
+  }
+  const inferredRuntime = inferRuntimeTokenMetadata(claims);
+  if (!input.interactive && inferredRuntime) return { token: input.token, ...inferredRuntime };
+  if (!input.interactive) return { token: input.token };
+
+  try {
+    const url = new URL("/api/runtime-tokens/interactive-runner", input.relayUrl);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Agent-Relay-Token": input.token,
+      },
+      body: JSON.stringify({
+        provider: input.provider,
+        cwd: input.cwd,
+        runnerId: input.runnerId,
+        agentId: input.agentId,
+        label: input.label,
+        host: hostname(),
+      }),
+      signal: AbortSignal.timeout(5_000),
+    });
+    const body = await res.json().catch(() => null) as { token?: string; record?: { jti?: string; profileId?: string; expiresAt?: number }; error?: string } | null;
+    if (res.ok && body?.token) return { token: body.token, jti: body.record?.jti, profileId: body.record?.profileId ?? "provider-interactive", expiresAt: body.record?.expiresAt };
+    const detail = body?.error ? `: ${body.error}` : "";
+    console.warn(`[agent-relay] interactive scoped-token exchange failed (${res.status}${detail}); continuing with existing token. Root-token runtime fallback is deprecated.`);
+  } catch (error) {
+    console.warn(`[agent-relay] interactive scoped-token exchange failed (${error instanceof Error ? error.message : String(error)}); continuing with existing token. Root-token runtime fallback is deprecated.`);
+  }
+  return { token: input.token, rootFallback: true };
+}
+
+function decodeComponentTokenClaims(token: string | undefined): { sub?: string; role?: string; exp?: number; jti?: string } | undefined {
+  const payload = token?.split(".")[1];
+  if (!payload) return undefined;
+  try {
+    const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const decoded = JSON.parse(Buffer.from(normalized, "base64").toString("utf8")) as Record<string, unknown>;
+    const exp = typeof decoded.exp === "number" && Number.isSafeInteger(decoded.exp) && decoded.exp > 0 ? decoded.exp : undefined;
+    return {
+      ...(typeof decoded.sub === "string" ? { sub: decoded.sub } : {}),
+      ...(typeof decoded.role === "string" ? { role: decoded.role } : {}),
+      ...(typeof decoded.jti === "string" ? { jti: decoded.jti } : {}),
+      ...(exp ? { exp } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function inferRuntimeTokenMetadata(claims: { sub?: string; role?: string; exp?: number; jti?: string } | undefined): { jti?: string; profileId?: string; expiresAt?: number } | undefined {
+  if (claims?.role !== "provider" || !claims.exp) return undefined;
+  const sub = claims.sub ?? "";
+  const profileId = sub.startsWith("runner:interactive:")
+    ? "provider-interactive"
+    : sub.startsWith("runner:spawn:") || sub.startsWith("runner:policy:") || /^runner:(codex|claude|provider):/.test(sub)
+      ? "provider-agent"
+      : undefined;
+  if (!profileId) return undefined;
+  return {
+    ...(claims.jti ? { jti: claims.jti } : {}),
+    profileId,
+    expiresAt: claims.exp,
+  };
+}
+
+function parseTokenExpiresAt(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function isVersionRequest(argv: string[]): boolean {
+  const relayArgs = argv.slice(2);
+  const providerSep = relayArgs.indexOf("--");
+  const ownArgs = providerSep >= 0 ? relayArgs.slice(0, providerSep) : relayArgs;
+  return ownArgs.some((arg) => arg === "--version" || arg === "-v");
+}
+
 function parseArgs(argv: string[]): CliOptions {
   const bin = [argv[1], process.env._].map((s) => basename(s || "")).join(" ");
   let provider: "claude" | "codex" = bin.includes("claude") ? "claude" : "codex";
@@ -73,14 +216,18 @@ function parseArgs(argv: string[]): CliOptions {
   const ownArgs = providerSep >= 0 ? relayArgs.slice(0, providerSep) : relayArgs;
   const providerArgs = providerSep >= 0 ? relayArgs.slice(providerSep + 1) : [];
   let headless = false;
+  let model: string | undefined;
+  let effort: string | undefined;
   let cwd: string | undefined;
   let rig: string | undefined;
+  let profile: string | undefined;
   let relayUrl: string | undefined;
   let token: string | undefined;
   let approvalMode: string | undefined;
   let label: string | undefined;
   let agentId: string | undefined;
   let prompt: string | undefined;
+  let systemPromptAppend: string | undefined;
   let tags: string[] = [];
   let caps: string[] = [];
 
@@ -88,14 +235,18 @@ function parseArgs(argv: string[]): CliOptions {
     const arg = ownArgs[i];
     if (arg === "claude" || arg === "codex") provider = arg;
     else if (arg === "--headless") headless = true;
+    else if (arg === "--model" && ownArgs[i + 1]) model = ownArgs[++i];
+    else if (arg === "--effort" && ownArgs[i + 1]) effort = ownArgs[++i];
     else if (arg === "--cwd" && ownArgs[i + 1]) cwd = ownArgs[++i];
     else if (arg === "--rig" && ownArgs[i + 1]) rig = ownArgs[++i];
+    else if (arg === "--profile" && ownArgs[i + 1]) profile = ownArgs[++i];
     else if (arg === "--relay-url" && ownArgs[i + 1]) relayUrl = ownArgs[++i];
     else if (arg === "--token" && ownArgs[i + 1]) token = ownArgs[++i];
     else if ((arg === "--approval" || arg === "--approval-mode") && ownArgs[i + 1]) approvalMode = ownArgs[++i];
     else if (arg === "--label" && ownArgs[i + 1]) label = ownArgs[++i];
     else if (arg === "--agent-id" && ownArgs[i + 1]) agentId = ownArgs[++i];
     else if (arg === "--prompt" && ownArgs[i + 1]) prompt = ownArgs[++i];
+    else if ((arg === "--system-prompt-append" || arg === "--append-system-prompt") && ownArgs[i + 1]) systemPromptAppend = ownArgs[++i];
     else if (arg === "--tags" && ownArgs[i + 1]) tags = csvSplit(ownArgs[++i]!);
     else if (arg === "--caps" && ownArgs[i + 1]) caps = csvSplit(ownArgs[++i]!);
     else if (arg === "--help" || arg === "-h") {
@@ -107,15 +258,35 @@ function parseArgs(argv: string[]): CliOptions {
   }
 
   const interactive = !headless && isatty(0);
-  return { provider, headless, interactive, cwd, rig, relayUrl, token, approvalMode, label, agentId, prompt, tags, caps, providerArgs };
+  return { provider, model, effort, headless, interactive, cwd, rig, profile, relayUrl, token, approvalMode, label, agentId, prompt, systemPromptAppend, tags, caps, providerArgs };
 }
 
 function csvSplit(value: string): string[] {
   return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
 
+function parseAgentProfileEnv(raw: string | undefined): AgentProfile | undefined {
+  if (!raw) return undefined;
+  try {
+    const parsed = JSON.parse(raw) as Partial<AgentProfile>;
+    return parsed && typeof parsed === "object" && typeof parsed.name === "string" ? parsed as AgentProfile : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseWorkspaceEnv(raw: string | undefined): WorkspaceMetadata | undefined {
+  if (!raw) return undefined;
+  try {
+    const parsed = JSON.parse(raw) as Partial<WorkspaceMetadata>;
+    return parsed && typeof parsed === "object" && typeof parsed.mode === "string" ? parsed as WorkspaceMetadata : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function printHelp(provider: string): void {
-  console.log(`${provider}-relay [--headless] [--rig NAME] [--cwd PATH] [--relay-url URL] [--approval MODE] [--label NAME] [--agent-id ID] [--tags a,b] [--caps x,y] [-- provider-args...]`);
+  console.log(`${provider}-relay [--headless] [--model ALIAS] [--effort LEVEL] [--rig NAME] [--profile NAME] [--cwd PATH] [--relay-url URL] [--approval MODE] [--label NAME] [--agent-id ID] [--prompt TEXT] [--system-prompt-append TEXT] [--tags a,b] [--caps x,y] [-- provider-args...]`);
 }
 
 function signalPromise(): Promise<number> {
@@ -125,6 +296,32 @@ function signalPromise(): Promise<number> {
   });
 }
 
+export function detectApprovalModeFromArgs(provider: string, defaultArgs: string[], providerArgs: string[]): string | undefined {
+  const allArgs = [...defaultArgs, ...providerArgs];
+  if (provider === "claude") {
+    if (allArgs.includes("--dangerously-skip-permissions")) return "open";
+    const modeIdx = allArgs.lastIndexOf("--permission-mode");
+    if (modeIdx >= 0) {
+      const mode = allArgs[modeIdx + 1];
+      if (mode === "dontAsk") return "read-only";
+      if (mode === "default") return "guarded";
+    }
+    return undefined;
+  }
+  if (provider === "codex") {
+    if (allArgs.includes("--yolo")) return "open";
+    for (let i = 0; i < allArgs.length; i++) {
+      if (allArgs[i] === "-c" || allArgs[i] === "--config") {
+        const value = allArgs[i + 1] ?? "";
+        if (/sandbox_mode\s*=\s*"?danger-full-access"?/.test(value)) return "open";
+        if (/sandbox_mode\s*=\s*"?read-only"?/.test(value)) return "read-only";
+      }
+    }
+    return undefined;
+  }
+  return undefined;
+}
+
 if (import.meta.main) {
   await main();
 }

package/src/profile-home.ts

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
+import { CLAUDE_RELAY_MANUAL } from "./relay-instructions";
+
+type ProviderHome = {
+  path: string;
+  authLinked: string[];
+};
+
+export function profileUsesHostProviderGlobals(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return !config.agentProfile || config.agentProfile.base === "host";
+}
+
+function profileRequiresIsolatedHome(config: RunnerSpawnConfig): boolean {
+  return Boolean(config.agentProfile && config.agentProfile.base !== "host");
+}
+
+export function prepareCodexProfileHome(config: RunnerSpawnConfig): ProviderHome | undefined {
+  if (!profileRequiresIsolatedHome(config)) return undefined;
+  const target = providerHomePath("codex", config);
+  mkdirSync(target, { recursive: true });
+  trustCodexProjectIfAllowed(target, config);
+  const sourceHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  const authLinked = linkExistingAuthItems(sourceHome, target, ["auth.json", "installation_id"]);
+  return { path: target, authLinked };
+}
+
+export function prepareClaudeProfileHome(config: RunnerSpawnConfig): ProviderHome | undefined {
+  if (!profileRequiresIsolatedHome(config)) return undefined;
+  const target = providerHomePath("claude", config);
+  mkdirSync(target, { recursive: true });
+  // Only inject the Relay usage manual when the profile actually wants a Relay
+  // surface. An isolated-research profile (relay.context disabled) must not get
+  // agent-relay communication instructions written into its config home.
+  if (profileAllowsRelayFeature(config, "context")) writeClaudeRelayManual(target);
+  const sourceHome = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+  const authLinked = linkExistingAuthItems(sourceHome, target, [".credentials.json", "statsig"]);
+  return { path: target, authLinked };
+}
+
+function providerHomePath(provider: "claude" | "codex", config: RunnerSpawnConfig): string {
+  const root = process.env.AGENT_RELAY_PROVIDER_HOME_ROOT || join(homedir(), ".agent-relay", "provider-homes");
+  const profileName = sanitizePathPart(config.agentProfile?.name || config.profile || "profile");
+  const instance = sanitizePathPart(config.instanceId || config.runnerId);
+  return join(root, provider, profileName, instance);
+}
+
+function sanitizePathPart(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 120) || "profile";
+}
+
+function linkExistingAuthItems(sourceHome: string, targetHome: string, items: string[]): string[] {
+  const linked: string[] = [];
+  for (const item of items) {
+    const source = join(sourceHome, item);
+    const target = join(targetHome, item);
+    if (!existsSync(source) || existsSync(target)) continue;
+    symlinkSync(source, target);
+    linked.push(item);
+  }
+  return linked;
+}
+
+function trustCodexProjectIfAllowed(codexHome: string, config: RunnerSpawnConfig): void {
+  if (config.agentProfile?.instructions.repoInstructions === "ignore") return;
+  const path = join(codexHome, "config.toml");
+  const project = tomlBasicString(resolve(config.cwd));
+  const section = `[projects.${project}]`;
+  const entry = `${section}\ntrust_level = "trusted"\n`;
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (current.includes(section)) return;
+  const prefix = current.trimEnd();
+  writeFileSync(path, `${prefix ? `${prefix}\n\n` : ""}${entry}`, { mode: 0o600 });
+}
+
+function writeClaudeRelayManual(claudeHome: string): void {
+  const path = join(claudeHome, "CLAUDE.md");
+  writeFileSync(path, CLAUDE_RELAY_MANUAL, { mode: 0o600 });
+}
+
+function tomlBasicString(value: string): string {
+  return JSON.stringify(value);
+}

package/src/profile-projection.ts

@@ -0,0 +1,146 @@
+import type { AgentProfile, AgentProfileProjectionEntry, AgentProfileProjectionReport, SpawnProvider } from "agent-relay-sdk";
+
+interface AgentProfileProjectionInput {
+  provider: SpawnProvider;
+  profile: AgentProfile;
+  generatedAt?: number;
+}
+
+export function agentProfileProjectionReport(input: AgentProfileProjectionInput): AgentProfileProjectionReport {
+  const entries: AgentProfileProjectionEntry[] = [];
+  const add = (entry: AgentProfileProjectionEntry) => entries.push(entry);
+  const { provider, profile } = input;
+  const generatedAt = input.generatedAt ?? Date.now();
+
+  add(relayContextEntry(profile));
+  add(relaySkillsEntry(provider, profile));
+  add(relayPluginsEntry(provider, profile));
+  add(relayStatusLineEntry(provider, profile));
+  add(repoInstructionsEntry(profile));
+  add(globalInstructionsEntry(provider, profile));
+  add(mcpEntry(provider, profile));
+  add(hooksEntry(provider, profile));
+  add(filesystemEntry(profile));
+  add(configHomeEntry(provider, profile));
+  add(envEntry(profile));
+
+  const warnings = entries
+    .filter((entry) => entry.result === "partial" || entry.result === "unsupported")
+    .map((entry) => `${entry.capability}: ${entry.detail}`);
+  const unsupported = entries
+    .filter((entry) => entry.result === "unsupported")
+    .map((entry) => entry.capability);
+
+  return {
+    profileName: profile.name,
+    provider,
+    base: profile.base,
+    generatedAt,
+    entries,
+    warnings,
+    unsupported,
+  };
+}
+
+function relayContextEntry(profile: AgentProfile): AgentProfileProjectionEntry {
+  return profile.relay.context
+    ? applied("relay.context", "enabled", "Relay context is injected before Relay-delivered provider turns.")
+    : applied("relay.context", "disabled", "Relay context injection is disabled by the profile.");
+}
+
+function relaySkillsEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
+  if (provider === "codex") {
+    return profile.relay.skills
+      ? applied("relay.skills", "enabled", "Bundled Agent Relay Codex skills are passed through Codex skills.config.")
+      : applied("relay.skills", "disabled", "Bundled Agent Relay Codex skills are omitted.");
+  }
+  return profile.relay.skills
+    ? applied("relay.skills", "enabled", "Agent Relay Claude skills are available through the bundled Relay plugin.")
+    : applied("relay.skills", "disabled", profile.relay.plugins
+      ? "Claude does not expose an independent Relay skill switch; disabling skills requires disabling the Relay plugin."
+      : "Bundled Agent Relay Claude plugin dirs are omitted, so Relay plugin-provided skills are unavailable.");
+}
+
+function relayPluginsEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
+  if (provider === "claude") {
+    return profile.relay.plugins
+      ? applied("relay.plugins", "enabled", "Bundled Agent Relay Claude plugin dir is passed to Claude.")
+      : applied("relay.plugins", "disabled", "Bundled Agent Relay Claude plugin dirs are omitted.");
+  }
+  return notApplicable("relay.plugins", profile.relay.plugins ? "enabled" : "disabled", "Codex Relay integration uses skills/app-server delivery, not a Relay plugin dir.");
+}
+
+function relayStatusLineEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
+  if (provider === "claude") {
+    return profile.relay.statusLine
+      ? applied("relay.statusLine", "enabled", "Agent Relay status-line context probe settings are injected when caller settings allow it.")
+      : applied("relay.statusLine", "disabled", "Agent Relay status-line settings are omitted.");
+  }
+  return notApplicable("relay.statusLine", profile.relay.statusLine ? "enabled" : "disabled", "Codex reports context through App Server events instead of a Relay status-line setting.");
+}
+
+function repoInstructionsEntry(profile: AgentProfile): AgentProfileProjectionEntry {
+  if (profile.instructions.repoInstructions === "allow") {
+    return applied("instructions.repo", "allow", "Repo-local provider instructions are left available.");
+  }
+  return unsupported("instructions.repo", "ignore", "Provider-specific repo instruction suppression is not projected yet.");
+}
+
+function globalInstructionsEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
+  if (profile.instructions.globalInstructions === "allow") {
+    return applied("instructions.global", "allow", "Host/global provider instructions are left available.");
+  }
+  if (profile.base !== "host") {
+    return applied("instructions.global", "ignore", `${provider} uses an isolated provider config home, so host/global provider instructions are not loaded.`);
+  }
+  return unsupported("instructions.global", "ignore", `${provider} global instruction isolation requires an isolated provider config home.`);
+}
+
+function mcpEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
+  if (profile.mcp.mode === "host") return applied("mcp", "host", "Host provider MCP configuration is left available.");
+  if (profile.mcp.mode === "none" && profile.base !== "host") {
+    return applied("mcp", "none", `${provider} uses an isolated provider config home without host MCP configuration.`);
+  }
+  return unsupported("mcp", profile.mcp.mode, `${provider} MCP category projection is not enforced yet.`);
+}
+
+function hooksEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
+  if (profile.hooks.mode === "host") return applied("hooks", "host", "Host provider hooks are left available.");
+  if (profile.hooks.mode === "none" && profile.base !== "host") {
+    return applied("hooks", "none", `${provider} uses an isolated provider config home without host hook configuration.`);
+  }
+  return unsupported("hooks", profile.hooks.mode, `${provider} hook category projection is not enforced yet.`);
+}
+
+function filesystemEntry(profile: AgentProfile): AgentProfileProjectionEntry {
+  if (profile.permissions.filesystem === "host") return applied("permissions.filesystem", "host", "No profile-level filesystem boundary requested.");
+  return partial("permissions.filesystem", profile.permissions.filesystem, "Relay constrains spawn cwd through the orchestrator; provider-level filesystem sandbox projection is not complete yet.");
+}
+
+function configHomeEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
+  if (profile.base === "host") return applied("provider.configHome", "host", "Provider uses the host's normal configuration home.");
+  return applied("provider.configHome", profile.base, `${provider} is launched with an Agent Relay managed provider config home and linked host auth where available.`);
+}
+
+function envEntry(profile: AgentProfile): AgentProfileProjectionEntry {
+  const count = Object.keys(profile.env).length;
+  return count
+    ? applied("env", `${count} vars`, "Profile environment variables are passed through the orchestrator runner environment.")
+    : applied("env", "none", "No profile environment variables requested.");
+}
+
+function applied(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "applied", detail };
+}
+
+function partial(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "partial", detail };
+}
+
+function unsupported(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "unsupported", detail };
+}
+
+function notApplicable(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "not-applicable", detail };
+}

package/src/relay-instructions.ts

@@ -0,0 +1,25 @@
+export const CLAUDE_RELAY_MANUAL = `# Agent Relay
+
+- Agent Relay messages may come from humans, channels, or other agents.
+- Read the delivered message body and do the requested work.
+- Reply through Relay only when the sender still needs an answer.
+- Prefer \`agent-relay /reply <messageId> --stdin < response.md\` for the actual answer to an incoming Relay message.
+- Do not send \`/message\` with the useful answer and then a separate \`/reply\` that only says it was sent.
+- If multiple Relay messages arrive together, answer once to the latest relevant message and cover the current request. Do not separately acknowledge stale greetings or context.
+- If the useful response was already delivered through Relay, do not send an extra "sent", "done", or "drafts sent" confirmation unless the user explicitly asked for one.
+- No reply is needed for pure info messages, passive acknowledgements, or reactions that do not ask for action.
+- Use \`agent-relay /react <messageId> <emoji>\` instead of a text reply for lightweight acknowledgement, approval, thanks, or "good job" after a completed work update.
+- Good reaction uses: acknowledge praise with 👍 or ❤️, mark a completed handoff as seen, approve a proposed next step, or acknowledge a passive FYI.
+- Do not use reactions when the user asked a question, gave a new task, reported a bug, or needs a textual result.
+- A thumbs-up reaction to your question means approval to proceed. A thumbs-up reaction to your completed status means no further action.
+- Use \`agent-relay get-message <id>\` when a delivered preview is truncated.
+- Use \`agent-relay /status --json\` to inspect your current Relay identity and \`agent-relay /guide\` for command details.
+`;
+
+export const CLAUDE_RELAY_CONTEXT = `[agent-relay] Relay is available. Follow the Agent Relay rules in CLAUDE.md when present, or run agent-relay /guide. Reply through Relay only when a response is needed; do not send status-only follow-ups after the useful Relay response was already delivered.`;
+
+export const CLAUDE_READ_ONLY_RELAY_CONTEXT = `${CLAUDE_RELAY_CONTEXT}
+
+This Claude session is running with restricted read-only Relay permissions. Do not invoke Agent Relay skills. If you need to reply, use this Bash command shape:
+
+agent-relay /reply <messageId> "<your reply>"`;