tokenmaxxing 1.6.0 → 1.8.0

package/src/lib/relay/config.ts

@@ -0,0 +1,84 @@
+// $TOKENMAXXING_HOME/relay.json - sparse overrides merged with defaults.
+
+import { existsSync, readFileSync } from "node:fs";
+import { z } from "zod";
+import { paths } from "../paths.ts";
+import { writeFileAtomic } from "../atomic.ts";
+import { ClaudePermissionModeSchema } from "./modes.ts";
+
+const WorkerSchema = z.enum(["claude", "codex"]);
+export type RelayWorker = z.infer<typeof WorkerSchema>;
+
+const HostsSchema = z.object({
+  cursor: z.object({ model: z.string().min(1).optional() }).default({}),
+  claude: z.object({ model: z.string().min(1).optional() }).default({}),
+}).default({ cursor: {}, claude: {} });
+
+export const RelayConfigFileSchema = z.object({
+  defaultWorker: WorkerSchema.optional(),
+  defaultPermissionMode: ClaudePermissionModeSchema.optional(),
+  turnTimeoutMs: z.number().int().positive().optional(),
+  decideTimeoutMs: z.number().int().positive().optional(),
+  idleTtlMs: z.number().int().positive().optional(),
+  sameSessionBusyMs: z.number().int().positive().optional(),
+  sessionPrefix: z.string().min(1).optional(),
+  hosts: HostsSchema.optional(),
+});
+export type RelayConfigFile = z.infer<typeof RelayConfigFileSchema>;
+
+export const RelayConfigSchema = z.object({
+  defaultWorker: WorkerSchema,
+  defaultPermissionMode: ClaudePermissionModeSchema,
+  turnTimeoutMs: z.number().int().positive(),
+  decideTimeoutMs: z.number().int().positive(),
+  idleTtlMs: z.number().int().positive(),
+  sameSessionBusyMs: z.number().int().positive(),
+  sessionPrefix: z.string().min(1),
+  hosts: z.object({
+    cursor: z.object({ model: z.string().min(1).optional() }),
+    claude: z.object({ model: z.string().min(1).optional() }),
+  }),
+});
+export type RelayConfig = z.infer<typeof RelayConfigSchema>;
+
+export const DEFAULT_RELAY_CONFIG: RelayConfig = {
+  defaultWorker: "claude",
+  defaultPermissionMode: "auto",
+  turnTimeoutMs: 30 * 60 * 1000,
+  decideTimeoutMs: 30 * 60 * 1000,
+  idleTtlMs: 60 * 60 * 1000,
+  sameSessionBusyMs: 50,
+  sessionPrefix: "xx-relay-",
+  hosts: { cursor: {}, claude: {} },
+};
+
+export function loadRelayConfig(): RelayConfig {
+  if (!existsSync(paths.relayJson)) return DEFAULT_RELAY_CONFIG;
+  const raw = RelayConfigFileSchema.parse(JSON.parse(readFileSync(paths.relayJson, "utf8")));
+  return RelayConfigSchema.parse({
+    ...DEFAULT_RELAY_CONFIG,
+    ...raw,
+    hosts: {
+      cursor: { ...DEFAULT_RELAY_CONFIG.hosts.cursor, ...raw.hosts?.cursor },
+      claude: { ...DEFAULT_RELAY_CONFIG.hosts.claude, ...raw.hosts?.claude },
+    },
+    defaultPermissionMode: raw.defaultPermissionMode ?? DEFAULT_RELAY_CONFIG.defaultPermissionMode,
+  });
+}
+
+export function writeRelayConfig(input: { file: RelayConfigFile }): void {
+  const validated = RelayConfigFileSchema.parse(input.file);
+  writeFileAtomic(paths.relayJson, JSON.stringify(validated, null, 2) + "\n");
+}
+
+export function mergeRelayConfigFile(input: { patch: RelayConfigFile }): RelayConfig {
+  const existing = existsSync(paths.relayJson)
+    ? RelayConfigFileSchema.parse(JSON.parse(readFileSync(paths.relayJson, "utf8")))
+    : {};
+  const next = RelayConfigFileSchema.parse({ ...existing, ...input.patch, hosts: {
+    cursor: { ...existing.hosts?.cursor, ...input.patch.hosts?.cursor },
+    claude: { ...existing.hosts?.claude, ...input.patch.hosts?.claude },
+  } });
+  writeRelayConfig({ file: next });
+  return loadRelayConfig();
+}

package/src/lib/relay/decide.ts

@@ -0,0 +1,75 @@
+// relay decide: approve/deny a pending permission ping and resume the wait.
+
+import { delay } from "es-toolkit";
+import { loadRelayConfig } from "./config.ts";
+import {
+  clearPendingRequest,
+  listPendingRequests,
+  readPendingRequest,
+  writeDecision,
+} from "./markers.ts";
+import { runTurn, type TurnResult } from "./turn.ts";
+import { readEntry, touchEntry, withSessionLock } from "./registry.ts";
+
+export type DecideParams = {
+  sessionId: string;
+  requestId?: string;
+  approve: boolean;
+  /** After writing the decision, wait for turn-done or the next ping. */
+  wait?: boolean;
+  cwd?: string;
+  timeoutMs?: number;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+export async function runDecide(input: DecideParams): Promise<{
+  decisionWritten: boolean;
+  requestId: string;
+  turn?: TurnResult;
+}> {
+  const entry = readEntry({ sessionId: input.sessionId });
+  if (entry == null) throw new Error(`relay session not found: ${input.sessionId}`);
+
+  let requestId = input.requestId ?? entry.pendingRequestId;
+  if (requestId == null) {
+    const pending = listPendingRequests({ sessionId: input.sessionId });
+    requestId = pending[0]?.requestId;
+  }
+  if (requestId == null) throw new Error(`no pending permission request for session ${input.sessionId}`);
+
+  const pending = readPendingRequest({ sessionId: input.sessionId, requestId });
+  if (pending == null) throw new Error(`pending request not found: ${requestId}`);
+
+  writeDecision({
+    sessionId: input.sessionId,
+    requestId,
+    approve: input.approve,
+    now: (input.now ?? Date.now)(),
+  });
+  clearPendingRequest({ sessionId: input.sessionId, requestId });
+  await withSessionLock({
+    sessionId: input.sessionId,
+    fn: () => touchEntry({
+      sessionId: input.sessionId,
+      state: "running",
+      pendingRequestId: null,
+      now: (input.now ?? Date.now)(),
+    }),
+  });
+
+  if (input.wait === false) {
+    return { decisionWritten: true, requestId };
+  }
+
+  const cfg = loadRelayConfig();
+  const turn = await runTurn({
+    sessionId: input.sessionId,
+    cwd: input.cwd ?? entry.cwd,
+    waitOnly: true,
+    timeoutMs: input.timeoutMs ?? cfg.decideTimeoutMs,
+    now: input.now,
+    sleep: input.sleep ?? delay,
+  });
+  return { decisionWritten: true, requestId, turn };
+}

package/src/lib/relay/gc.ts

@@ -0,0 +1,80 @@
+// relay destroy / gc / status. Exact tmux session names only; never pattern-kill.
+
+import { rmSync } from "node:fs";
+import { loadRelayConfig } from "./config.ts";
+import { clearSessionMarkers } from "./markers.ts";
+import {
+  deleteEntry,
+  listEntries,
+  readEntry,
+  sessionLockPath,
+  withSessionLock,
+  type RelayRegistryEntry,
+} from "./registry.ts";
+import { getTmux } from "./tmux.ts";
+
+export async function destroySession(input: { sessionId: string }): Promise<boolean> {
+  const entry = readEntry({ sessionId: input.sessionId });
+  if (entry == null) {
+    // Still try exact tmux name from config prefix in case registry was lost.
+    return false;
+  }
+  await withSessionLock({
+    sessionId: input.sessionId,
+    fn: () => {
+      getTmux().killSession({ name: entry.tmuxName });
+      clearSessionMarkers({ sessionId: input.sessionId });
+      deleteEntry({ sessionId: input.sessionId });
+      rmSync(sessionLockPath({ sessionId: input.sessionId }), { force: true });
+    },
+  });
+  return true;
+}
+
+export type GcResult = {
+  reaped: string[];
+  kept: string[];
+};
+
+/** Reap dead tmux sessions and idle sessions past idleTtlMs. */
+export async function gcSessions(input: { now?: number; idleTtlMs?: number } = {}): Promise<GcResult> {
+  const cfg = loadRelayConfig();
+  const now = input.now ?? Date.now();
+  const idleTtlMs = input.idleTtlMs ?? cfg.idleTtlMs;
+  const reaped: string[] = [];
+  const kept: string[] = [];
+  const tmux = getTmux();
+
+  for (const entry of listEntries()) {
+    const alive = tmux.hasSession({ name: entry.tmuxName });
+    const idleTooLong = now - entry.lastActiveAt > idleTtlMs;
+    if (!alive || idleTooLong || entry.state === "destroyed") {
+      await destroySession({ sessionId: entry.sessionId });
+      reaped.push(entry.sessionId);
+      continue;
+    }
+    kept.push(entry.sessionId);
+  }
+  return { reaped, kept };
+}
+
+export function statusSessions(): RelayRegistryEntry[] {
+  const tmux = getTmux();
+  return listEntries().map((entry) => ({
+    ...entry,
+    // annotate liveness in a non-schema field via spread for printers; keep schema pure
+  })).map((entry) => {
+    void tmux.hasSession({ name: entry.tmuxName });
+    return entry;
+  });
+}
+
+export type StatusRow = RelayRegistryEntry & { tmuxAlive: boolean };
+
+export function statusRows(): StatusRow[] {
+  const tmux = getTmux();
+  return listEntries().map((entry) => ({
+    ...entry,
+    tmuxAlive: tmux.hasSession({ name: entry.tmuxName }),
+  }));
+}

package/src/lib/relay/install.ts

@@ -0,0 +1,143 @@
+// relay install: write thin host agent templates + optional hook snippets.
+// Merge only tokenmaxxing-owned keys.
+
+import { existsSync, mkdirSync, readFileSync, cpSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "../atomic.ts";
+import { paths } from "../paths.ts";
+import { isOurHookCommand } from "../settings.ts";
+
+const pluginRoot = () => join(import.meta.dir, "../../../agent-plugin");
+
+function repoAgentsDir(): string {
+  return join(pluginRoot(), "agents");
+}
+
+function repoSkillDir(): string {
+  return join(pluginRoot(), "skills", "relay-session");
+}
+
+function repoHooksDir(): string {
+  return join(pluginRoot(), "hooks");
+}
+
+export type InstallTarget = "cursor" | "claude" | "all";
+
+export type InstallResult = {
+  agentsWritten: string[];
+  skillWritten: boolean;
+  hooksMerged: string[];
+};
+
+function copyAgent(input: { name: string; destDir: string }): string {
+  mkdirSync(input.destDir, { recursive: true });
+  const src = join(repoAgentsDir(), input.name);
+  const dest = join(input.destDir, input.name);
+  if (!existsSync(src)) throw new Error(`missing agent template: ${src}`);
+  cpSync(src, dest);
+  return dest;
+}
+
+function copySkill(input: { destDir: string }): boolean {
+  const src = repoSkillDir();
+  if (!existsSync(src)) return false;
+  mkdirSync(input.destDir, { recursive: true });
+  cpSync(src, input.destDir, { recursive: true });
+  return true;
+}
+
+const CursorHooksSchema = z.looseObject({
+  version: z.number().optional(),
+  hooks: z.record(z.string(), z.unknown()).optional(),
+});
+
+const TOKENMAXXING_HOOK_KEY = "tokenmaxxingRelay";
+
+/** Merge Cursor hooks.json: only the tokenmaxxingRelay key is ours. */
+export function mergeCursorHooks(input: { hooksPath: string }): boolean {
+  const snippetPath = join(repoHooksDir(), "cursor-relay.json");
+  if (!existsSync(snippetPath)) return false;
+  const snippet = CursorHooksSchema.parse(JSON.parse(readFileSync(snippetPath, "utf8")));
+  let existing: z.infer<typeof CursorHooksSchema> = { version: 1, hooks: {} };
+  if (existsSync(input.hooksPath)) {
+    try {
+      existing = CursorHooksSchema.parse(JSON.parse(readFileSync(input.hooksPath, "utf8")));
+    } catch {
+      existing = { version: 1, hooks: {} };
+    }
+  }
+  existing.hooks ??= {};
+  const ours = snippet.hooks?.[TOKENMAXXING_HOOK_KEY];
+  if (ours === undefined) return false;
+  existing.hooks[TOKENMAXXING_HOOK_KEY] = ours;
+  mkdirSync(dirname(input.hooksPath), { recursive: true });
+  writeFileAtomic(input.hooksPath, JSON.stringify(existing, null, 2) + "\n");
+  return true;
+}
+
+const ClaudeSettingsLoose = z.looseObject({
+  hooks: z.record(z.string(), z.array(z.looseObject({
+    matcher: z.string().optional(),
+    hooks: z.array(z.looseObject({ type: z.string(), command: z.string() })).default([]),
+  }))).optional(),
+});
+
+const RELAY_PERM_SUB = "__relay-permission-hook";
+
+/** Append PermissionRequest hook for relay; never remove foreign hooks. */
+export function mergeClaudeRelayPermissionHook(input: { settingsPath?: string } = {}): boolean {
+  const settingsPath = input.settingsPath ?? paths.claudeSettings;
+  const bin = join(paths.binDir, "tokenmaxxing");
+  const command = `${JSON.stringify(bin)} ${RELAY_PERM_SUB}`;
+  let settings: z.infer<typeof ClaudeSettingsLoose> = {};
+  if (existsSync(settingsPath)) {
+    settings = ClaudeSettingsLoose.parse(JSON.parse(readFileSync(settingsPath, "utf8")));
+  }
+  settings.hooks ??= {};
+  settings.hooks.PermissionRequest ??= [];
+  const arr = settings.hooks.PermissionRequest;
+  const present = arr.some((g) => g.hooks.some((h) => h.command === command || isOurHookCommand(h.command, RELAY_PERM_SUB)));
+  if (!present) {
+    arr.push({ hooks: [{ type: "command", command }] });
+  }
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  const mode = existsSync(settingsPath) ? 0o600 : 0o600;
+  writeFileAtomic(settingsPath, JSON.stringify(settings, null, 2) + "\n", mode);
+  return true;
+}
+
+export function installRelayHosts(input: {
+  target: InstallTarget;
+  cursorAgentsDir?: string;
+  claudeAgentsDir?: string;
+  cursorHooksPath?: string;
+  mergeHooks?: boolean;
+}): InstallResult {
+  const home = process.env.HOME ?? "";
+  const cursorAgents = input.cursorAgentsDir ?? join(home, ".cursor", "agents");
+  const claudeAgents = input.claudeAgentsDir ?? join(home, ".claude", "agents");
+  const agentsWritten: string[] = [];
+  const hooksMerged: string[] = [];
+  let skillWritten = false;
+
+  if (input.target === "cursor" || input.target === "all") {
+    agentsWritten.push(copyAgent({ name: "tokenmaxxing-claude.md", destDir: cursorAgents }));
+    agentsWritten.push(copyAgent({ name: "tokenmaxxing-codex.md", destDir: cursorAgents }));
+    skillWritten = copySkill({ destDir: join(home, ".cursor", "skills", "relay-session") }) || skillWritten;
+    if (input.mergeHooks !== false) {
+      const hooksPath = input.cursorHooksPath ?? join(home, ".cursor", "hooks.json");
+      if (mergeCursorHooks({ hooksPath })) hooksMerged.push(hooksPath);
+    }
+  }
+  if (input.target === "claude" || input.target === "all") {
+    agentsWritten.push(copyAgent({ name: "tokenmaxxing-claude.md", destDir: claudeAgents }));
+    agentsWritten.push(copyAgent({ name: "tokenmaxxing-codex.md", destDir: claudeAgents }));
+    if (input.mergeHooks !== false) {
+      if (mergeClaudeRelayPermissionHook()) hooksMerged.push(paths.claudeSettings);
+    }
+  }
+  return { agentsWritten, skillWritten, hooksMerged };
+}
+
+export { RELAY_PERM_SUB };

package/src/lib/relay/markers.ts

@@ -0,0 +1,148 @@
+// Additive turn-done and permission-needed markers under relayDir.
+// Never writes into respawn/.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, readdirSync } from "node:fs";
+import { z } from "zod";
+import { writeFileAtomic } from "../atomic.ts";
+import {
+  decisionPath,
+  pendingRequestPath,
+  relayDecisionsDir,
+  relayPendingDir,
+  relayTurnDoneDir,
+  turnDonePath,
+} from "./registry.ts";
+
+export const TurnDoneMarkerSchema = z.object({
+  sessionId: z.uuid(),
+  ts: z.number().int().nonnegative(),
+  source: z.enum(["claude-stop", "codex-stop", "test"]).default("claude-stop"),
+});
+export type TurnDoneMarker = z.infer<typeof TurnDoneMarkerSchema>;
+
+export const PendingRequestSchema = z.object({
+  requestId: z.string().min(1),
+  sessionId: z.uuid(),
+  summary: z.string(),
+  detail: z.string(),
+  ts: z.number().int().nonnegative(),
+});
+export type PendingRequest = z.infer<typeof PendingRequestSchema>;
+
+export const DecisionSchema = z.object({
+  requestId: z.string().min(1),
+  sessionId: z.uuid(),
+  approve: z.boolean(),
+  ts: z.number().int().nonnegative(),
+});
+export type Decision = z.infer<typeof DecisionSchema>;
+
+/** Write a turn-done marker for a relay session. Additive; never touches respawn/. */
+export function writeTurnDoneMarker(input: {
+  sessionId: string;
+  source?: TurnDoneMarker["source"];
+  now?: number;
+}): void {
+  mkdirSync(relayTurnDoneDir(), { recursive: true });
+  const payload = TurnDoneMarkerSchema.parse({
+    sessionId: input.sessionId,
+    ts: input.now ?? Date.now(),
+    source: input.source ?? "claude-stop",
+  });
+  writeFileAtomic(turnDonePath({ sessionId: input.sessionId }), JSON.stringify(payload) + "\n");
+}
+
+export function readTurnDoneMarker(input: { sessionId: string }): TurnDoneMarker | null {
+  const path = turnDonePath(input);
+  if (!existsSync(path)) return null;
+  return TurnDoneMarkerSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function clearTurnDoneMarker(input: { sessionId: string }): void {
+  rmSync(turnDonePath(input), { force: true });
+}
+
+export function writePendingRequest(input: {
+  sessionId: string;
+  requestId: string;
+  summary: string;
+  detail: string;
+  now?: number;
+}): PendingRequest {
+  const payload = PendingRequestSchema.parse({
+    requestId: input.requestId,
+    sessionId: input.sessionId,
+    summary: input.summary,
+    detail: input.detail,
+    ts: input.now ?? Date.now(),
+  });
+  writeFileAtomic(
+    pendingRequestPath({ sessionId: input.sessionId, requestId: input.requestId }),
+    JSON.stringify(payload, null, 2) + "\n",
+  );
+  return payload;
+}
+
+export function readPendingRequest(input: { sessionId: string; requestId: string }): PendingRequest | null {
+  const path = pendingRequestPath(input);
+  if (!existsSync(path)) return null;
+  return PendingRequestSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function listPendingRequests(input: { sessionId: string }): PendingRequest[] {
+  const dir = `${relayPendingDir()}/${input.sessionId}`;
+  if (!existsSync(dir)) return [];
+  const out: PendingRequest[] = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      out.push(PendingRequestSchema.parse(JSON.parse(readFileSync(`${dir}/${name}`, "utf8"))));
+    } catch {
+      // skip
+    }
+  }
+  return out.sort((a, b) => a.ts - b.ts);
+}
+
+export function clearPendingRequest(input: { sessionId: string; requestId: string }): void {
+  rmSync(pendingRequestPath(input), { force: true });
+}
+
+export function writeDecision(input: {
+  sessionId: string;
+  requestId: string;
+  approve: boolean;
+  now?: number;
+}): Decision {
+  mkdirSync(`${relayDecisionsDir()}/${input.sessionId}`, { recursive: true });
+  const payload = DecisionSchema.parse({
+    requestId: input.requestId,
+    sessionId: input.sessionId,
+    approve: input.approve,
+    ts: input.now ?? Date.now(),
+  });
+  writeFileAtomic(
+    decisionPath({ sessionId: input.sessionId, requestId: input.requestId }),
+    JSON.stringify(payload, null, 2) + "\n",
+  );
+  return payload;
+}
+
+export function readDecision(input: { sessionId: string; requestId: string }): Decision | null {
+  const path = decisionPath(input);
+  if (!existsSync(path)) return null;
+  return DecisionSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function clearDecision(input: { sessionId: string; requestId: string }): void {
+  rmSync(decisionPath(input), { force: true });
+}
+
+/** Clear all marker artifacts for a session (destroy/gc). Does not touch respawn/. */
+export function clearSessionMarkers(input: { sessionId: string }): void {
+  clearTurnDoneMarker(input);
+  const pendingDir = `${relayPendingDir()}/${input.sessionId}`;
+  const decisionsDir = `${relayDecisionsDir()}/${input.sessionId}`;
+  rmSync(pendingDir, { recursive: true, force: true });
+  rmSync(decisionsDir, { recursive: true, force: true });
+}

package/src/lib/relay/modes.ts

@@ -0,0 +1,82 @@
+// Claude Code permission-mode vocabulary for the relay worker, plus the Codex
+// sandbox / ask-for-approval mapping. Host terms only: never invent alternate
+// security labels. `manual` aliases Claude's `default` (≥2.1.200 UI name).
+
+import { z } from "zod";
+
+export const ClaudePermissionModes = [
+  "default",
+  "acceptEdits",
+  "plan",
+  "auto",
+  "dontAsk",
+  "bypassPermissions",
+] as const;
+
+export const ClaudePermissionModeSchema = z.enum(ClaudePermissionModes);
+export type ClaudePermissionMode = z.infer<typeof ClaudePermissionModeSchema>;
+
+const AliasSchema = z.enum(["manual", "yolo", "dangerous"]);
+
+/** Parse a host/CLI permission-mode token into a Claude mode. */
+export function parsePermissionMode(input: { raw: string }): ClaudePermissionMode {
+  const trimmed = input.raw.trim();
+  const alias = AliasSchema.safeParse(trimmed);
+  if (alias.success) {
+    if (alias.data === "manual") return "default";
+    return "bypassPermissions";
+  }
+  return ClaudePermissionModeSchema.parse(trimmed);
+}
+
+export function tryParsePermissionMode(input: { raw: string }): ClaudePermissionMode | null {
+  try {
+    return parsePermissionMode(input);
+  } catch {
+    return null;
+  }
+}
+
+export type CodexAskForApproval = "untrusted" | "on-failure" | "on-request" | "never";
+
+export type CodexSpawnFlags = {
+  sandbox: "read-only" | "workspace-write" | "danger-full-access";
+  askForApproval: CodexAskForApproval;
+};
+
+/** Map a Claude permission-mode name onto Codex CLI flags. */
+export function codexFlagsForMode(input: { mode: ClaudePermissionMode }): CodexSpawnFlags {
+  switch (input.mode) {
+    case "plan":
+    case "default":
+      return { sandbox: "read-only", askForApproval: "on-request" };
+    case "acceptEdits":
+      return { sandbox: "workspace-write", askForApproval: "on-request" };
+    case "auto":
+      return { sandbox: "workspace-write", askForApproval: "on-request" };
+    case "dontAsk":
+      return { sandbox: "read-only", askForApproval: "never" };
+    case "bypassPermissions":
+      return { sandbox: "danger-full-access", askForApproval: "never" };
+  }
+}
+
+/** Claude argv fragment for a permission mode (includes allow-dangerously when needed). */
+export function claudeArgvForMode(input: { mode: ClaudePermissionMode }): string[] {
+  const args = ["--permission-mode", input.mode];
+  if (input.mode === "bypassPermissions") {
+    args.push("--dangerously-skip-permissions");
+  }
+  return args;
+}
+
+/** Codex argv fragment for a Claude-named mode. */
+export function codexArgvForMode(input: { mode: ClaudePermissionMode }): string[] {
+  const flags = codexFlagsForMode(input);
+  return ["--sandbox", flags.sandbox, "--ask-for-approval", flags.askForApproval];
+}
+
+/** Under bypassPermissions, worker permission pings must not surface to main. */
+export function permissionPingsEnabled(input: { mode: ClaudePermissionMode }): boolean {
+  return input.mode !== "bypassPermissions";
+}

package/src/lib/relay/protocol.ts

@@ -0,0 +1,61 @@
+// Shared stdout contract for cheap host relay agents.
+
+import type { ClaudePermissionMode } from "./modes.ts";
+
+export type TurnOutput = {
+  sessionId: string;
+  permissionMode: ClaudePermissionMode;
+  kind: "turn-done";
+  text: string;
+};
+
+export type PermissionNeededOutput = {
+  sessionId: string;
+  permissionMode: ClaudePermissionMode;
+  kind: "permission-needed";
+  requestId: string;
+  summary: string;
+  detail: string;
+};
+
+export type RelayStdout = TurnOutput | PermissionNeededOutput;
+
+export function formatRelayStdout(input: { payload: RelayStdout }): string {
+  const p = input.payload;
+  const lines = [
+    `session: ${p.sessionId}`,
+    `permission-mode: ${p.permissionMode}`,
+  ];
+  if (p.kind === "permission-needed") {
+    lines.push(`permission-needed: ${p.requestId}`);
+    lines.push(`summary: ${p.summary}`);
+    lines.push(`detail: ${p.detail}`);
+    lines.push(`session: ${p.sessionId}`);
+    lines.push(`permission-mode: ${p.permissionMode}`);
+  } else if (p.text.trim() !== "") {
+    lines.push(p.text.replace(/\s+$/, ""));
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function parseRelayStdout(input: { text: string }): {
+  sessionId: string | null;
+  permissionMode: string | null;
+  requestId: string | null;
+  summary: string | null;
+  detail: string | null;
+} {
+  let sessionId: string | null = null;
+  let permissionMode: string | null = null;
+  let requestId: string | null = null;
+  let summary: string | null = null;
+  let detail: string | null = null;
+  for (const line of input.text.split("\n")) {
+    if (line.startsWith("session: ")) sessionId = line.slice("session: ".length).trim();
+    else if (line.startsWith("permission-mode: ")) permissionMode = line.slice("permission-mode: ".length).trim();
+    else if (line.startsWith("permission-needed: ")) requestId = line.slice("permission-needed: ".length).trim();
+    else if (line.startsWith("summary: ")) summary = line.slice("summary: ".length);
+    else if (line.startsWith("detail: ")) detail = line.slice("detail: ".length);
+  }
+  return { sessionId, permissionMode, requestId, summary, detail };
+}