@ctliz/agent-intercom-claude 0.12.0-connect.3

package/claude/team.ts

@@ -0,0 +1,348 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { PARTICIPANT_STATES, TERMINAL_PARTICIPANT_STATES } from "@ctliz/agent-intercom-core/boss";
+import type { BossSessionMetadata } from "../types.ts";
+import { getAgentDirPath } from "../broker/paths.ts";
+
+export interface TeamSession {
+  id: string;
+  name?: string;
+  /** Already parsed and broker-authenticated by the client session decoder. */
+  boss?: Pick<BossSessionMetadata, "binding" | "principal" | "liveWorker">;
+}
+
+interface StoredWorker {
+  id?: unknown;
+  runId?: unknown;
+  workerIncarnationId?: unknown;
+  workerGeneration?: unknown;
+  bossRunId?: unknown;
+  participantId?: unknown;
+  bindingEpoch?: unknown;
+  sessionId?: unknown;
+  harness?: unknown;
+  role?: unknown;
+  state?: unknown;
+  owned?: unknown;
+  managerSessionId?: unknown;
+  intercomTarget?: unknown;
+}
+
+export interface TeamMember {
+  id: string;
+  target: string;
+  harness?: string;
+  role?: string;
+  state?: string;
+  connected: boolean;
+}
+
+export interface IntercomTeam {
+  teamId?: string;
+  self: { id: string; workerId?: string; isManager: boolean };
+  manager?: { target: string; connected: boolean };
+  coworkers: TeamMember[];
+}
+
+const LEGACY_LIVE_STATES = new Set(["provisioning", "running", "idle", "needs_attention", "stopping"]);
+const BOSS_NONTERMINAL_STATES: ReadonlySet<string> = new Set(
+  PARTICIPANT_STATES.filter((state) => !(TERMINAL_PARTICIPANT_STATES as readonly string[]).includes(state)),
+);
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function exactStringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+function positiveIntegerString(value: unknown): number | undefined {
+  if (typeof value !== "string" || !/^[1-9]\d*$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function connectedTo(sessions: TeamSession[], target: string): boolean {
+  const normalized = target.toLowerCase();
+  return sessions.some((session) => session.id === target || session.name?.toLowerCase() === normalized);
+}
+
+async function readWorkers(agentDir: string): Promise<StoredWorker[]> {
+  try {
+    const parsed = JSON.parse(await readFile(join(agentDir, "intercom", "orchestrator", "workers.json"), "utf8")) as { workers?: unknown };
+    return Array.isArray(parsed.workers) ? parsed.workers as StoredWorker[] : [];
+  } catch {
+    return [];
+  }
+}
+
+function bossSessionHasExactAuthority(session: TeamSession): boolean {
+  const binding = session.boss?.binding;
+  const principal = session.boss?.principal;
+  const liveWorker = session.boss?.liveWorker;
+  const liveIdentity = liveWorker?.identity;
+  return binding !== undefined
+    && principal !== undefined
+    && liveWorker !== undefined
+    && liveIdentity !== undefined
+    && binding.sessionId === session.id
+    && binding.state === "active"
+    && principal.principalClass === "boss-private"
+    && principal.principalId === session.id
+    && principal.state === "active"
+    && principal.bossRunId === binding.bossRunId
+    && principal.participantId === binding.participantId
+    && principal.role === binding.role
+    && principal.bindingEpoch === binding.bindingEpoch
+    && principal.assignedManagerParticipantId === binding.assignedManagerParticipantId
+    && ((binding.role === "worker" || binding.role === "scout") === (binding.assignedManagerParticipantId !== undefined))
+    && ((principal.role === "manager") === Array.isArray(principal.assignedParticipantIds))
+    && (principal.role === "manager" || principal.assignedParticipantIds === undefined)
+    && liveIdentity.workerId === session.id
+    && "bossRunId" in liveIdentity
+    && liveIdentity.bossRunId === binding.bossRunId
+    && liveIdentity.participantId === binding.participantId
+    && liveIdentity.bindingEpoch === binding.bindingEpoch
+    && BOSS_NONTERMINAL_STATES.has(liveWorker.state);
+}
+
+function bossWorkerMatchesSession(worker: StoredWorker, session: TeamSession): boolean {
+  const binding = session.boss?.binding;
+  const liveWorker = session.boss?.liveWorker;
+  const liveIdentity = liveWorker?.identity;
+  const id = exactStringValue(worker.id);
+  const target = exactStringValue(worker.intercomTarget);
+  const storedSessionId = exactStringValue(worker.sessionId) ?? target;
+  return bossSessionHasExactAuthority(session)
+    && binding !== undefined
+    && liveWorker !== undefined
+    && liveIdentity !== undefined
+    && worker.owned === true
+    && id !== undefined
+    && target === id
+    && storedSessionId === id
+    && session.id === id
+    && binding.sessionId === session.id
+    && binding.state === "active"
+    && BOSS_NONTERMINAL_STATES.has(liveWorker.state)
+    && exactStringValue(worker.state) === liveWorker.state
+    && exactStringValue(worker.bossRunId) === binding.bossRunId
+    && exactStringValue(worker.participantId) === binding.participantId
+    && positiveInteger(worker.bindingEpoch) === binding.bindingEpoch
+    && exactStringValue(worker.role) === binding.role
+    && liveIdentity.workerId === id
+    && liveIdentity.workerId === session.id
+    && liveIdentity.workerIncarnationId === exactStringValue(worker.workerIncarnationId)
+    && liveIdentity.workerGeneration === positiveInteger(worker.workerGeneration)
+    && liveIdentity.bossRunId === binding.bossRunId
+    && liveIdentity.participantId === binding.participantId
+    && liveIdentity.bindingEpoch === binding.bindingEpoch;
+}
+
+function isReciprocallyAssignedToManager(workerSession: TeamSession, managerSession: TeamSession): boolean {
+  const workerBinding = workerSession.boss?.binding;
+  const workerPrincipal = workerSession.boss?.principal;
+  const managerBinding = managerSession.boss?.binding;
+  const managerPrincipal = managerSession.boss?.principal;
+  return bossSessionHasExactAuthority(workerSession)
+    && bossSessionHasExactAuthority(managerSession)
+    && (workerBinding?.role === "worker" || workerBinding?.role === "scout")
+    && workerPrincipal?.role === workerBinding.role
+    && managerBinding?.role === "manager"
+    && managerPrincipal?.role === "manager"
+    && workerBinding.bossRunId === managerBinding.bossRunId
+    && workerBinding.assignedManagerParticipantId === managerBinding.participantId
+    && workerPrincipal.assignedManagerParticipantId === managerPrincipal.participantId
+    && managerPrincipal.assignedParticipantIds?.includes(workerBinding.participantId) === true;
+}
+
+function currentBossWorker(
+  workers: StoredWorker[],
+  self: TeamSession,
+  env: NodeJS.ProcessEnv,
+): StoredWorker | undefined {
+  const binding = self.boss?.binding;
+  const liveIdentity = self.boss?.liveWorker.identity;
+  if (!binding) return undefined;
+  const workerId = exactStringValue(env.AGENT_INTERCOM_WORKER_ID);
+  const incarnationId = exactStringValue(env.AGENT_INTERCOM_WORKER_INCARNATION_ID);
+  const deprecatedIncarnationId = exactStringValue(env.AGENT_INTERCOM_RUN_ID);
+  const workerGeneration = positiveIntegerString(env.AGENT_INTERCOM_WORKER_GENERATION);
+  const bindingEpoch = positiveIntegerString(env.AGENT_INTERCOM_BINDING_EPOCH);
+  if (
+    workerId === undefined
+    || incarnationId === undefined
+    || (deprecatedIncarnationId !== undefined && deprecatedIncarnationId !== incarnationId)
+    || workerGeneration === undefined
+    || bindingEpoch === undefined
+    || liveIdentity === undefined
+    || liveIdentity.workerId !== workerId
+    || liveIdentity.workerIncarnationId !== incarnationId
+    || liveIdentity.workerGeneration !== workerGeneration
+    || liveIdentity.bossRunId !== binding.bossRunId
+    || liveIdentity.participantId !== binding.participantId
+    || liveIdentity.bindingEpoch !== binding.bindingEpoch
+    || exactStringValue(env.AGENT_INTERCOM_BOSS_RUN_ID) !== binding.bossRunId
+    || exactStringValue(env.AGENT_INTERCOM_PARTICIPANT_ID) !== binding.participantId
+    || bindingEpoch !== binding.bindingEpoch
+  ) return undefined;
+
+  return workers.find((worker) =>
+    exactStringValue(worker.id) === workerId
+    && exactStringValue(worker.workerIncarnationId) === incarnationId
+    && positiveInteger(worker.workerGeneration) === workerGeneration
+    && bossWorkerMatchesSession(worker, self)
+  );
+}
+
+function teamMember(worker: StoredWorker, session: TeamSession): TeamMember {
+  const id = stringValue(worker.id)!;
+  return {
+    id,
+    target: id,
+    ...(stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {}),
+    ...(stringValue(worker.role) ? { role: stringValue(worker.role) } : {}),
+    ...(stringValue(worker.state) ? { state: stringValue(worker.state) } : {}),
+    connected: session.id === id,
+  };
+}
+
+function resolveLegacyTeam(
+  input: { selfId: string; sessions: TeamSession[] },
+  workers: StoredWorker[],
+  env: NodeJS.ProcessEnv,
+): IntercomTeam {
+  const workerId = stringValue(env.AGENT_INTERCOM_WORKER_ID);
+  const runId = stringValue(env.AGENT_INTERCOM_RUN_ID);
+  const current = workerId
+    ? workers.find((worker) =>
+      stringValue(worker.id) === workerId
+      && (!runId || stringValue(worker.runId) === runId)
+    )
+    : undefined;
+  const managerTarget = stringValue(current?.managerSessionId)
+    ?? stringValue(env.AGENT_INTERCOM_MANAGER_TARGET)
+    ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+  const teamId = managerTarget ?? input.selfId;
+  const coworkers = workers
+    .filter((worker) => worker.owned === true)
+    .filter((worker) => stringValue(worker.managerSessionId) === teamId)
+    .filter((worker) => LEGACY_LIVE_STATES.has(stringValue(worker.state) ?? ""))
+    .filter((worker) => stringValue(worker.id) !== workerId)
+    .map((worker): TeamMember | undefined => {
+      const id = stringValue(worker.id);
+      if (!id) return undefined;
+      const target = stringValue(worker.intercomTarget) ?? id;
+      return {
+        id,
+        target,
+        ...(stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {}),
+        ...(stringValue(worker.role) ? { role: stringValue(worker.role) } : {}),
+        ...(stringValue(worker.state) ? { state: stringValue(worker.state) } : {}),
+        connected: connectedTo(input.sessions, target),
+      };
+    })
+    .filter((member): member is TeamMember => Boolean(member));
+  return {
+    teamId,
+    self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: !managerTarget },
+    manager: managerTarget
+      ? { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) }
+      : { target: input.selfId, connected: true },
+    coworkers,
+  };
+}
+
+export async function resolveIntercomTeam(input: {
+  selfId: string;
+  sessions: TeamSession[];
+  env?: NodeJS.ProcessEnv;
+  agentDir?: string;
+}): Promise<IntercomTeam> {
+  const env = input.env ?? process.env;
+  const workers = await readWorkers(input.agentDir ?? getAgentDirPath());
+  const selfSession = input.sessions.find((session) => session.id === input.selfId);
+  if (!selfSession?.boss) return resolveLegacyTeam(input, workers, env);
+
+  const current = currentBossWorker(workers, selfSession, env);
+  const workerId = stringValue(env.AGENT_INTERCOM_WORKER_ID);
+  if (!current) {
+    return {
+      teamId: selfSession.boss.binding.bossRunId,
+      self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: false },
+      coworkers: [],
+    };
+  }
+
+  const currentRole = selfSession.boss.binding.role;
+  const selfIsManager = currentRole === "manager";
+  const configuredManagerTarget = selfIsManager ? input.selfId : exactStringValue(current.managerSessionId);
+  const managerSession = configuredManagerTarget === undefined
+    ? undefined
+    : input.sessions.find((session) => session.id === configuredManagerTarget);
+  const managerWorker = managerSession === undefined
+    ? undefined
+    : workers.find((worker) => exactStringValue(worker.id) === configuredManagerTarget && bossWorkerMatchesSession(worker, managerSession));
+  const managerTarget = selfIsManager
+    ? input.selfId
+    : managerWorker !== undefined
+      && managerSession?.boss?.binding.bossRunId === selfSession.boss.binding.bossRunId
+      && isReciprocallyAssignedToManager(selfSession, managerSession)
+      ? configuredManagerTarget
+      : undefined;
+
+  if (managerTarget === undefined) {
+    return {
+      teamId: selfSession.boss.binding.bossRunId,
+      self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: false },
+      coworkers: [],
+    };
+  }
+
+  const coworkers = workers
+    .filter((worker) => exactStringValue(worker.id) !== workerId)
+    .filter((worker) => exactStringValue(worker.managerSessionId) === managerTarget)
+    .map((worker): TeamMember | undefined => {
+      const id = exactStringValue(worker.id);
+      if (!id) return undefined;
+      const session = input.sessions.find((candidate) => candidate.id === id);
+      if (
+        session === undefined
+        || !bossWorkerMatchesSession(worker, session)
+        || session.boss?.binding.bossRunId !== selfSession.boss!.binding.bossRunId
+        || managerSession === undefined
+        || !isReciprocallyAssignedToManager(session, managerSession)
+      ) return undefined;
+      return teamMember(worker, session);
+    })
+    .filter((member): member is TeamMember => Boolean(member));
+
+  return {
+    teamId: selfSession.boss.binding.bossRunId,
+    self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: selfIsManager },
+    manager: { target: managerTarget, connected: true },
+    coworkers,
+  };
+}
+
+export function formatIntercomTeam(team: IntercomTeam): string {
+  const lines = [
+    `Manager: ${team.manager ? `${team.manager.target} [${team.manager.connected ? "connected" : "not connected"}]` : "unknown"}`,
+    `You: ${team.self.id}${team.self.isManager ? " [manager]" : ""}`,
+  ];
+  if (!team.coworkers.length) {
+    lines.push("Coworkers: none");
+  } else {
+    lines.push("Coworkers:");
+    for (const coworker of team.coworkers) {
+      const metadata = [coworker.harness, coworker.role, coworker.state].filter(Boolean).join(", ");
+      lines.push(`- ${coworker.id} target=${coworker.target}${metadata ? ` (${metadata})` : ""} [${coworker.connected ? "connected" : "not connected"}]`);
+    }
+  }
+  return lines.join("\n");
+}

package/claude/transport.ts

@@ -0,0 +1,97 @@
+import { spawnSync } from "node:child_process";
+
+export const CLAUDE_INTERCOM_TRANSPORT_ENV = "CLAUDE_INTERCOM_TRANSPORT";
+export const MIN_NATIVE_CLAUDE_VERSION = "2.1.220";
+export const MAX_NATIVE_CLAUDE_VERSION = "2.1.226";
+
+export type ClaudeIntercomTransport = "auto" | "native" | "mcp";
+export type ResolvedClaudeIntercomTransport = Exclude<ClaudeIntercomTransport, "auto">;
+
+export interface ClaudeVersionProbe {
+  command: string;
+  version: string | null;
+  compatible: boolean;
+  reason: string;
+}
+
+export interface ClaudeTransportResolution extends ClaudeVersionProbe {
+  requested: ClaudeIntercomTransport;
+  selected: ResolvedClaudeIntercomTransport;
+}
+
+export function parseClaudeIntercomTransport(value: unknown, source = "transport"): ClaudeIntercomTransport {
+  if (value === undefined || value === null || value === "") return "auto";
+  if (value === "auto" || value === "native" || value === "mcp") return value;
+  throw new Error(`${source} must be one of auto, native, or mcp`);
+}
+
+export function parseClaudeVersion(output: string): string | null {
+  const match = output.match(/(?:^|\s)(\d+\.\d+\.\d+)(?:\s|$)/);
+  return match?.[1] ?? null;
+}
+
+function compareVersions(left: string, right: string): number {
+  const a = left.split(".").map(Number);
+  const b = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+export function isNativeClaudeVersionCompatible(version: string): boolean {
+  return compareVersions(version, MIN_NATIVE_CLAUDE_VERSION) >= 0
+    && compareVersions(version, MAX_NATIVE_CLAUDE_VERSION) <= 0;
+}
+
+export function probeClaudeVersion(command = "claude"): ClaudeVersionProbe {
+  const result = spawnSync(command, ["--version"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.error || result.status !== 0) {
+    return {
+      command,
+      version: null,
+      compatible: false,
+      reason: `could not run ${command} --version`,
+    };
+  }
+  const version = parseClaudeVersion(`${result.stdout}\n${result.stderr}`);
+  if (!version) {
+    return { command, version: null, compatible: false, reason: "Claude version output was not recognized" };
+  }
+  const compatible = isNativeClaudeVersionCompatible(version);
+  return {
+    command,
+    version,
+    compatible,
+    reason: compatible
+      ? `Claude ${version} is within the native transport compatibility window ${MIN_NATIVE_CLAUDE_VERSION}-${MAX_NATIVE_CLAUDE_VERSION}`
+      : `Claude ${version} is outside the verified native transport compatibility window ${MIN_NATIVE_CLAUDE_VERSION}-${MAX_NATIVE_CLAUDE_VERSION}`,
+  };
+}
+
+export function resolveClaudeIntercomTransport(options: {
+  requested?: ClaudeIntercomTransport | string;
+  env?: NodeJS.ProcessEnv;
+  claudeCommand?: string;
+  probe?: (command: string) => ClaudeVersionProbe;
+} = {}): ClaudeTransportResolution {
+  const requested = parseClaudeIntercomTransport(
+    options.requested ?? options.env?.[CLAUDE_INTERCOM_TRANSPORT_ENV] ?? "auto",
+    options.requested === undefined ? CLAUDE_INTERCOM_TRANSPORT_ENV : "transport",
+  );
+  const command = options.claudeCommand || "claude";
+  const versionProbe = (options.probe ?? probeClaudeVersion)(command);
+  if (requested === "mcp") return { requested, selected: "mcp", ...versionProbe };
+  if (requested === "native" && !versionProbe.compatible) {
+    throw new Error(`Native Claude intercom transport was requested, but ${versionProbe.reason}. Use --transport mcp or install a verified-compatible Claude version.`);
+  }
+  return {
+    requested,
+    selected: requested === "native" || versionProbe.compatible ? "native" : "mcp",
+    ...versionProbe,
+  };
+}

package/claude/worker-config.ts

@@ -0,0 +1,198 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { cwd as processCwd } from "node:process";
+import { getIntercomDirPath, restrictIntercomRuntimeFile } from "../broker/paths.ts";
+import { isDenseArrayOf } from "../broker/validation.ts";
+import {
+  assertNoPermissionOverrides,
+  bindHardenedClaudePaths,
+  resolveClaudePermissionPolicy,
+  type ClaudePermissionCeiling,
+  type ClaudePermissionMode,
+} from "./permission-policy.ts";
+import { parseClaudeIntercomTransport, type ClaudeIntercomTransport } from "./transport.ts";
+
+export interface WorkerAgentConfig {
+  id: string;
+  name: string;
+  cwd: string;
+  model?: string;
+  sessionId?: string;
+  instructions?: string;
+  permissionMode?: ClaudePermissionMode;
+  dangerouslySkipPermissions?: boolean;
+  permissionCeiling?: ClaudePermissionCeiling;
+  /** Tightening-only role hint; authority still comes exclusively from the broker binding. */
+  bossRole?: "adversary" | "council";
+  addDirs?: string[];
+  mcpConfig?: string;
+  claudeArgs?: string[];
+  transport?: ClaudeIntercomTransport;
+}
+
+export interface WorkerConfig {
+  agents: WorkerAgentConfig[];
+  statePath: string;
+  claudeCommand?: string;
+}
+
+export interface WorkerState {
+  agents: Record<string, { sessionId: string; updatedAt: number }>;
+}
+
+export const DEFAULT_WORKER_CONFIG_PATH = join(getIntercomDirPath(), "claude-worker.json");
+export const DEFAULT_WORKER_STATE_PATH = join(getIntercomDirPath(), "claude-worker-state.json");
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new Error(`${field} must be a string`);
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function requireString(value: unknown, field: string): string {
+  const result = optionalString(value, field);
+  if (!result) throw new Error(`${field} must be a non-empty string`);
+  return result;
+}
+
+function optionalBoolean(value: unknown, field: string): boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "boolean") throw new Error(`${field} must be a boolean`);
+  return value;
+}
+
+function optionalStringArray(value: unknown, field: string): string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isDenseArrayOf<unknown>(value, (_entry): _entry is unknown => true)) {
+    throw new Error(`${field} must be an exact dense array`);
+  }
+  return value.map((item, index) => requireString(item, `${field}[${index}]`));
+}
+
+function normalizeAgent(raw: unknown, index: number): WorkerAgentConfig {
+  if (!isRecord(raw)) throw new Error(`agents[${index}] must be an object`);
+  const id = requireString(raw.id, `agents[${index}].id`);
+  const name = optionalString(raw.name, `agents[${index}].name`) ?? id;
+  const cwdValue = optionalString(raw.cwd, `agents[${index}].cwd`) ?? processCwd();
+  let cwd = resolve(cwdValue);
+  const permissionModeValue = optionalString(raw.permissionMode, `agents[${index}].permissionMode`);
+  const dangerouslySkipPermissionsValue = optionalBoolean(
+    raw.dangerouslySkipPermissions,
+    `agents[${index}].dangerouslySkipPermissions`,
+  );
+  const permissionCeilingValue = optionalString(raw.permissionCeiling, `agents[${index}].permissionCeiling`);
+  if (permissionCeilingValue !== undefined && permissionCeilingValue !== "standard" && permissionCeilingValue !== "read-only") {
+    throw new Error(`agents[${index}].permissionCeiling must be standard or read-only`);
+  }
+  const bossRoleValue = optionalString(raw.bossRole, `agents[${index}].bossRole`);
+  if (bossRoleValue !== undefined && bossRoleValue !== "adversary" && bossRoleValue !== "council") {
+    throw new Error(`agents[${index}].bossRole must be adversary or council`);
+  }
+  if (bossRoleValue !== undefined && permissionCeilingValue === "standard") {
+    throw new Error(`agents[${index}].permissionCeiling cannot widen an Adversary/Council role`);
+  }
+  const permission = resolveClaudePermissionPolicy({
+    permissionMode: permissionModeValue,
+    dangerouslySkipPermissions: dangerouslySkipPermissionsValue,
+    ceiling: bossRoleValue === undefined
+      ? permissionCeilingValue as ClaudePermissionCeiling | undefined
+      : "read-only",
+  });
+  const claudeArgs = optionalStringArray(raw.claudeArgs, `agents[${index}].claudeArgs`);
+  let addDirs = optionalStringArray(raw.addDirs, `agents[${index}].addDirs`);
+  const mcpConfig = optionalString(raw.mcpConfig, `agents[${index}].mcpConfig`);
+  assertNoPermissionOverrides(claudeArgs ?? [], `agents[${index}].claudeArgs`, permission.ceiling);
+  if (permission.ceiling === "read-only") {
+    if (mcpConfig !== undefined) {
+      throw new Error(`agents[${index}].mcpConfig cannot add an arbitrary MCP capability to a hardened Claude role`);
+    }
+    const binding = bindHardenedClaudePaths(cwdValue, addDirs ?? [], `agents[${index}]`);
+    try {
+      cwd = binding.cwd;
+      addDirs = binding.addDirs.length ? binding.addDirs : undefined;
+    } finally {
+      binding.release();
+    }
+  }
+  return {
+    id,
+    name,
+    cwd,
+    model: optionalString(raw.model, `agents[${index}].model`),
+    sessionId: optionalString(raw.sessionId, `agents[${index}].sessionId`),
+    instructions: optionalString(raw.instructions, `agents[${index}].instructions`),
+    ...(permission.ceiling === "standard" && permissionModeValue === undefined
+      ? {}
+      : { permissionMode: permission.permissionMode }),
+    ...(dangerouslySkipPermissionsValue === undefined && permission.ceiling !== "read-only"
+      ? {}
+      : { dangerouslySkipPermissions: permission.dangerouslySkipPermissions }),
+    ...(permissionCeilingValue === undefined && bossRoleValue === undefined
+      ? {}
+      : { permissionCeiling: permission.ceiling }),
+    ...(bossRoleValue === undefined ? {} : { bossRole: bossRoleValue }),
+    addDirs,
+    mcpConfig,
+    claudeArgs,
+    transport: raw.transport === undefined
+      ? undefined
+      : parseClaudeIntercomTransport(raw.transport, `agents[${index}].transport`),
+  };
+}
+
+export function defaultWorkerConfig(env: NodeJS.ProcessEnv = process.env): WorkerConfig {
+  const id = env.CLAUDE_INTERCOM_WORKER_ID?.trim() || "claude-worker";
+  return {
+    statePath: env.CLAUDE_INTERCOM_WORKER_STATE?.trim() || DEFAULT_WORKER_STATE_PATH,
+    agents: [{
+      id,
+      name: env.CLAUDE_INTERCOM_WORKER_NAME?.trim() || id,
+      cwd: resolve(env.CLAUDE_INTERCOM_WORKER_CWD?.trim() || processCwd()),
+      model: env.CLAUDE_INTERCOM_WORKER_MODEL?.trim() || undefined,
+      instructions: env.CLAUDE_INTERCOM_WORKER_INSTRUCTIONS?.trim() || undefined,
+      transport: parseClaudeIntercomTransport(env.CLAUDE_INTERCOM_TRANSPORT, "CLAUDE_INTERCOM_TRANSPORT"),
+    }],
+  };
+}
+
+export function loadWorkerConfig(path = process.env.CLAUDE_INTERCOM_WORKER_CONFIG || DEFAULT_WORKER_CONFIG_PATH): WorkerConfig {
+  if (!existsSync(path)) return defaultWorkerConfig();
+
+  const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (!isRecord(parsed)) throw new Error("Worker config must be a JSON object");
+  if (!isDenseArrayOf<unknown>(parsed.agents, (_entry): _entry is unknown => true)) {
+    throw new Error("Worker config requires an exact dense agents array");
+  }
+
+  return {
+    statePath: resolve(optionalString(parsed.statePath, "statePath") ?? DEFAULT_WORKER_STATE_PATH),
+    claudeCommand: optionalString(parsed.claudeCommand, "claudeCommand"),
+    agents: parsed.agents.map(normalizeAgent),
+  };
+}
+
+export function loadWorkerState(path: string): WorkerState {
+  if (!existsSync(path)) return { agents: {} };
+  const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (!isRecord(parsed) || !isRecord(parsed.agents)) return { agents: {} };
+  const agents: WorkerState["agents"] = {};
+  for (const [id, value] of Object.entries(parsed.agents)) {
+    if (!isRecord(value) || typeof value.sessionId !== "string") continue;
+    agents[id] = {
+      sessionId: value.sessionId,
+      updatedAt: typeof value.updatedAt === "number" ? value.updatedAt : 0,
+    };
+  }
+  return { agents };
+}
+
+export function saveWorkerState(path: string, state: WorkerState): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  restrictIntercomRuntimeFile(path);
+}