@mattstack/rt-client 0.25.0 → 0.27.0

package/dist/commands.d.ts

@@ -108,6 +108,7 @@ export type GateOption = string | {
     value: string;
     label: string;
     recommended?: boolean;
+    description?: string;
 };
 export interface GateOrigin {
     paneId?: string;
@@ -117,11 +118,14 @@ export interface GateOrigin {
     surface?: string;
     presentation?: "form" | "wait";
 }
+/** `context` is per-question material (what this one choice turns on);
+    the gate-level `context` on the open/ask payload is the whole ask's. */
 export interface GateQuestion {
     id: string;
     label: string;
     multi: boolean;
     options: GateOption[];
+    context?: string;
 }
 /** Implementations live in gate-options.ts (the browser-safe ./gate
     subpath); re-exported here so existing commands.ts/index.ts consumers
@@ -171,14 +175,13 @@ export interface GateRow {
         at: number;
     } | null;
     released: boolean;
-    /** Set once the nudged pane has provably read the answer: either it
-        self-answered (stamped in the same transaction as the answer) or a
-        later `markConsumed` call recorded that it acted on a push. `null`
-        until then, so a sweep can tell an answered-but-unread row from a
-        settled one. Currently only stamped for herd-subject gates (the
-        self-answer path and `rt herd answer`'s nudged-session read); a
-        non-herd gate with a nudge stays `null` even after its pane
-        reconciles. */
+    /** Set once the nudged pane has provably read the answer: it self-answered
+        or lost the CAS to one (both stamped in the answer's own transaction),
+        or a later `markConsumed` call recorded that it acted on a push
+        (`rt herd answer` and `rt gate wait`, each on the nudged session's own
+        read). `null` until then, so a sweep can tell an answered-but-unread row
+        from a settled one. Every nudge-bearing subject has a stamping read;
+        a gate with no nudge never carries one, having no pane to read it. */
     consumedAt: number | null;
     owner: string | null;
     escalatedAt: number | null;
@@ -228,19 +231,20 @@ export interface HerdJobInfo {
     agentSession: string | null;
     agentId: string | null;
     handle: string;
-    status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed";
+    status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed" | "stuck-at-modal";
     disposable: boolean;
     lastGate: string | null;
     lastReport: number | null;
     createdAt: number;
     updatedAt: number;
 }
-/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: a TERMINAL gate (answered or closed) whose delivery is `dead-pane` is the "worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
 export interface HerdStatusData {
     herd: HerdInfo;
     jobs: Array<HerdJobInfo & {
         openGate: string | null;
-        paneStatus: string | null;
+        paneStatus: string | null; /** The worker session behind this job's pane is gone while the job still reads in-flight: herdr lists the pane but no claude is on it. Null when herdr does not list the pane at all (it closed, or herdr is unreachable), which proves nothing either way. */
+        sessionDead: boolean | null;
         lastGateStatus: GateStatus | null;
         lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null;
         lastGateConsumed: boolean | null;
@@ -507,6 +511,7 @@ export interface AgentRecord {
     extraArgs?: string;
     exitCode?: number;
     resultPath?: string;
+    yolo?: boolean;
     createdAt: number;
     lastResumedAt?: number;
     finishedAt?: number;
@@ -1141,6 +1146,7 @@ export interface Commands {
             cwd: string;
             prompt?: string;
             surface?: AgentSurface;
+            provider?: string;
             model?: string;
             effort?: string;
             account?: string;
@@ -1154,6 +1160,7 @@ export interface Commands {
             handle?: string;
             bg?: boolean;
             subject?: string;
+            yolo?: boolean;
         };
         data: AgentRecord;
     };
@@ -1503,11 +1510,16 @@ export interface Commands {
                 worktree?: string;
             };
         };
+        /** `contextOmitted` appears only when the gate context plus every
+            question's `context` exceeded their shared 8192-byte budget: the
+            gate still opened, but question contexts were dropped, and the gate
+            context too when it was over the budget on its own. */
         data: {
             id: string;
             presentation: "form" | "wait";
             subject: string;
             supersededId: string | null;
+            contextOmitted?: true;
         };
     };
     /**
@@ -1538,10 +1550,14 @@ export interface Commands {
     };
     /** `ok:false "not-found"` on an unknown id is terminal; the CLI loop must not re-enter on it.
      *  `timeout` carries no row (nothing settled); `answered`/`closed` always carry the settled row. */
+    /** `sessionId` is the caller's own session: an answered result returned to
+     *  the gate's nudged session is a recorded read and stamps `consumedAt`.
+     *  Omitting it reads without consuming. */
     "gate:wait": {
         payload: {
             id: string;
             waitMs?: number;
+            sessionId?: string;
         };
         data: {
             status: "timeout";
@@ -1689,7 +1705,8 @@ export interface Commands {
             wasOnDeck: boolean | null;
             agentId: string;
             sessionId: string;
-            handle: string;
+            handle: string; /** What the folder-trust check established: no modal was up, one was accepted and verified gone, one is still up (the job reads `stuck-at-modal`), or herdr could not be read. */
+            trust: "none" | "accepted" | "stuck" | "unchecked";
         };
     };
     "herd:gates": {

package/dist/gate-options.d.ts

@@ -5,6 +5,9 @@ import type { GateOption, GateQuestion } from "./commands.ts";
 export interface GateOptionObject {
     value: string;
     label: string;
+    /** Per-option explanation, carried verbatim: never capitalized, never
+        suffixed, never filled in from value/label. */
+    description?: string;
 }
 export declare function gateOptionValue(o: GateOption): string;
 export declare function gateOptionLabel(o: GateOption): string;
@@ -17,8 +20,13 @@ export declare function gateOptionLabel(o: GateOption): string;
     word-like (see isWordLikeLabel), and an object form's `recommended:
     true` lifts into a " (Recommended)" label suffix -- guarded against
     double-appending -- since `recommended` itself does not survive into
-    the returned object; the suffix IS its wire representation. Every
-    returned entry is a full {value,label} pair -- callers may trust the
-    return type without re-checking it. Pure and order-preserving. */
+    the returned object; the suffix IS its wire representation. An object
+    form's non-empty string `description` rides along untouched (no
+    capitalization, no suffix); any other description shape is dropped.
+    Every returned entry is a full {value,label} pair -- callers may trust
+    the return type without re-checking it. Pure and order-preserving. */
 export declare function normalizeGateOptions(options: GateOption[]): GateOptionObject[];
+/** Options normalize per normalizeGateOptions; a question's `context` is
+    kept verbatim when it is a non-blank string and dropped otherwise, so a
+    stored row never carries an empty or non-string context key. */
 export declare function normalizeGateQuestions(questions: GateQuestion[]): GateQuestion[];

package/dist/gate.js

@@ -33,11 +33,18 @@ function normalizeGateOptions(options) {
     label = capitalize(label);
     if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label))
       label += RECOMMENDED_SUFFIX;
-    return { value, label };
+    const d = o !== null && typeof o === "object" ? o.description : undefined;
+    return typeof d === "string" && d ? { value, label, description: d } : { value, label };
   });
 }
 function normalizeGateQuestions(questions) {
-  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+  return questions.map((q) => {
+    const { context, ...rest } = q;
+    const out = { ...rest, options: normalizeGateOptions(q.options) };
+    if (typeof context === "string" && context.trim())
+      out.context = context;
+    return out;
+  });
 }
 
 // src/gate-answers.ts

package/dist/index.js

@@ -243,7 +243,7 @@ function eventsList(payload, o = {}) {
 }
 function agentStart(a, o = {}) {
   const payload = { repo: a.repo, cwd: a.cwd };
-  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg", "subject"]) {
+  for (const k of ["prompt", "surface", "provider", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg", "subject", "yolo"]) {
     if (a[k] !== undefined)
       payload[k] = a[k];
   }
@@ -344,6 +344,8 @@ function gateWait(a, o = {}) {
   const payload = { id: a.id };
   if (a.waitMs !== undefined)
     payload.waitMs = a.waitMs;
+  if (a.sessionId !== undefined)
+    payload.sessionId = a.sessionId;
   return rtCommand("gate:wait", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 250000 });
 }
 function gateList(a, o = {}) {
@@ -491,11 +493,18 @@ function normalizeGateOptions(options) {
     label = capitalize(label);
     if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label))
       label += RECOMMENDED_SUFFIX;
-    return { value, label };
+    const d = o !== null && typeof o === "object" ? o.description : undefined;
+    return typeof d === "string" && d ? { value, label, description: d } : { value, label };
   });
 }
 function normalizeGateQuestions(questions) {
-  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+  return questions.map((q) => {
+    const { context, ...rest } = q;
+    const out = { ...rest, options: normalizeGateOptions(q.options) };
+    if (typeof context === "string" && context.trim())
+      out.context = context;
+    return out;
+  });
 }
 
 // src/commands.ts
@@ -1519,32 +1528,75 @@ var REGISTRY = [
     description: "Destination (topic/URL/token) the configured chat.push.provider sends to."
   },
   {
-    key: "agent.model",
+    key: "agent.provider",
+    type: "string",
+    scopes: ["user", "machine"],
+    default: "claude",
+    merge: "replace",
+    description: 'Which provider rt agent start uses when --provider is not given: "claude" or "codex".'
+  },
+  {
+    key: "agent.claude.model",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --model for claude rt agent launches; unset omits the flag."
+  },
+  {
+    key: "agent.claude.effort",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --effort for claude rt agent launches; unset omits the flag."
+  },
+  {
+    key: "agent.claude.account",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "cswap account email claude rt agent launches under; unset uses the default claude profile."
+  },
+  {
+    key: "agent.claude.extraArgs",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Default --model for rt agent launches; unset omits the flag."
+    description: "Opaque extra claude arguments appended to every claude rt agent launch (escape hatch)."
   },
   {
-    key: "agent.effort",
+    key: "agent.claude.yolo",
+    type: "boolean",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --yolo (--dangerously-skip-permissions) for claude rt agent launches; unset behaves as false."
+  },
+  {
+    key: "agent.codex.model",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Default --effort for rt agent launches; unset omits the flag."
+    description: "Default -m/--model for codex rt agent launches; unset omits the flag."
   },
   {
-    key: "agent.account",
+    key: "agent.codex.effort",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "cswap account email rt agent launches under; unset uses the default claude profile."
+    description: "Default reasoning effort for codex rt agent launches, passed as -c model_reasoning_effort=<value>; unset omits the override."
   },
   {
-    key: "agent.extraArgs",
+    key: "agent.codex.extraArgs",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch)."
+    description: "Opaque extra codex arguments appended to every codex rt agent launch (escape hatch)."
+  },
+  {
+    key: "agent.codex.yolo",
+    type: "boolean",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --yolo (--dangerously-bypass-approvals-and-sandbox) for codex rt agent launches; unset behaves as false. codex has no per-agent account setting (see spec's Non-goals)."
   },
   {
     key: "rt.gates.escalationTtlMinutes",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "type": "module",
   "exports": {
     ".": {

package/src/client.ts

@@ -356,7 +356,7 @@ export function agentStart(
   a: Commands["agent:start"]["payload"], o: RtClientOptions = {},
 ): Promise<RtResponse<AgentRecord>> {
   const payload: Record<string, unknown> = { repo: a.repo, cwd: a.cwd };
-  for (const k of ["prompt", "surface", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg", "subject"] as const) {
+  for (const k of ["prompt", "surface", "provider", "model", "effort", "account", "label", "caller", "workspace", "tab", "extraArgs", "env", "herdrSocket", "handle", "bg", "subject", "yolo"] as const) {
     if (a[k] !== undefined) payload[k] = a[k];
   }
   return rtCommand<AgentRecord>("agent:start", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
@@ -499,6 +499,7 @@ export function gateWait(
 ): Promise<RtResponse<Commands["gate:wait"]["data"]>> {
   const payload: Record<string, unknown> = { id: a.id };
   if (a.waitMs !== undefined) payload.waitMs = a.waitMs;
+  if (a.sessionId !== undefined) payload.sessionId = a.sessionId;
   return rtCommand<Commands["gate:wait"]["data"]>("gate:wait", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 250_000 });
 }
 

package/src/commands.ts

@@ -97,7 +97,7 @@ export const GATE_BY_PANE = "pane";
 export type GateStatus = "open" | "answered" | "parked" | "closed";
 /** Reconciler's view of an agent's liveness; also the value `GateRow.executor` is stamped with. */
 export type ExecutorState = "live" | "blocked" | "hidden" | "gone" | "cleared" | "unknown";
-export type GateOption = string | { value: string; label: string; recommended?: boolean };
+export type GateOption = string | { value: string; label: string; recommended?: boolean; description?: string };
 export interface GateOrigin {
   paneId?: string;
   tabId?: string;
@@ -106,7 +106,9 @@ export interface GateOrigin {
   surface?: string;
   presentation?: "form" | "wait";
 }
-export interface GateQuestion { id: string; label: string; multi: boolean; options: GateOption[] }
+/** `context` is per-question material (what this one choice turns on);
+    the gate-level `context` on the open/ask payload is the whole ask's. */
+export interface GateQuestion { id: string; label: string; multi: boolean; options: GateOption[]; context?: string }
 /** Implementations live in gate-options.ts (the browser-safe ./gate
     subpath); re-exported here so existing commands.ts/index.ts consumers
     are unaffected. */
@@ -134,14 +136,13 @@ export interface GateRow {
   nudge: { session: string } | null;
   delivery: { outcome: "delivered" | "dead-pane" | "confirmed" | "stuck"; at: number } | null;
   released: boolean;
-  /** Set once the nudged pane has provably read the answer: either it
-      self-answered (stamped in the same transaction as the answer) or a
-      later `markConsumed` call recorded that it acted on a push. `null`
-      until then, so a sweep can tell an answered-but-unread row from a
-      settled one. Currently only stamped for herd-subject gates (the
-      self-answer path and `rt herd answer`'s nudged-session read); a
-      non-herd gate with a nudge stays `null` even after its pane
-      reconciles. */
+  /** Set once the nudged pane has provably read the answer: it self-answered
+      or lost the CAS to one (both stamped in the answer's own transaction),
+      or a later `markConsumed` call recorded that it acted on a push
+      (`rt herd answer` and `rt gate wait`, each on the nudged session's own
+      read). `null` until then, so a sweep can tell an answered-but-unread row
+      from a settled one. Every nudge-bearing subject has a stamping read;
+      a gate with no nudge never carries one, having no pane to read it. */
   consumedAt: number | null;
   owner: string | null;
   escalatedAt: number | null;
@@ -166,11 +167,11 @@ export interface GateSubscription {
 export interface HerdInfo { id: string; repo: string; room: string; workspace: string; shepherdSession: string; shepherdHandle: string; herdrSocket: string | null; hidden: boolean; status: "active" | "wrapped"; createdAt: number; wrappedAt: number | null }
 /** A herd row as `herd:list` reports it: the registry row plus how many jobs hang off it. */
 export interface HerdListRow extends HerdInfo { jobs: number }
-export interface HerdJobInfo { herd: string; name: string; worktree: string; branch: string | null; tree: string | null; pane: string | null; agentSession: string | null; agentId: string | null; handle: string; status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed"; disposable: boolean; lastGate: string | null; lastReport: number | null; createdAt: number; updatedAt: number }
-/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
+export interface HerdJobInfo { herd: string; name: string; worktree: string; branch: string | null; tree: string | null; pane: string | null; agentSession: string | null; agentId: string | null; handle: string; status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed" | "stuck-at-modal"; disposable: boolean; lastGate: string | null; lastReport: number | null; createdAt: number; updatedAt: number }
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: a TERMINAL gate (answered or closed) whose delivery is `dead-pane` is the "worker not woken" case the shepherd must act on. `lastGateConsumed` is `null` when there is nothing to consume (no last gate, not answered, or not nudged), and otherwise reports whether the nudged pane has read its answer. */
 export interface HerdStatusData {
   herd: HerdInfo;
-  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null; lastGateConsumed: boolean | null }>;
+  jobs: Array<HerdJobInfo & { openGate: string | null; paneStatus: string | null; /** The worker session behind this job's pane is gone while the job still reads in-flight: herdr lists the pane but no claude is on it. Null when herdr does not list the pane at all (it closed, or herdr is unreachable), which proves nothing either way. */ sessionDead: boolean | null; lastGateStatus: GateStatus | null; lastGateDelivery: "delivered" | "dead-pane" | "confirmed" | "stuck" | null; lastGateConsumed: boolean | null }>;
   unread: number;
   lifecycleConnected: boolean;
   hiddenUp: boolean | null;
@@ -360,7 +361,7 @@ export interface AgentRecord {
       PreToolUse hook gets injected at all. */
   subject?: string;
   paneId?: string; tabId?: string; workspaceId?: string;
-  extraArgs?: string; exitCode?: number; resultPath?: string;
+  extraArgs?: string; exitCode?: number; resultPath?: string; yolo?: boolean;
   createdAt: number; lastResumedAt?: number; finishedAt?: number;
 }
 
@@ -617,7 +618,7 @@ export interface Commands {
   "chat:dm-open": { payload: { from: string; to: string; sessionId?: string }; data: { room: string; created: boolean } };
 
   // ─── Agent handoff (rt agent) ────────────────────────────────────────────
-  "agent:start": { payload: { repo: string; cwd: string; prompt?: string; surface?: AgentSurface; model?: string; effort?: string; account?: string; label?: string; caller?: string; workspace?: string; tab?: string; extraArgs?: string; env?: Record<string, string>; herdrSocket?: string; handle?: string; bg?: boolean; subject?: string }; data: AgentRecord };
+  "agent:start": { payload: { repo: string; cwd: string; prompt?: string; surface?: AgentSurface; provider?: string; model?: string; effort?: string; account?: string; label?: string; caller?: string; workspace?: string; tab?: string; extraArgs?: string; env?: Record<string, string>; herdrSocket?: string; handle?: string; bg?: boolean; subject?: string; yolo?: boolean }; data: AgentRecord };
   "agent:resume": { payload: { id: string; prompt?: string; surface?: AgentSurface; workspace?: string; tab?: string }; data: AgentRecord };
   "agent:get": { payload: { id: string }; data: AgentRecord };
   "agent:list": { payload: { repo?: string }; data: { agents: AgentRecord[] } };
@@ -712,7 +713,11 @@ export interface Commands {
       agent?: string;
       origin?: { surface?: string; tabId?: string; worktree?: string };
     };
-    data: { id: string; presentation: "form" | "wait"; subject: string; supersededId: string | null };
+    /** `contextOmitted` appears only when the gate context plus every
+        question's `context` exceeded their shared 8192-byte budget: the
+        gate still opened, but question contexts were dropped, and the gate
+        context too when it was over the budget on its own. */
+    data: { id: string; presentation: "form" | "wait"; subject: string; supersededId: string | null; contextOmitted?: true };
   };
   /**
    * A CAS loss is a DEFINED OUTCOME, not an error: `ok:true` with
@@ -730,7 +735,10 @@ export interface Commands {
   "gate:answer": { payload: { id: string; answers: GateAnswer["answers"]; by: string; session?: string; override?: boolean }; data: { row: GateRow; conflict?: true } };
   /** `ok:false "not-found"` on an unknown id is terminal; the CLI loop must not re-enter on it.
    *  `timeout` carries no row (nothing settled); `answered`/`closed` always carry the settled row. */
-  "gate:wait": { payload: { id: string; waitMs?: number }; data: { status: "timeout" } | { status: "answered" | "closed"; row: GateRow } };
+  /** `sessionId` is the caller's own session: an answered result returned to
+   *  the gate's nudged session is a recorded read and stamps `consumedAt`.
+   *  Omitting it reads without consuming. */
+  "gate:wait": { payload: { id: string; waitMs?: number; sessionId?: string }; data: { status: "timeout" } | { status: "answered" | "closed"; row: GateRow } };
   /** Paged like events:list: an omitted `limit` clamps daemon-side rather than
    *  forcing a full-table read; `cursor` is the paging rowid to resume from. */
   "gate:list": { payload: { open?: boolean; subjectPrefix?: string; kind?: string; limit?: number; cursor?: number }; data: { gates: GateRow[]; cursor: number } };
@@ -750,7 +758,7 @@ export interface Commands {
   "herd:list":   { payload: { all?: boolean }; data: { herds: HerdListRow[] } };
   "herd:close":  { payload: { herd: string; job: string }; data: { job: string; status: "closed"; /** Advisory: a resumable run can still write into this job's worktree after close, so this warns rather than blocking. */ warning?: string } };
   /** `brief` is the brief TEXT, not a path: the CLI reads the file. It is stored at `<jobsRoot>/<herd>/<job>/job.md`, so a respawn with `dir` and no `brief` reads it back. */
-  "herd:spawn":  { payload: { herd: string; job: string; brief?: string; dir?: string; model?: string; effort?: string; account?: string; disposable?: boolean }; data: { herd: string; job: string; pane: string; worktree: string; branch: string | null; tree: string | null; /** null = no provisioning ran (--dir); false = cold create, worth announcing. */ wasOnDeck: boolean | null; agentId: string; sessionId: string; handle: string } };
+  "herd:spawn":  { payload: { herd: string; job: string; brief?: string; dir?: string; model?: string; effort?: string; account?: string; disposable?: boolean }; data: { herd: string; job: string; pane: string; worktree: string; branch: string | null; tree: string | null; /** null = no provisioning ran (--dir); false = cold create, worth announcing. */ wasOnDeck: boolean | null; agentId: string; sessionId: string; handle: string; /** What the folder-trust check established: no modal was up, one was accepted and verified gone, one is still up (the job reads `stuck-at-modal`), or herdr could not be read. */ trust: "none" | "accepted" | "stuck" | "unchecked" } };
   "herd:gates":  { payload: { herd: string }; data: { gates: GateRow[] } };
   "herd:ask":       { payload: { herd: string; job: string; session: string; pane?: string; questions: GateQuestion[]; context?: string }; data: { gate: string } };
   "herd:milestone": { payload: { herd: string; job: string; session: string; pane?: string; artifact: string; summary?: string }; data: { gate: string; message: number } };

package/src/gate-options.ts

@@ -6,6 +6,9 @@ import type { GateOption, GateQuestion } from "./commands.ts";
 export interface GateOptionObject {
   value: string;
   label: string;
+  /** Per-option explanation, carried verbatim: never capitalized, never
+      suffixed, never filled in from value/label. */
+  description?: string;
 }
 
 export function gateOptionValue(o: GateOption): string {
@@ -45,9 +48,11 @@ function capitalize(label: string): string {
     word-like (see isWordLikeLabel), and an object form's `recommended:
     true` lifts into a " (Recommended)" label suffix -- guarded against
     double-appending -- since `recommended` itself does not survive into
-    the returned object; the suffix IS its wire representation. Every
-    returned entry is a full {value,label} pair -- callers may trust the
-    return type without re-checking it. Pure and order-preserving. */
+    the returned object; the suffix IS its wire representation. An object
+    form's non-empty string `description` rides along untouched (no
+    capitalization, no suffix); any other description shape is dropped.
+    Every returned entry is a full {value,label} pair -- callers may trust
+    the return type without re-checking it. Pure and order-preserving. */
 export function normalizeGateOptions(options: GateOption[]): GateOptionObject[] {
   return options.map((o) => {
     const recommended = o !== null && typeof o === "object" && (o as { recommended?: unknown }).recommended === true;
@@ -70,10 +75,19 @@ export function normalizeGateOptions(options: GateOption[]): GateOptionObject[]
     // downstream `label || value` fallback (gate-kit) must still see label
     // as absent, not as a non-empty "(Recommended)" that hides the value.
     if (recommended && label && !HAS_RECOMMENDED_SUFFIX.test(label)) label += RECOMMENDED_SUFFIX;
-    return { value, label };
+    const d = o !== null && typeof o === "object" ? (o as { description?: unknown }).description : undefined;
+    return typeof d === "string" && d ? { value, label, description: d } : { value, label };
   });
 }
 
+/** Options normalize per normalizeGateOptions; a question's `context` is
+    kept verbatim when it is a non-blank string and dropped otherwise, so a
+    stored row never carries an empty or non-string context key. */
 export function normalizeGateQuestions(questions: GateQuestion[]): GateQuestion[] {
-  return questions.map((q) => ({ ...q, options: normalizeGateOptions(q.options) }));
+  return questions.map((q) => {
+    const { context, ...rest } = q;
+    const out: GateQuestion = { ...rest, options: normalizeGateOptions(q.options) };
+    if (typeof context === "string" && context.trim()) out.context = context;
+    return out;
+  });
 }

package/src/settings/registry-defs.ts

@@ -666,35 +666,80 @@ export const REGISTRY: readonly SettingDef[] = [
   },
 
   // --- agent (rt agent handoff) --------------------------------------------
-  // No defaults by design: an unset key means the flag is omitted from the
-  // claude invocation entirely (spec "Settings").
+  // No defaults on any per-provider row, by design: an unset key means the
+  // flag is omitted from the launch entirely (spec "Settings"). agent.provider
+  // is the one exception -- it needs a concrete fallback to preserve
+  // claude-only behavior with zero code changes for callers who never set it.
   {
-    key: "agent.model",
+    key: "agent.provider",
     type: "string",
     scopes: ["user", "machine"],
+    default: "claude",
     merge: "replace",
-    description: "Default --model for rt agent launches; unset omits the flag.",
+    description: "Which provider rt agent start uses when --provider is not given: \"claude\" or \"codex\".",
   },
   {
-    key: "agent.effort",
+    key: "agent.claude.model",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Default --effort for rt agent launches; unset omits the flag.",
+    description: "Default --model for claude rt agent launches; unset omits the flag.",
   },
   {
-    key: "agent.account",
+    key: "agent.claude.effort",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "cswap account email rt agent launches under; unset uses the default claude profile.",
+    description: "Default --effort for claude rt agent launches; unset omits the flag.",
   },
   {
-    key: "agent.extraArgs",
+    key: "agent.claude.account",
     type: "string",
     scopes: ["user", "machine"],
     merge: "replace",
-    description: "Opaque extra claude arguments appended to every rt agent launch (escape hatch).",
+    description: "cswap account email claude rt agent launches under; unset uses the default claude profile.",
+  },
+  {
+    key: "agent.claude.extraArgs",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Opaque extra claude arguments appended to every claude rt agent launch (escape hatch).",
+  },
+  {
+    key: "agent.claude.yolo",
+    type: "boolean",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --yolo (--dangerously-skip-permissions) for claude rt agent launches; unset behaves as false.",
+  },
+  {
+    key: "agent.codex.model",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default -m/--model for codex rt agent launches; unset omits the flag.",
+  },
+  {
+    key: "agent.codex.effort",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default reasoning effort for codex rt agent launches, passed as -c model_reasoning_effort=<value>; unset omits the override.",
+  },
+  {
+    key: "agent.codex.extraArgs",
+    type: "string",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Opaque extra codex arguments appended to every codex rt agent launch (escape hatch).",
+  },
+  {
+    key: "agent.codex.yolo",
+    type: "boolean",
+    scopes: ["user", "machine"],
+    merge: "replace",
+    description: "Default --yolo (--dangerously-bypass-approvals-and-sandbox) for codex rt agent launches; unset behaves as false. codex has no per-agent account setting (see spec's Non-goals).",
   },
 
   // --- gates (escalation) ----------------------------------------------------