agent-relay-runner 0.10.6 → 0.10.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.10.6",
+  "version": "0.10.8",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

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

@@ -1,5 +1,5 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.10.6"
+  "version": "0.10.8"
 }

package/plugins/claude/skills/disconnect/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: disconnect
+description: End the current Agent Relay pair session. Use when the user invokes /disconnect or asks to hang up, unpair, or disconnect from a paired agent.
+argument-hint: "[PAIR_ID]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Disconnect
+
+Run:
+
+```bash
+agent-relay /disconnect $ARGUMENTS
+```
+
+If no pair id is supplied, the CLI ends the active pair for this session. Report the result briefly.

package/plugins/claude/skills/label/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: label
+description: Read, set, or clear the current Agent Relay agent label. Use when the user invokes /label or asks to rename this relay agent.
+argument-hint: "[LABEL|--clear]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Label
+
+Run:
+
+```bash
+agent-relay /label $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /label backend-fixer
+agent-relay /label --clear
+```
+
+Report the new label or current label briefly.

package/plugins/claude/skills/message/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: message
+description: Send a normal Agent Relay message to another agent, label, tag, capability, or broadcast target. Use when the user invokes /message or asks to send a one-off relay message.
+argument-hint: "<target> <message> [--subject TEXT] [--channel NAME]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Message
+
+Run:
+
+```bash
+agent-relay /message $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /message codex "Can you look at that failing action?"
+agent-relay /message tag:backend "Does anyone see the regression?"
+agent-relay /message broadcast "Standup in five minutes"
+```
+
+Report the sent message id briefly.

package/plugins/claude/skills/pair/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: pair
+description: Start, inspect, accept, reject, or send messages in an Agent Relay two-agent pair session. Use when the user invokes /pair or asks to pair this agent with Codex, Claude, or another relay agent.
+argument-hint: "<target|status|accept|reject|send> [args]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Pair
+
+Run the Agent Relay CLI with the user's arguments:
+
+```bash
+agent-relay /pair $ARGUMENTS
+```
+
+Use this for pair-session commands such as:
+
+```bash
+agent-relay /pair codex "Debug flaky tests"
+agent-relay /pair status
+agent-relay /pair accept PAIR_ID
+agent-relay /pair reject PAIR_ID
+agent-relay /pair send PAIR_ID "What do you see?"
+```
+
+Report the command output briefly. If the CLI cannot detect this session's agent id, rerun with `--agent AGENT_ID` or `--from AGENT_ID` using the Agent Relay ID shown in session context.

package/plugins/claude/skills/reply/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: reply
+description: Reply to an Agent Relay message by ID. Auto-routes to the sender and inherits channel context — no target needed. Use when the user invokes /reply or asks to reply to a specific relay message.
+argument-hint: "<messageId> <message>"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Reply
+
+Run:
+
+```bash
+agent-relay /reply $ARGUMENTS
+```
+
+The server auto-routes the reply to the original sender and inherits the channel (Telegram, Slack, etc.) if applicable. No target or channel ID needed.
+
+Examples:
+
+```bash
+agent-relay /reply 206 "Sounds good, I'll take a look"
+agent-relay /reply 42 "Done — the fix is in commit abc123"
+```
+
+Report the sent message id and resolved target briefly.

package/plugins/claude/skills/send-claimable/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: send-claimable
+description: Send a claimable Agent Relay work item so one matching agent can claim and handle it. Use when the user invokes /send-claimable or wants to enqueue work for another agent.
+argument-hint: "<target> <message> [--subject TEXT] [--channel NAME]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Send Claimable
+
+Run:
+
+```bash
+agent-relay /send-claimable $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /send-claimable codex "Claim this and inspect the failing action"
+agent-relay /send-claimable tag:backend "Fix the failing API test"
+agent-relay /send-claimable cap:review "Review the migration patch"
+```
+
+Report the sent claimable message id briefly.

package/plugins/claude/skills/status/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: status
+description: Show Agent Relay status for this session, including relay health, current agent id, label, tags, readiness, and active pair state. Use when the user invokes /status or asks for relay connection status.
+argument-hint: "[--json]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Status
+
+Run:
+
+```bash
+agent-relay /status $ARGUMENTS
+```
+
+Summarize the current relay connection, agent identity, label, tags, and active pair state.

package/plugins/claude/skills/tags/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: tags
+description: List or update Agent Relay tags for the current session. Use when the user invokes /tags or asks to set, add, remove, or inspect relay tags.
+argument-hint: "[TAG ...|--list|--add TAGS|--remove TAGS]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Tags
+
+Run:
+
+```bash
+agent-relay /tags $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /tags
+agent-relay /tags backend tests urgent
+agent-relay /tags --add backend,tests
+agent-relay /tags --remove urgent
+```
+
+Report the resulting tags briefly.

package/plugins/codex/skills/disconnect/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: disconnect
+description: End the current Agent Relay pair session. Use when the user invokes /disconnect or asks to hang up, unpair, or disconnect from a paired agent.
+argument-hint: "[PAIR_ID]"
+---
+
+# Agent Relay Disconnect
+
+Run:
+
+```bash
+agent-relay /disconnect $ARGUMENTS
+```
+
+If no pair id is supplied, the CLI ends the active pair for this session. Report the result briefly.

package/plugins/codex/skills/label/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: label
+description: Read, set, or clear the current Agent Relay agent label. Use when the user invokes /label or asks to rename this relay agent.
+argument-hint: "[LABEL|--clear]"
+---
+
+# Agent Relay Label
+
+Run:
+
+```bash
+agent-relay /label $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /label backend-fixer
+agent-relay /label --clear
+```
+
+Report the new label or current label briefly.

package/plugins/codex/skills/message/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: message
+description: Send a normal Agent Relay message to another agent, label, tag, capability, policy, or broadcast target. Use when the user invokes /message or asks to send a one-off relay message.
+argument-hint: "<target> <message> [--subject TEXT] [--channel NAME]"
+---
+
+# Agent Relay Message
+
+Run:
+
+```bash
+agent-relay /message $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /message codex "Can you look at that failing action?"
+agent-relay /message tag:backend "Does anyone see the regression?"
+agent-relay /message policy:reviewer "Review this when you come online"
+agent-relay /message broadcast "Standup in five minutes"
+```
+
+Report the sent message id briefly.

package/plugins/codex/skills/pair/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: pair
+description: Start, inspect, accept, reject, or send messages in an Agent Relay two-agent pair session. Use when the user invokes /pair or asks to pair this agent with Codex, Claude, or another relay agent.
+argument-hint: "<target|status|accept|reject|send> [args]"
+---
+
+# Agent Relay Pair
+
+Run the Agent Relay CLI with the user's arguments:
+
+```bash
+agent-relay /pair $ARGUMENTS
+```
+
+Use this for pair-session commands such as:
+
+```bash
+agent-relay /pair codex "Debug flaky tests"
+agent-relay /pair status
+agent-relay /pair accept PAIR_ID
+agent-relay /pair reject PAIR_ID
+agent-relay /pair send PAIR_ID "What do you see?"
+```
+
+Report the command output briefly. If the CLI cannot detect this session's agent id, rerun with `--agent AGENT_ID` or `--from AGENT_ID` using the Agent Relay ID shown in session context.

package/plugins/codex/skills/reply/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: reply
+description: Reply to an Agent Relay message by ID. Auto-routes to the sender and inherits channel context, so no target is needed. Use when the user invokes /reply or asks to reply to a specific relay message.
+argument-hint: "<messageId> <message>"
+---
+
+# Agent Relay Reply
+
+Run:
+
+```bash
+agent-relay /reply $ARGUMENTS
+```
+
+The server auto-routes the reply to the original sender and inherits the channel if applicable. No target or channel ID is needed.
+
+Examples:
+
+```bash
+agent-relay /reply 206 "Sounds good, I'll take a look"
+agent-relay /reply 42 "Done; the fix is in commit abc123"
+```
+
+Report the sent message id and resolved target briefly.

package/plugins/codex/skills/send-claimable/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: send-claimable
+description: Send a claimable Agent Relay work item so one matching agent can claim and handle it. Use when the user invokes /send-claimable or wants to enqueue work for another agent.
+argument-hint: "<target> <message> [--subject TEXT] [--channel NAME]"
+---
+
+# Agent Relay Send Claimable
+
+Run:
+
+```bash
+agent-relay /send-claimable $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /send-claimable codex "Claim this and inspect the failing action"
+agent-relay /send-claimable tag:backend "Fix the failing API test"
+agent-relay /send-claimable cap:review "Review the migration patch"
+agent-relay /send-claimable policy:reviewer "Review this when the managed reviewer starts"
+```
+
+Report the sent claimable message id briefly.

package/plugins/codex/skills/status/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: status
+description: Show Agent Relay status for this session, including relay health, current agent id, label, tags, readiness, and active pair state. Use when the user invokes /status or asks for relay connection status.
+argument-hint: "[--json]"
+---
+
+# Agent Relay Status
+
+Run:
+
+```bash
+agent-relay /status $ARGUMENTS
+```
+
+Summarize the current relay connection, agent identity, label, tags, and active pair state.

package/plugins/codex/skills/tags/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: tags
+description: List or update Agent Relay tags for the current session. Use when the user invokes /tags or asks to set, add, remove, or inspect relay tags.
+argument-hint: "[TAG ...|--list|--add TAGS|--remove TAGS]"
+---
+
+# Agent Relay Tags
+
+Run:
+
+```bash
+agent-relay /tags $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /tags
+agent-relay /tags backend tests urgent
+agent-relay /tags --add backend,tests
+agent-relay /tags --remove urgent
+```
+
+Report the resulting tags briefly.

package/src/adapter.ts

@@ -26,6 +26,7 @@ export interface RunnerSpawnConfig {
   headless: boolean;
   approvalMode: string;
   label?: string;
+  rig?: string;
   prompt?: string;
   providerArgs: string[];
   providerConfig: ProviderConfig;

package/src/adapters/claude.ts

@@ -5,6 +5,7 @@ import type { ManagedProcess, ProviderAdapter, ProviderConfig, RunnerSpawnConfig
 export class ClaudeAdapter implements ProviderAdapter {
   readonly provider = "claude";
   private statusCb: (status: SemanticStatus) => void = () => {};
+  private tmuxWatcher?: Timer;
 
   onStatusChange(cb: (status: SemanticStatus) => void): void {
     this.statusCb = cb;
@@ -12,6 +13,11 @@ export class ClaudeAdapter implements ProviderAdapter {
 
   async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
     const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
+
+    if (config.headless) {
+      return this.spawnHeadless(config, args);
+    }
+
     const proc = Bun.spawn([args.command, ...args.args], {
       cwd: args.cwd,
       env: args.env,
@@ -24,6 +30,11 @@ export class ClaudeAdapter implements ProviderAdapter {
   }
 
   async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+    const tmuxSession = process.meta?.tmuxSession as string | undefined;
+    if (tmuxSession) {
+      await this.shutdownTmux(tmuxSession, opts);
+      return;
+    }
     await terminateProcess(process, opts);
   }
 
@@ -36,7 +47,10 @@ export class ClaudeAdapter implements ProviderAdapter {
   buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
     const pluginRoot = resolve(import.meta.dir, "../../plugins/claude");
     const pluginDirs = [...new Set([pluginRoot, ...providerConfig.pluginDirs])];
+    const isClaudeRig = /claude-rig/.test(providerConfig.command);
+    const rigPrefix = isClaudeRig && config.rig ? ["launch", config.rig] : [];
     const args = [
+      ...rigPrefix,
       ...pluginDirs.flatMap((dir) => ["--plugin-dir", dir]),
       ...providerConfig.defaultArgs,
       ...config.providerArgs,
@@ -52,6 +66,117 @@ export class ClaudeAdapter implements ProviderAdapter {
       },
     };
   }
+
+  buildTmuxArgs(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): { sessionName: string; args: string[] } {
+    const sessionName = tmuxSessionName(config.providerConfig.headless.tmuxPrefix, config.instanceId, config.label);
+    const shellCmd = [spawnArgs.command, ...spawnArgs.args].map(shellQuote).join(" ");
+    const tmuxArgs = ["new-session", "-d", "-s", sessionName, "-x", "200", "-y", "50"];
+
+    const envKeys = tmuxEnvKeys(spawnArgs.env, config.providerConfig.env);
+    for (const key of envKeys) {
+      if (spawnArgs.env[key] !== undefined) {
+        tmuxArgs.push("-e", `${key}=${spawnArgs.env[key]}`);
+      }
+    }
+
+    tmuxArgs.push("-c", spawnArgs.cwd, shellCmd);
+    return { sessionName, args: tmuxArgs };
+  }
+
+  private async spawnHeadless(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): Promise<ManagedProcess> {
+    const { sessionName, args: tmuxArgs } = this.buildTmuxArgs(config, spawnArgs);
+
+    Bun.spawnSync(["tmux", "kill-session", "-t", sessionName], {
+      stdin: "ignore", stdout: "ignore", stderr: "ignore",
+    });
+
+    const result = Bun.spawnSync(["tmux", ...tmuxArgs], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toString().trim();
+      throw new Error(`tmux session creation failed: ${stderr || `exit code ${result.exitCode}`}`);
+    }
+
+    this.watchTmuxSession(sessionName);
+
+    return {
+      pid: undefined,
+      process: undefined,
+      meta: {
+        monitor: config.monitor,
+        tmuxSession: sessionName,
+      },
+    };
+  }
+
+  private watchTmuxSession(sessionName: string): void {
+    if (this.tmuxWatcher) clearInterval(this.tmuxWatcher);
+    this.tmuxWatcher = setInterval(() => {
+      if (!tmuxHasSession(sessionName)) {
+        clearInterval(this.tmuxWatcher!);
+        this.tmuxWatcher = undefined;
+        this.statusCb("offline");
+      }
+    }, 2000);
+  }
+
+  private async shutdownTmux(sessionName: string, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+    if (this.tmuxWatcher) {
+      clearInterval(this.tmuxWatcher);
+      this.tmuxWatcher = undefined;
+    }
+
+    if (opts.graceful && tmuxHasSession(sessionName)) {
+      Bun.spawnSync(["tmux", "send-keys", "-t", sessionName, "C-c"], {
+        stdin: "ignore", stdout: "ignore", stderr: "ignore",
+      });
+
+      const deadline = Date.now() + opts.timeoutMs;
+      while (Date.now() < deadline) {
+        if (!tmuxHasSession(sessionName)) return;
+        await Bun.sleep(500);
+      }
+    }
+
+    Bun.spawnSync(["tmux", "kill-session", "-t", sessionName], {
+      stdin: "ignore", stdout: "ignore", stderr: "ignore",
+    });
+  }
+}
+
+export function tmuxSessionName(prefix: string, instanceId: string, label?: string): string {
+  if (label) return `${prefix}-${label.replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase()}`;
+  return `${prefix}-${instanceId.slice(0, 8)}`;
+}
+
+export function tmuxHasSession(sessionName: string): boolean {
+  const result = Bun.spawnSync(["tmux", "has-session", "-t", sessionName], {
+    stdin: "ignore", stdout: "ignore", stderr: "ignore",
+  });
+  return result.exitCode === 0;
+}
+
+export function tmuxEnvKeys(env: Record<string, string>, providerEnv: Record<string, string>): string[] {
+  const keys = new Set<string>();
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("AGENT_RELAY_") || key.startsWith("CLAUDE_")) {
+      keys.add(key);
+    }
+  }
+  for (const key of Object.keys(providerEnv)) {
+    keys.add(key);
+  }
+  return [...keys].sort();
+}
+
+export function shellQuote(arg: string): string {
+  if (arg.length === 0) return "''";
+  if (/^[a-zA-Z0-9_./:@=+,-]+$/.test(arg)) return arg;
+  return `'${arg.replace(/'/g, "'\\''")}'`;
 }
 
 async function terminateProcess(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {

package/src/adapters/codex.ts

@@ -1,3 +1,5 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
 import type { Message } from "agent-relay-sdk";
 import { providerMessageText, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
 import { CodexAppClient, type ClientEvent } from "./codex-client";
@@ -27,8 +29,8 @@ export class CodexAdapter implements ProviderAdapter {
       client.onEvent((event) => this.handleCodexEvent(event));
     }
 
-    const tui = !config.headless && config.providerConfig.command === "codex"
-      ? Bun.spawn(["codex", "--remote", appServerUrl, ...config.providerConfig.defaultArgs, ...config.providerArgs], {
+    const tui = !config.headless && isCodexCliCommand(config.providerConfig.command)
+      ? Bun.spawn([config.providerConfig.command, "--remote", appServerUrl, ...bundledSkillConfigArgs(), ...config.providerConfig.defaultArgs, ...config.providerArgs], {
         cwd: config.cwd,
         env: args.env,
         stdin: "inherit",
@@ -62,8 +64,14 @@ export class CodexAdapter implements ProviderAdapter {
 
   buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
     const appServerUrl = String(config.appServerUrl || process.env.CODEX_APP_SERVER_URL || `ws://127.0.0.1:${config.controlPort + 1000}`);
-    const args = providerConfig.command === "codex"
-      ? ["app-server", "--listen", appServerUrl]
+    const args = isCodexCliCommand(providerConfig.command)
+      ? [
+        "app-server",
+        ...codexAppServerConfigArgs(providerConfig.defaultArgs, config.providerArgs),
+        ...bundledSkillConfigArgs(),
+        "--listen",
+        appServerUrl,
+      ]
       : [...providerConfig.defaultArgs, ...config.providerArgs];
     return {
       command: providerConfig.command,
@@ -90,6 +98,49 @@ export class CodexAdapter implements ProviderAdapter {
   }
 }
 
+export function isCodexCliCommand(command: string): boolean {
+  return basename(command) === "codex";
+}
+
+export function bundledCodexSkillDirs(baseDir = resolve(import.meta.dir, "../../plugins/codex/skills")): string[] {
+  if (!existsSync(baseDir)) return [];
+  return readdirSync(baseDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(baseDir, entry.name, "SKILL.md")))
+    .map((entry) => join(baseDir, entry.name))
+    .sort();
+}
+
+export function bundledSkillConfigArgs(skillDirs = bundledCodexSkillDirs()): string[] {
+  if (skillDirs.length === 0) return [];
+  const skillsConfig = skillDirs
+    .map((dir) => `{path=${tomlString(dir)},enabled=true}`)
+    .join(",");
+  return ["-c", `skills.config=[${skillsConfig}]`];
+}
+
+export function codexAppServerConfigArgs(...argLists: string[][]): string[] {
+  const result: string[] = [];
+  for (const args of argLists) {
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "-c" || arg === "--config" || arg === "--enable" || arg === "--disable") {
+        const value = args[i + 1];
+        if (value !== undefined) {
+          result.push(arg, value);
+          i++;
+        }
+      } else if (arg?.startsWith("--config=") || arg?.startsWith("--enable=") || arg?.startsWith("--disable=")) {
+        result.push(arg);
+      }
+    }
+  }
+  return result;
+}
+
+function tomlString(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
 async function connectWithRetry(client: CodexAppClient, attempts = 40): Promise<void> {
   let lastError: unknown;
   for (let i = 0; i < attempts; i++) {

package/src/config.ts

@@ -24,7 +24,7 @@ function providersDir(home = agentRelayHome()): string {
 }
 
 export function defaultProviderConfig(provider: string): ProviderConfig {
-  const command = provider === "claude" ? "claude-rig" : provider;
+  const command = provider === "claude" ? "claude" : provider;
   return {
     command,
     defaultArgs: provider === "claude" ? ["--dangerously-skip-permissions"] : [],

package/src/index.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { basename } from "node:path";
+import { isatty } from "node:tty";
 import { ClaudeAdapter } from "./adapters/claude";
 import { CodexAdapter } from "./adapters/codex";
 import { AgentRunner } from "./runner";
@@ -8,13 +9,17 @@ import { loadGlobalConfig, loadProviderConfig, resolveCwd, runnerId } from "./co
 interface CliOptions {
   provider: "claude" | "codex";
   headless: boolean;
+  interactive: boolean;
   cwd?: string;
+  rig?: string;
   relayUrl?: string;
   token?: string;
   approvalMode?: string;
   label?: string;
   agentId?: string;
   prompt?: string;
+  tags: string[];
+  caps: string[];
   providerArgs: string[];
 }
 
@@ -25,6 +30,10 @@ export async function main(argv = process.argv): Promise<void> {
   const cwd = resolveCwd(opts.cwd, globalConfig.defaultCwd);
   const id = runnerId(opts.provider, cwd, opts.label);
   const adapter = opts.provider === "claude" ? new ClaudeAdapter() : new CodexAdapter();
+
+  let exitResolve: (code: number) => void;
+  const exitPromise = new Promise<number>((resolve) => { exitResolve = resolve; });
+
   const runner = new AgentRunner({
     provider: opts.provider,
     runnerId: id,
@@ -36,17 +45,28 @@ export async function main(argv = process.argv): Promise<void> {
     headless: opts.headless,
     approvalMode: opts.approvalMode ?? providerConfig.defaultApprovalMode,
     label: opts.label,
+    rig: opts.rig,
     prompt: opts.prompt,
+    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,
+    startedAt: Date.now(),
     providerConfig,
     adapter,
+    onProviderExit: (code) => exitResolve(code ?? 1),
   });
   await runner.run();
-  await waitForShutdown(() => runner.stop());
+
+  const code = await Promise.race([exitPromise, signalPromise()]);
+  await runner.stop();
+  process.exit(code);
 }
 
 function parseArgs(argv: string[]): CliOptions {
-  const bin = basename(argv[1] || "");
+  const bin = [argv[1], process.env._].map((s) => basename(s || "")).join(" ");
   let provider: "claude" | "codex" = bin.includes("claude") ? "claude" : "codex";
   const relayArgs = argv.slice(2);
   const providerSep = relayArgs.indexOf("--");
@@ -54,24 +74,30 @@ function parseArgs(argv: string[]): CliOptions {
   const providerArgs = providerSep >= 0 ? relayArgs.slice(providerSep + 1) : [];
   let headless = false;
   let cwd: string | undefined;
+  let rig: 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 tags: string[] = [];
+  let caps: string[] = [];
 
   for (let i = 0; i < ownArgs.length; i++) {
     const arg = ownArgs[i];
     if (arg === "claude" || arg === "codex") provider = arg;
     else if (arg === "--headless") headless = true;
     else if (arg === "--cwd" && ownArgs[i + 1]) cwd = ownArgs[++i];
+    else if (arg === "--rig" && ownArgs[i + 1]) rig = 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 === "--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") {
       printHelp(provider);
       process.exit(0);
@@ -80,24 +106,23 @@ function parseArgs(argv: string[]): CliOptions {
     }
   }
 
-  return { provider, headless, cwd, relayUrl, token, approvalMode, label, agentId, prompt, providerArgs };
+  const interactive = !headless && isatty(0);
+  return { provider, headless, interactive, cwd, rig, relayUrl, token, approvalMode, label, agentId, prompt, tags, caps, providerArgs };
+}
+
+function csvSplit(value: string): string[] {
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
 
 function printHelp(provider: string): void {
-  console.log(`${provider}-relay [--headless] [--cwd PATH] [--relay-url URL] [--approval MODE] [--label NAME] [--agent-id ID] [-- provider-args...]`);
+  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...]`);
 }
 
-async function waitForShutdown(stop: () => Promise<void>): Promise<void> {
-  let stopping = false;
-  const shutdown = async () => {
-    if (stopping) return;
-    stopping = true;
-    await stop();
-    process.exit(0);
-  };
-  process.on("SIGINT", () => void shutdown());
-  process.on("SIGTERM", () => void shutdown());
-  await new Promise(() => {});
+function signalPromise(): Promise<number> {
+  return new Promise<number>((resolve) => {
+    process.on("SIGINT", () => resolve(130));
+    process.on("SIGTERM", () => resolve(143));
+  });
 }
 
 if (import.meta.main) {

package/src/runner.ts

@@ -16,10 +16,18 @@ interface RunnerOptions {
   headless: boolean;
   approvalMode: string;
   label?: string;
+  rig?: string;
   prompt?: string;
+  tags: string[];
+  capabilities: string[];
   providerArgs: string[];
+  policyName?: string;
+  spawnRequestId?: string;
+  tmuxSession?: string;
+  startedAt: number;
   providerConfig: ProviderConfig;
   adapter: ProviderAdapter;
+  onProviderExit?: (code: number | null) => void;
 }
 
 export class AgentRunner {
@@ -30,6 +38,7 @@ export class AgentRunner {
   private control?: ControlServer;
   private process?: ManagedProcess;
   private stopped = false;
+  private exitCommandInProgress = false;
   private delivering = false;
   private readonly pendingMessages = new Map<number, Message>();
 
@@ -47,6 +56,8 @@ export class AgentRunner {
       capabilities: [
         ...new Set([
           ...options.providerConfig.defaultCapabilities,
+          ...options.capabilities,
+          ...csvTags(process.env.AGENT_RELAY_CAPS),
           "lifecycle.shutdown.hard",
           "lifecycle.restart.hard",
           "lifecycle.status.semantic",
@@ -56,10 +67,14 @@ export class AgentRunner {
           "capabilities.report",
         ]),
       ],
-      tags: [...new Set([options.provider, ...csvTags(process.env.AGENT_RELAY_TAGS), ...options.providerConfig.defaultTags, ...(options.headless ? ["headless"] : [])])],
+      tags: [...new Set([options.provider, ...csvTags(process.env.AGENT_RELAY_TAGS), ...options.tags, ...options.providerConfig.defaultTags, ...(options.headless ? ["headless"] : [])])],
       meta: {
         provider: options.provider,
         runnerId: options.runnerId,
+        startedAt: options.startedAt,
+        tmuxSession: options.tmuxSession ?? null,
+        policyName: options.policyName ?? null,
+        spawnRequestId: options.spawnRequestId ?? null,
         runnerManaged: true,
         cwd: options.cwd,
         approvalMode: options.approvalMode,
@@ -77,7 +92,10 @@ export class AgentRunner {
 
   async run(): Promise<void> {
     this.control = startControlServer({ onStatus: (status) => this.setProviderStatus(status) });
-    this.options.adapter.onStatusChange((status) => this.setProviderStatus(status));
+    this.options.adapter.onStatusChange((status) => {
+      this.setProviderStatus(status);
+      if (runnerShouldResolveProviderExit(status, this.exitCommandInProgress)) this.options.onProviderExit?.(status === "offline" ? 0 : 1);
+    });
     this.bus.on("message.new", (message) => this.enqueueMessage(message as Message));
     this.bus.on("command", (type, params, commandId, command) => {
       void this.handleCommand(type, params, commandId, command);
@@ -123,6 +141,7 @@ export class AgentRunner {
       headless: this.options.headless,
       approvalMode: this.options.approvalMode,
       ...(this.options.label ? { label: this.options.label } : {}),
+      ...(this.options.rig ? { rig: this.options.rig } : {}),
       ...(this.options.prompt ? { prompt: this.options.prompt } : {}),
       providerArgs: this.options.providerArgs,
       providerConfig: this.options.providerConfig,
@@ -173,6 +192,7 @@ export class AgentRunner {
     if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.kill") return;
 
     const exitAfterCommand = type !== "agent.restart";
+    if (exitAfterCommand) this.exitCommandInProgress = true;
     this.claims.startClaim("command", commandId);
     this.publishStatus();
     await this.updateCommand(commandId, "accepted");
@@ -180,7 +200,14 @@ export class AgentRunner {
     try {
       if (type === "agent.restart") await this.restartProvider();
       else await this.shutdownProvider(type === "agent.kill");
-      await this.updateCommand(commandId, "succeeded", { action: type, agentId: this.agentId, runnerId: this.options.runnerId });
+      await this.updateCommand(commandId, "succeeded", {
+        action: type,
+        agentId: this.agentId,
+        runnerId: this.options.runnerId,
+        policyName: this.options.policyName,
+        spawnRequestId: this.options.spawnRequestId,
+        reason: typeof params.reason === "string" ? params.reason : undefined,
+      });
     } catch (error) {
       await this.updateCommand(commandId, "failed", undefined, error instanceof Error ? error.message : String(error)).catch(() => {});
     } finally {
@@ -251,6 +278,10 @@ export class AgentRunner {
       ready: agentStatus !== "offline" && !this.stopped,
       meta: {
         runnerId: this.options.runnerId,
+        startedAt: this.options.startedAt,
+        tmuxSession: this.options.tmuxSession ?? null,
+        policyName: this.options.policyName ?? null,
+        spawnRequestId: this.options.spawnRequestId ?? null,
         ...(status === "error" ? { terminalStatus: "error" } : {}),
         busyReasons: this.claims.reasons(),
         transport: this.bus.transportState,
@@ -259,20 +290,41 @@ export class AgentRunner {
   }
 
   private matchesMessage(message: Message): boolean {
-    if (message.to === this.agentId || message.to === "broadcast") return true;
-    if (message.to === `label:${this.options.label}`) return true;
-    if (message.to.startsWith("tag:")) {
-      const tag = message.to.slice("tag:".length);
-      return this.options.providerConfig.defaultTags.includes(tag) || tag === this.options.provider;
-    }
-    if (message.to.startsWith("cap:")) {
-      const cap = message.to.slice("cap:".length);
-      return this.options.providerConfig.defaultCapabilities.includes(cap);
-    }
-    return false;
+    return runnerMessageMatches(message, {
+      agentId: this.agentId,
+      label: this.options.label,
+      provider: this.options.provider,
+      tags: this.options.tags,
+      capabilities: this.options.capabilities,
+      defaultTags: this.options.providerConfig.defaultTags,
+      defaultCapabilities: this.options.providerConfig.defaultCapabilities,
+    });
   }
 }
 
+export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAgent">, target: {
+  agentId: string;
+  label?: string;
+  provider: string;
+  tags: string[];
+  capabilities: string[];
+  defaultTags: string[];
+  defaultCapabilities: string[];
+}): boolean {
+  if (message.resolvedToAgent === target.agentId) return true;
+  if (message.to === target.agentId || message.to === "broadcast") return true;
+  if (target.label && message.to === `label:${target.label}`) return true;
+  if (message.to.startsWith("tag:")) {
+    const tag = message.to.slice("tag:".length);
+    return target.tags.includes(tag) || target.defaultTags.includes(tag) || tag === target.provider;
+  }
+  if (message.to.startsWith("cap:")) {
+    const cap = message.to.slice("cap:".length);
+    return target.capabilities.includes(cap) || target.defaultCapabilities.includes(cap);
+  }
+  return false;
+}
+
 function csvTags(raw: string | undefined): string[] {
   return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
 }
@@ -294,6 +346,10 @@ export function runnerBusErrorAction(code: string, stopped: boolean): "ignore" |
   return "log";
 }
 
+export function runnerShouldResolveProviderExit(status: SemanticStatus, exitCommandInProgress: boolean): boolean {
+  return !exitCommandInProgress && (status === "offline" || status === "error");
+}
+
 function lifecycleCapabilities(): Record<string, true> {
   return {
     shutdownHard: true,