agent-relay-runner 0.104.5 → 0.105.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.104.5",
+  "version": "0.105.1",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "agent-relay-providers": "0.104.0",
-    "agent-relay-sdk": "0.2.90",
+    "agent-relay-sdk": "0.2.92",
     "callmux": "0.23.0"
   },
   "devDependencies": {

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

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

package/plugins/claude/monitors/relay-monitor.provisioned.mjs

@@ -847,13 +847,109 @@ function messageBodyMaxCharsFromEnv() {
   return process.env.AGENT_RELAY_MESSAGE_BODY_MAX_CHARS;
 }
 
-// runner/src/relay-instructions.ts
-var 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.`;
-var CLAUDE_READ_ONLY_RELAY_CONTEXT = `${CLAUDE_RELAY_CONTEXT}
+// sdk/src/prompt-template-defaults.ts
+function lines(...parts) {
+  return parts.join(`
+`);
+}
+var RUNNER_PROMPT_TEMPLATE_DEFAULTS = [
+  {
+    slug: "relay.manual.claude",
+    category: "runner",
+    title: "Claude Relay Manual",
+    description: "Bundled CLAUDE.md relay manual written into provisioned Claude homes.",
+    template: lines("# 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 the inline MCP tools `relay_reply` or `relay_send_message` 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.", "- NEVER reply to a notification-class message. The server marks these and renders a single `\u21AA Notification \u2014 no reply needed.` line instead of the reply reminder \u2014 it is a fire-and-forget signal (a merge notice, lifecycle event, or FYI). Act on the information if relevant, but do not send any reply, status confirmation, or reaction back.", '- 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 \uD83D\uDC4D or \u2764\uFE0F, 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."),
+    defaultTemplate: lines("# 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 the inline MCP tools `relay_reply` or `relay_send_message` 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.", "- NEVER reply to a notification-class message. The server marks these and renders a single `\u21AA Notification \u2014 no reply needed.` line instead of the reply reminder \u2014 it is a fire-and-forget signal (a merge notice, lifecycle event, or FYI). Act on the information if relevant, but do not send any reply, status confirmation, or reaction back.", '- 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 \uD83D\uDC4D or \u2764\uFE0F, 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."),
+    variables: []
+  },
+  {
+    slug: "relay.context.claude",
+    category: "runner",
+    title: "Claude Relay Context",
+    description: "One-line relay context note for Claude sessions.",
+    template: "[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.",
+    defaultTemplate: "[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.",
+    variables: []
+  },
+  {
+    slug: "relay.context.claude.readonly",
+    category: "runner",
+    title: "Claude Relay Context (Read Only)",
+    description: "Read-only relay context note for Claude sessions.",
+    template: lines("[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.", "", "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>"'),
+    defaultTemplate: lines("[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.", "", "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>"'),
+    variables: []
+  },
+  {
+    slug: "relay.context.codex",
+    category: "runner",
+    title: "Codex Relay Context",
+    description: "Relay context note injected into Codex sessions.",
+    template: "[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id \u2014 relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own \u2014 find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> \"<your reply>\". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide",
+    defaultTemplate: "[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id \u2014 relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own \u2014 find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> \"<your reply>\". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide",
+    variables: []
+  },
+  {
+    slug: "workspace.lifecycle",
+    category: "runner",
+    title: "Runner Workspace Lifecycle Note",
+    description: "Lifecycle note injected by the runner for isolated workspaces.",
+    template: lines("[agent-relay] Isolated workspace: you are in a git worktree on branch {{branch}}, based on {{baseRef}} \u2014 NOT the main checkout. Other agents may work in parallel and land to {{baseRef}}, so {{baseRef}} will move under you. That is expected; don't fight it.", "Do NOT push this branch yourself \u2014 not with `git push`, not with `tl push` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, run `agent-relay workspace ready` \u2014 Relay rebases onto the latest {{baseRef}}, lands your work, and pushes for you. If the installed `agent-relay` binary is stale and says the workspace command is unknown, run the repo-local fallback: `bun src/index.ts workspace ready`.", "After `ready`, the status becomes `review_requested` \u2014 this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after `ready` and go idle; do NOT wait or poll the steward queue. Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a `--N` suffix \u2014 expected, keep working there. Never `cd` into the main checkout, and never merge/push/resolve conflicts yourself \u2014 Relay and the steward own all of that. `agent-relay workspace status` anytime shows your current state and the exact next step."),
+    defaultTemplate: lines("[agent-relay] Isolated workspace: you are in a git worktree on branch {{branch}}, based on {{baseRef}} \u2014 NOT the main checkout. Other agents may work in parallel and land to {{baseRef}}, so {{baseRef}} will move under you. That is expected; don't fight it.", "Do NOT push this branch yourself \u2014 not with `git push`, not with `tl push` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, run `agent-relay workspace ready` \u2014 Relay rebases onto the latest {{baseRef}}, lands your work, and pushes for you. If the installed `agent-relay` binary is stale and says the workspace command is unknown, run the repo-local fallback: `bun src/index.ts workspace ready`.", "After `ready`, the status becomes `review_requested` \u2014 this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after `ready` and go idle; do NOT wait or poll the steward queue. Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a `--N` suffix \u2014 expected, keep working there. Never `cd` into the main checkout, and never merge/push/resolve conflicts yourself \u2014 Relay and the steward own all of that. `agent-relay workspace status` anytime shows your current state and the exact next step."),
+    variables: ["branch", "baseRef"]
+  },
+  {
+    slug: "workspace.deps.symlink",
+    category: "runner",
+    title: "Runner Workspace Deps Symlink Note",
+    description: "Symlinked node_modules caveat injected by the runner.",
+    template: "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout \u2014 dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If typecheck/build fails on a missing module (a dependency added to the base AFTER this worktree was created), run `agent-relay workspace deps` \u2014 it re-provisions only the stale dirs with a real isolated install, safely, without touching the shared node_modules. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.",
+    defaultTemplate: "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout \u2014 dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If typecheck/build fails on a missing module (a dependency added to the base AFTER this worktree was created), run `agent-relay workspace deps` \u2014 it re-provisions only the stale dirs with a real isolated install, safely, without touching the shared node_modules. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.",
+    variables: []
+  },
+  {
+    slug: "workspace.deps.none",
+    category: "runner",
+    title: "Runner Workspace Deps None Note",
+    description: "Missing dependency provisioning caveat injected by the runner.",
+    template: "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.",
+    defaultTemplate: "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.",
+    variables: []
+  },
+  {
+    slug: "workspace.symlinks",
+    category: "runner",
+    title: "Runner Workspace Symlink Note",
+    description: "Write-through symlink caveat injected by the runner.",
+    template: "[agent-relay] Isolated workspace: these untracked paths are SYMLINKED from the main checkout: {{linked}}. They resolve to the real files in main, so editing or deleting them writes THROUGH to main \u2014 treat them as read-only unless you intend to change main.",
+    defaultTemplate: "[agent-relay] Isolated workspace: these untracked paths are SYMLINKED from the main checkout: {{linked}}. They resolve to the real files in main, so editing or deleting them writes THROUGH to main \u2014 treat them as read-only unless you intend to change main.",
+    variables: []
+  }
+];
 
-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:
+// runner/src/template-resolver.ts
+var RUNNER_DEFAULTS = new Map(RUNNER_PROMPT_TEMPLATE_DEFAULTS.map((template) => [template.slug, template.defaultTemplate]));
+var templateCache = new Map;
+function renderValue(value) {
+  return value ?? "";
+}
+function applyVariables(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => renderValue(vars[key]));
+}
+function renderRunnerTemplate(slug, vars = {}) {
+  const template = templateCache.get(slug) ?? RUNNER_DEFAULTS.get(slug);
+  if (template === undefined)
+    throw new Error(`unknown runner prompt template slug: ${slug}`);
+  return applyVariables(template, vars);
+}
 
-agent-relay /reply <messageId> "<your reply>"`;
+// runner/src/relay-instructions.ts
+function claudeRelayContext() {
+  return renderRunnerTemplate("relay.context.claude");
+}
+function claudeReadOnlyRelayContext() {
+  return renderRunnerTemplate("relay.context.claude.readonly");
+}
 function relayReplyActionText(messageId) {
   return `relay_reply (messageId: ${messageId}, body: "<your reply>"). CLI fallback: agent-relay /reply ${messageId} "<your reply>"`;
 }
@@ -865,9 +961,9 @@ function workspaceDepsNote(input) {
     return "";
   switch (input.depsMode) {
     case "symlink":
-      return "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout \u2014 dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If typecheck/build fails on a missing module (a dependency added to the base AFTER this worktree was created), run `agent-relay workspace deps` \u2014 it re-provisions only the stale dirs with a real isolated install, safely, without touching the shared node_modules. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.";
+      return renderRunnerTemplate("workspace.deps.symlink");
     case "none":
-      return "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.";
+      return renderRunnerTemplate("workspace.deps.none");
     default:
       return "";
   }
@@ -877,17 +973,12 @@ function workspaceLifecycleNote(input) {
     return "";
   const branch = input.branch ? `\`${input.branch}\`` : "an isolated agent branch";
   const base = input.baseRef ? `\`${input.baseRef}\`` : "the base branch";
-  return [
-    `[agent-relay] Isolated workspace: you are in a git worktree on branch ${branch}, based on ${base} \u2014 NOT the main checkout. Other agents may work in parallel and land to ${base}, so ${base} will move under you. That is expected; don't fight it.`,
-    `Do NOT push this branch yourself \u2014 not with \`git push\`, not with \`tl push\` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, run \`agent-relay workspace ready\` \u2014 Relay rebases onto the latest ${base}, lands your work, and pushes for you. If the installed \`agent-relay\` binary is stale and says the workspace command is unknown, run the repo-local fallback: \`bun src/index.ts workspace ready\`.`,
-    `After \`ready\`, the status becomes \`review_requested\` \u2014 this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after \`ready\` and go idle; do NOT wait or poll the steward queue. Relay wakes you with \`landed-success\` when your branch lands and refreshes, or \`landed-failure\` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a \`--N\` suffix \u2014 expected, keep working there. Never \`cd\` into the main checkout, and never merge/push/resolve conflicts yourself \u2014 Relay and the steward own all of that. \`agent-relay workspace status\` anytime shows your current state and the exact next step.`
-  ].join(`
-`);
+  return renderRunnerTemplate("workspace.lifecycle", { branch, baseRef: base });
 }
 function workspaceSymlinksNote(linked) {
   if (!linked.length)
     return "";
-  return `[agent-relay] Isolated workspace: these untracked paths are SYMLINKED from the main checkout: ${linked.join(", ")}. They resolve to the real files in main, so editing or deleting them writes THROUGH to main \u2014 treat them as read-only unless you intend to change main.`;
+  return renderRunnerTemplate("workspace.symlinks", { linked: linked.join(", ") });
 }
 function workspaceDepsNoteFromEnv(env = process.env) {
   const json = env.AGENT_RELAY_WORKSPACE_JSON;
@@ -948,7 +1039,7 @@ function providerAttachmentText(message) {
   const refs = attachmentRefs(message);
   if (!refs.length)
     return;
-  const lines = refs.flatMap((ref) => {
+  const lines2 = refs.flatMap((ref) => {
     const artifactId = typeof ref.artifactId === "string" ? ref.artifactId : "unknown-artifact";
     const source = isRecord(ref.ref) ? [
       typeof ref.ref.provider === "string" ? ref.ref.provider : undefined,
@@ -974,7 +1065,7 @@ function providerAttachmentText(message) {
   ];
   return [
     "Attachments:",
-    ...lines,
+    ...lines2,
     ...guidance
   ].join(`
 `);
@@ -984,18 +1075,18 @@ function providerAttachmentText(message) {
 var REMINDER_EVERY_DELIVERIES = 5;
 var TASK_CLAIM_INSTRUCTION = "Claim this task before working it, then update task status when finished.";
 function stripRelayScaffolding(body) {
-  const lines = body.split(`
+  const lines2 = body.split(`
 `);
   const popTrailingBlanks = () => {
-    while (lines.length && (lines.at(-1) ?? "").trim() === "")
-      lines.pop();
+    while (lines2.length && (lines2.at(-1) ?? "").trim() === "")
+      lines2.pop();
   };
   popTrailingBlanks();
-  if (lines.at(-1) === TASK_CLAIM_INSTRUCTION) {
-    lines.pop();
+  if (lines2.at(-1) === TASK_CLAIM_INSTRUCTION) {
+    lines2.pop();
     popTrailingBlanks();
   }
-  return lines.join(`
+  return lines2.join(`
 `);
 }
 function isMemoryInjection(message) {
@@ -1100,7 +1191,7 @@ ws.onmessage = (event) => {
   const messages2 = payload.messages;
   deliveryCount += 1;
   if (firstDelivery) {
-    console.log(process.env.AGENT_RELAY_APPROVAL === "read-only" ? CLAUDE_READ_ONLY_RELAY_CONTEXT : CLAUDE_RELAY_CONTEXT);
+    console.log(process.env.AGENT_RELAY_APPROVAL === "read-only" ? claudeReadOnlyRelayContext() : claudeRelayContext());
     const wsNote = workspaceDepsNoteFromEnv();
     if (wsNote) {
       console.log("");

package/plugins/claude/monitors/relay-monitor.ts

@@ -1,6 +1,6 @@
 import type { Message } from "agent-relay-sdk";
 import { claudeProviderMessageText } from "../../../src/adapters/claude-delivery";
-import { CLAUDE_READ_ONLY_RELAY_CONTEXT, CLAUDE_RELAY_CONTEXT, workspaceDepsNoteFromEnv } from "../../../src/relay-instructions";
+import { claudeReadOnlyRelayContext, claudeRelayContext, workspaceDepsNoteFromEnv } from "../../../src/relay-instructions";
 
 const port = process.env.AGENT_RELAY_RUNNER_PORT;
 if (!port) process.exit(0);
@@ -15,7 +15,7 @@ ws.onmessage = (event) => {
   const messages = payload.messages as Message[];
   deliveryCount += 1;
   if (firstDelivery) {
-    console.log(process.env.AGENT_RELAY_APPROVAL === "read-only" ? CLAUDE_READ_ONLY_RELAY_CONTEXT : CLAUDE_RELAY_CONTEXT);
+    console.log(process.env.AGENT_RELAY_APPROVAL === "read-only" ? claudeReadOnlyRelayContext() : claudeRelayContext());
     const wsNote = workspaceDepsNoteFromEnv();
     if (wsNote) {
       console.log("");

package/src/adapter.ts

@@ -4,6 +4,7 @@ import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
 import { messageBodyMaxCharsFromEnv } from "./config";
 import { relayReplyReminderText } from "./relay-instructions";
+import { renderRunnerTemplate } from "./template-resolver";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 type ProviderWorkKind = "provider-turn" | "subagent" | "background-script";
@@ -226,7 +227,9 @@ export function profileIsVanillaBase(config: Pick<RunnerSpawnConfig, "agentProfi
   return config.agentProfile?.base === "vanilla";
 }
 
-export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> "<your reply>". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
+export function relayContext(): string {
+  return renderRunnerTemplate("relay.context.codex");
+}
 
 // #306 — deliver the FULL message body by default. Only a pathological body beyond this
 // high cap truncates (with a get-message hint) so it can't nuke an agent's context; the 99%

package/src/adapters/codex.ts

@@ -4,7 +4,7 @@ import { basename, join, resolve } from "node:path";
 import type { ContextState, InteractivePrompt, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
 import { isRecord, stringValue } from "agent-relay-sdk";
 import { isPidAlive, killPid, processTreePids, processTreePidsFromTable, waitForPidsExit } from "agent-relay-sdk/process-utils";
-import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { profileAllowsRelayFeature, providerMessageText, relayContext, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
 import { workspaceDepsNoteFromEnv } from "../relay-instructions";
 import { tomlString } from "../relay-mcp";
 import { assembleLaunch, bundledCodexSkillDirs, bundledSkillConfigArgs, materializeLaunchAssembly } from "../launch-assembly";
@@ -16,7 +16,7 @@ import { computeLivenessSignal, type LivenessInputs } from "../liveness";
 /** Relay context prepended to a Codex agent's first turn: the standard relay
  * blurb plus, when running in an isolated workspace, the deps caveat (#159). */
 function codexRelayContextBlock(): string {
-  return [RELAY_CONTEXT, workspaceDepsNoteFromEnv()].filter(Boolean).join("\n\n");
+  return [relayContext(), workspaceDepsNoteFromEnv()].filter(Boolean).join("\n\n");
 }
 import { prepareCodexProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
 import { CodexAppClient, type ClientEvent } from "./codex-client";

package/src/profile-home.ts

@@ -5,7 +5,7 @@ import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import type { ProvisioningMcpServer, SpawnProvider } from "agent-relay-sdk";
 import { getManifest } from "agent-relay-providers";
 import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
-import { CLAUDE_RELAY_MANUAL } from "./relay-instructions";
+import { claudeRelayManual } from "./relay-instructions";
 import { providerHomeRootFromEnv } from "./config";
 import { applyClaudeConfigPromptGatePreventions } from "./claude-prompt-gates";
 
@@ -184,7 +184,7 @@ function trustWorkspaceForCodex(codexHome: string, config: RunnerSpawnConfig): v
 
 function writeClaudeRelayManual(claudeHome: string): void {
   const path = join(claudeHome, "CLAUDE.md");
-  writeFileSync(path, CLAUDE_RELAY_MANUAL, { mode: 0o600 });
+  writeFileSync(path, claudeRelayManual(), { mode: 0o600 });
 }
 
 function tomlBasicString(value: string): string {

package/src/relay-instructions.ts

@@ -1,29 +1,16 @@
-export const CLAUDE_RELAY_MANUAL = `# Agent Relay
+import { renderRunnerTemplate } from "./template-resolver";
 
-- 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 the inline MCP tools \`relay_reply\` or \`relay_send_message\` 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.
-- NEVER reply to a notification-class message. The server marks these and renders a single \`↪ Notification — no reply needed.\` line instead of the reply reminder — it is a fire-and-forget signal (a merge notice, lifecycle event, or FYI). Act on the information if relevant, but do not send any reply, status confirmation, or reaction back.
-- 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}
+export function claudeRelayManual(): string {
+  return renderRunnerTemplate("relay.manual.claude");
+}
 
-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:
+export function claudeRelayContext(): string {
+  return renderRunnerTemplate("relay.context.claude");
+}
 
-agent-relay /reply <messageId> "<your reply>"`;
+export function claudeReadOnlyRelayContext(): string {
+  return renderRunnerTemplate("relay.context.claude.readonly");
+}
 
 export function relayReplyActionText(messageId: number): string {
   return `relay_reply (messageId: ${messageId}, body: "<your reply>"). CLI fallback: agent-relay /reply ${messageId} "<your reply>"`;
@@ -33,59 +20,30 @@ export function relayReplyReminderText(messageId: number): string {
   return `If this batch needs a response, send one useful reply to the latest relevant message with ${relayReplyActionText(messageId)}`;
 }
 
-/**
- * Provider-agnostic caveat injected into every spawned agent that runs in an
- * isolated workspace, regardless of which project it is working in. Isolated
- * workspaces are git worktrees whose node_modules are provisioned by the
- * orchestrator (see AGENT_RELAY_WORKSPACE_DEPS): symlinked from the main
- * checkout by default. The agent needs to know this so it doesn't run a clean
- * install that mutates the shared node_modules. Returns "" when no note applies
- * (shared workspace, or deps installed fresh / unknown).
- */
 export function workspaceDepsNote(input: { mode?: string | null; depsMode?: string | null }): string {
   if (input.mode !== "isolated") return "";
   switch (input.depsMode) {
     case "symlink":
-      return "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout — dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If typecheck/build fails on a missing module (a dependency added to the base AFTER this worktree was created), run `agent-relay workspace deps` — it re-provisions only the stale dirs with a real isolated install, safely, without touching the shared node_modules. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.";
+      return renderRunnerTemplate("workspace.deps.symlink");
     case "none":
-      return "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.";
+      return renderRunnerTemplate("workspace.deps.none");
     default:
       return "";
   }
 }
 
-/**
- * Lifecycle briefing for an agent spawned into an isolated workspace (#205).
- * Tells it, in plain terms, that it is on an isolated branch off a base that
- * other agents move in parallel, and how to hand off — so it doesn't re-derive
- * "I seem to be in a clone, not on main" every session or hand-roll a rebase/push.
- * Returns "" for shared workspaces. Branch/base come from the resolved metadata.
- */
 export function workspaceLifecycleNote(input: { mode?: string | null; branch?: string | null; baseRef?: string | null }): string {
   if (input.mode !== "isolated") return "";
   const branch = input.branch ? `\`${input.branch}\`` : "an isolated agent branch";
   const base = input.baseRef ? `\`${input.baseRef}\`` : "the base branch";
-  return [
-    `[agent-relay] Isolated workspace: you are in a git worktree on branch ${branch}, based on ${base} — NOT the main checkout. Other agents may work in parallel and land to ${base}, so ${base} will move under you. That is expected; don't fight it.`,
-    `Do NOT push this branch yourself — not with \`git push\`, not with \`tl push\` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, run \`agent-relay workspace ready\` — Relay rebases onto the latest ${base}, lands your work, and pushes for you. If the installed \`agent-relay\` binary is stale and says the workspace command is unknown, run the repo-local fallback: \`bun src/index.ts workspace ready\`.`,
-    `After \`ready\`, the status becomes \`review_requested\` — this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after \`ready\` and go idle; do NOT wait or poll the steward queue. Relay wakes you with \`landed-success\` when your branch lands and refreshes, or \`landed-failure\` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a \`--N\` suffix — expected, keep working there. Never \`cd\` into the main checkout, and never merge/push/resolve conflicts yourself — Relay and the steward own all of that. \`agent-relay workspace status\` anytime shows your current state and the exact next step.`,
-  ].join("\n");
+  return renderRunnerTemplate("workspace.lifecycle", { branch, baseRef: base });
 }
 
-/**
- * Caveat for untracked paths symlinked from main into an isolated worktree
- * (WorkspaceConfig.symlinkPaths, e.g. AGENTS.md, .claude-rig). Edits to these
- * write THROUGH to the main checkout — the agent must know so it doesn't mutate
- * shared config thinking it's worktree-local. Returns "" when nothing was linked.
- */
 export function workspaceSymlinksNote(linked: string[]): string {
   if (!linked.length) return "";
-  return `[agent-relay] Isolated workspace: these untracked paths are SYMLINKED from the main checkout: ${linked.join(", ")}. They resolve to the real files in main, so editing or deleting them writes THROUGH to main — treat them as read-only unless you intend to change main.`;
+  return renderRunnerTemplate("workspace.symlinks", { linked: linked.join(", ") });
 }
 
-/** Resolve the workspace caveats from the runner/monitor environment.
- * AGENT_RELAY_WORKSPACE_JSON carries the resolved workspace metadata (mode +
- * deps + symlinks) and is the authoritative source. Best-effort: never throws. */
 export function workspaceDepsNoteFromEnv(env: Record<string, string | undefined> = process.env): string {
   const json = env.AGENT_RELAY_WORKSPACE_JSON;
   if (!json) return "";

package/src/runner-core.ts

@@ -33,6 +33,7 @@ import { providerTerminalSession, providerTerminalSocket } from "./process-meta"
 import { capsFromEnv, logLevelFromEnv, mcpProxyEnabledFromEnv, orchestratorBaseDirFromEnv, orchestratorUrlFromEnv, registrationTimeoutMsFromEnv, runnerInfoFileFromEnv, runnerLogFileFromEnv, runnerOutboxDirWithInfoFallback, sessionDebugEnabled, tagsFromEnv, workspaceModeFromEnv } from "./config";
 import { boundaryReasonForCommand, PRE_DESTROY_TIMEOUT_MS, reasonExitsRunner, type LifecycleAction, type SessionDestroyReason } from "./session-destroy";
 import { isNativeSelfResumeCompact, NativeSelfResumeTracker, recoverNativeSelfResumeExit } from "./native-self-resume";
+import { initializeRunnerTemplates } from "./template-resolver";
 import {
   appliedAgentProfileMetadata,
   commandTimeoutMs,
@@ -442,7 +443,7 @@ export class AgentRunner {
       void this.handleCommand(type, params, commandId, command);
     });
     this.bus.on("error", (code, message) => this.handleBusError(String(code), String(message)));
-    await registerWithinDeadline(this.bus, registrationTimeoutMsFromEnv(), this.options.relayUrl, (reason) => logger.fatal("register", reason));
+    await registerWithinDeadline(this.bus, registrationTimeoutMsFromEnv(), this.options.relayUrl, (reason) => logger.fatal("register", reason)); await initializeRunnerTemplates(this.http);
     this.obligationCache.start();
     this.outbox.start();
     this.sessionOutbox.start();
@@ -487,8 +488,7 @@ export class AgentRunner {
     this.busyReconciler.disarm();
     this.stopReasoningTail();
     this.obligationCache.stop();
-    this.outbox.close();
-    this.sessionOutbox.close();
+    this.outbox.close(); this.sessionOutbox.close();
     this.proxy?.stop();
     this.control?.stop();
     await this.bus.close();

package/src/template-resolver.ts

@@ -0,0 +1,29 @@
+import type { RelayHttpClient } from "agent-relay-sdk";
+import { RUNNER_PROMPT_TEMPLATE_DEFAULTS } from "agent-relay-sdk/prompt-template-defaults";
+
+const RUNNER_DEFAULTS = new Map<string, string>(RUNNER_PROMPT_TEMPLATE_DEFAULTS.map((template) => [template.slug, template.defaultTemplate]));
+const templateCache = new Map<string, string>();
+
+function renderValue(value: string | undefined): string {
+  return value ?? "";
+}
+
+function applyVariables(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => renderValue(vars[key]));
+}
+
+export async function initializeRunnerTemplates(http: RelayHttpClient): Promise<void> {
+  try {
+    const templates = await http.listPromptTemplates();
+    templateCache.clear();
+    for (const template of templates) templateCache.set(template.slug, template.template);
+  } catch {
+    templateCache.clear();
+  }
+}
+
+export function renderRunnerTemplate(slug: string, vars: Record<string, string> = {}): string {
+  const template = templateCache.get(slug) ?? RUNNER_DEFAULTS.get(slug);
+  if (template === undefined) throw new Error(`unknown runner prompt template slug: ${slug}`);
+  return applyVariables(template, vars);
+}