@sublang/playbook 13.2.0 → 13.3.0

package/docs/configuration.md

@@ -55,8 +55,8 @@ key is that playbook's option slice. Every manifest role must be present
 exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
-The seeded config runs the stable Coder player on GPT-5.6 Sol with fast mode
-enabled and the stable Reviewer player on Claude Opus 5:
+The seeded config runs every stable player on Claude Opus 5 — the Coder at
+`high` effort, the Reviewer and Analyst at `xhigh`:
 
 ```yaml
 captain:
@@ -68,14 +68,11 @@ captain:
 
 players:
   dev.coder:
-    adapter: codex
-    model: gpt-5.6-sol
-    effort: ultra
-    fastMode: true
+    adapter: claude
+    model: claude-opus-5
+    effort: high
     permissions:
-      mode: auto
-      writablePaths:
-        - .git # allow git metadata writes under Codex auto mode
+      mode: auto # protected auto mode for the Claude Coder
 
   dev.reviewer:
     adapter: claude

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "13.2.0",
+  "version": "13.3.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",

package/reference/sdlc/code.playbook/bin/session-host.js

@@ -43,7 +43,7 @@ export async function openSessionHost(options) {
     await installRetainedGenerationsForLaunch({ lease, shell: created.shell, ...(record === undefined ? { freshBoundary: { cwd, structuralProjection: structure, executionProjection: config, snapshot: created.snapshot } } : {}), retainedGenerations: record?.retainedGenerations ?? {}, reconcileRepositoryEffects: created.reconcileRepositoryEffects });
     record = await lease.read();
     await replay.flushStoredRecords();
-    const execute = async (input, retry) => {
+    const execute = async (input, retry, actionId, shellActionId) => {
       if (closed || closing) throw new Error('session host is closing');
       if (active) throw new Error('session turn is already active');
       const operation = (async () => {
@@ -53,8 +53,18 @@ export async function openSessionHost(options) {
           input = prior.uncertain.input;
           if (!retryPending) throw new Error('retry requires reopening the uncertain checkpoint');
         } else if (prior?.state !== 'settled') throw new Error('session has an uncertain turn; select Retry or Discard');
-        if (typeof input !== 'string' || input.trim().length === 0) throw new Error('session input must be nonempty');
+        if (actionId === undefined && shellActionId === undefined && (typeof input !== 'string' || input.trim().length === 0)) throw new Error('session input must be nonempty');
         await created.reconcileRepositoryEffects();
+        // The selection is made after reconciliation, so the advertised
+        // reading it is validated against is the one this turn settles
+        // against, and its Boss text is this turn's durable input.
+        if (actionId !== undefined) {
+          if (typeof created.shell.submitRuntimeAction !== 'function') throw new Error('this Captain shell advertises no runtime actions');
+          input = created.shell.submitRuntimeAction(actionId);
+        } else if (shellActionId !== undefined) {
+          if (typeof created.shell.submitShellAction !== 'function') throw new Error('this Captain shell advertises no controls of its own');
+          input = created.shell.submitShellAction(shellActionId);
+        }
         terminal = undefined; replies = [];
         const attemptId = options.createAttemptId?.() ?? randomUUID();
         const marked = retry ? await lease.beginRetry({ expectedAttemptId: prior.uncertain.attemptId, nextAttemptId: attemptId }) : await lease.beginTurn({ input, attemptId, attemptedExecutionProjection: config });
@@ -84,7 +94,7 @@ export async function openSessionHost(options) {
       })();
       return closing;
     };
-    return Object.freeze({ sessionId, host: created.host, shell: created.shell, lease, read: () => lease.read(), handleBossTurn: (input) => execute(input, false), retry: () => execute(undefined, true), dispose });
+    return Object.freeze({ sessionId, host: created.host, shell: created.shell, lease, read: () => lease.read(), handleBossTurn: (input) => execute(input, false), listRuntimeActions: () => created.shell.describeRuntimeActions?.() ?? Object.freeze([]), submitRuntimeAction: (actionId) => execute(undefined, false, actionId), listShellActions: () => created.shell.describeShellActions?.() ?? Object.freeze([]), submitShellAction: (actionId) => execute(undefined, false, undefined, actionId), retry: () => execute(undefined, true), dispose });
   } catch (cause) {
     const failures = [cause];
     let disposed = true;

package/reference/sdlc/code.playbook/playbook-captain.d.ts

@@ -1,6 +1,6 @@
 import { type Captain, type CaptainSession, type TuningSelection } from '@sublang/cligent/tmux-play';
 import type { Effort, PermissionPolicy } from '@sublang/cligent';
-import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
+import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
 import { type CaptainControllerPort } from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy } from './code.registry.js';
 interface SessionAgent {
@@ -215,6 +215,31 @@ export interface PlaybookCaptainShell extends Captain {
     exportSnapshot(): PlaybookCaptainShellSnapshot | undefined;
     exportSettlement(): PlaybookCaptainSettlement | undefined;
     restore(session: CaptainSession, snapshot: PlaybookCaptainShellSnapshot): Promise<void>;
+    /**
+     * The active leaf's currently advertised runtime actions, as the host's own
+     * reading of the control view the ControlView digest reads (CAPTAIN-60).
+     * Declared optional because capability absence is member absence: a shell
+     * that publishes no reader advertises nothing.
+     */
+    describeRuntimeActions?(): readonly PlaybookControlAction[];
+    /**
+     * Select one currently advertised runtime action as the next Boss turn's
+     * decision and return that turn's Boss text, which the host submits through
+     * `handleBossTurn` (CAPTAIN-7).
+     */
+    submitRuntimeAction?(actionId: string): string;
+    /**
+     * The controls the shell effects on its own behalf, disjoint from the leaf's
+     * advertised runtime actions (CAPTAIN-62). Declared optional for the same
+     * reason: a shell that publishes no reader advertises nothing.
+     */
+    describeShellActions?(): readonly PlaybookControlAction[];
+    /**
+     * Select one currently advertised shell control as the next Boss turn's
+     * decision and return that turn's Boss text, which the host submits through
+     * `handleBossTurn` (CAPTAIN-7).
+     */
+    submitShellAction?(actionId: string): string;
 }
 export declare function assertPlaybookCaptainUnresolvedEffects(value: unknown): readonly PlaybookCaptainUnresolvedEffect[];
 /** Validate, detach, and freeze one untrusted shell snapshot. */

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -77,6 +77,9 @@ function isCanonicalLocalRoleId(value) {
 }
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID = 'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
+// CAPTAIN-62: the shell's own control, not a runtime action. The id is machine
+// data the host echoes back; the Boss never sees it (CAPPLAY-5).
+const GIVE_UP_ACTION_ID = 'give-up';
 // The fixed machine-syntax guard of a player's Boss-question suspension
 // (slc/link.md §Boss-reply suspension): the accepted outcome that parks on
 // Boss rather than sparing Boss a relay.
@@ -1732,6 +1735,12 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     // CAPTAIN-40's corrective re-ask on the very call whose prose it surfaces —
     // the selection reaches the controller port after that call's frame is gone.
     let decisionCall;
+    // CAPTAIN-7: the control the host selected for the turn it is about to
+    // submit, held with the exact Boss text that turn carries so an unrelated
+    // turn never consumes the selection. One turn consumes it, whichever it is,
+    // and one slot holds it whichever surface it came from — the leaf's
+    // advertised actions or the shell's own controls (CAPTAIN-62).
+    let pendingHostSelection;
     let lastAction;
     let lastSettlementStatus;
     const retainedGenerationCandidates = new Map();
@@ -3889,6 +3898,118 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         lines.push(retainedResumptionDigest());
         return lines.join('\n');
     };
+    // CAPTAIN-60: the same reading the ControlView digest performs, published as
+    // data instead of prose. It states what the digest states and withholds what
+    // the digest withholds: an idle shell, a leaf with no control surface, and a
+    // control view that cannot be read all advertise nothing, and a leaf fenced
+    // for repository-effect reconciliation advertises only its fence controls.
+    // The pairs are detached and frozen, so a host holds the shell's reading
+    // rather than a live view the runtime can rewrite underneath it.
+    const advertisedRuntimeActions = () => {
+        const empty = Object.freeze([]);
+        if (lifecycle !== 'ready' || terminallyDisposed)
+            return empty;
+        // Between turns: while a turn is running, the leaf's control view is the
+        // decision's grounding and the host can act on no selection, so the shell
+        // publishes none and reads nothing from a runtime mid-run.
+        if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+            return empty;
+        }
+        const leaf = leafFrame();
+        if (!leaf || typeof leaf.runtime.describe !== 'function')
+            return empty;
+        refreshRetainedEffectFence();
+        const fenced = retainedEffectReconciliation !== undefined;
+        if (fenced && typeof leaf.runtime.apply !== 'function')
+            return empty;
+        let actions;
+        try {
+            actions = leaf.runtime.describe().actions;
+        }
+        catch {
+            // An unreadable control view advertises nothing.
+            return empty;
+        }
+        return Object.freeze(actions
+            .filter((action) => !fenced ||
+            action.id === UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID ||
+            action.id === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID)
+            .map((action) => Object.freeze({ id: action.id, label: action.label })));
+    };
+    // CAPTAIN-62: the controls the shell effects itself, published beside the
+    // leaf's advertised actions and never mixed with them — these are the
+    // shell's own, so an engaged root offers one whatever its leaf advertises,
+    // fenced or not. A fenced root keeps its control because giving up reports
+    // unresolved effects (CAPTAIN-58) rather than reconciling them, and a run
+    // whose effects are unknown is exactly the run a Boss gives up on.
+    const advertisedShellActions = () => {
+        const empty = Object.freeze([]);
+        if (lifecycle !== 'ready' || terminallyDisposed)
+            return empty;
+        // Between turns, on the same rule the leaf's actions take: mid-turn the
+        // host can act on no selection.
+        if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+            return empty;
+        }
+        const root = rootFrame();
+        if (!root)
+            return empty;
+        return Object.freeze([
+            Object.freeze({
+                id: GIVE_UP_ACTION_ID,
+                // The label is the turn's durable Boss text, so it names the run the
+                // way the Boss started it rather than the frame that happens to be
+                // parked inside it.
+                label: `Stop ${frameLabel(root)}`,
+            }),
+        ]);
+    };
+    // CAPTAIN-7: the host's selection of the shell's own control, validated here
+    // against the same live reading. The returned text is the turn the host
+    // submits, exactly as for an advertised runtime action.
+    const selectShellAction = (actionId) => {
+        if (lifecycle !== 'ready' || terminallyDisposed) {
+            throw new Error('a shell control requires an initialized or restored Captain shell');
+        }
+        if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+            throw new Error('a shell control cannot be selected during a Boss turn');
+        }
+        if (typeof actionId !== 'string' || actionId.length === 0) {
+            throw new TypeError('a shell control id must be a nonempty string');
+        }
+        const advertised = advertisedShellActions().find((action) => action.id === actionId);
+        if (advertised === undefined) {
+            throw new Error('the shell does not advertise that control');
+        }
+        pendingHostSelection = { kind: 'give-up', text: advertised.label };
+        return advertised.label;
+    };
+    // CAPTAIN-7: the host's own selection of one advertised action, validated
+    // here against the same live reading and validated again at the controller
+    // port before any effect. The returned text is the turn the host submits.
+    const selectRuntimeAction = (actionId) => {
+        if (lifecycle !== 'ready' || terminallyDisposed) {
+            throw new Error('a runtime action requires an initialized or restored Captain shell');
+        }
+        if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+            throw new Error('a runtime action cannot be selected during a Boss turn');
+        }
+        if (typeof actionId !== 'string' || actionId.length === 0) {
+            throw new TypeError('a runtime action id must be a nonempty string');
+        }
+        const advertised = advertisedRuntimeActions().find((action) => action.id === actionId);
+        if (advertised === undefined) {
+            // CAPPLAY-5: the chosen id is control data whether or not the leaf
+            // advertises it, so the refusal names the fact and not the string.
+            throw new Error('the active leaf does not advertise that action');
+        }
+        const text = typeof advertised.label === 'string' ? advertised.label.trim() : '';
+        if (text.length === 0) {
+            throw new Error('the advertised action carries no Boss-facing label to submit as its turn');
+        }
+        pendingHostSelection = { kind: 'runtime', actionId, text };
+        return text;
+    };
     // The catalog is registry-authored, not shell-authored: an id, a command,
     // and an intent all arrive from an enabled module. They pass the same seam
     // the ControlView lines do, so an intent carrying a newline cannot open a
@@ -4341,6 +4462,42 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     ? []
                     : [labeledBlock('Conversation recap', options.reseedDigest)]),
             ]);
+            // CAPTAIN-7: a turn whose decision the host already made allocates no
+            // decision call. The host's selection is this state's decision reply, so
+            // it passes the runtime's own reply validation and reaches the shell
+            // through the controller port like every other selection — validation,
+            // execution, the outcome report, and the closing reply are the loop's.
+            if (kind === 'decision' && turn?.hostRuntimeActionId !== undefined) {
+                return {
+                    status: 'ok',
+                    finalText: JSON.stringify({
+                        action: 'runtime',
+                        actionId: turn.hostRuntimeActionId,
+                    }),
+                };
+            }
+            // CAPTAIN-63: a give-up allocates neither call. Its decision is the
+            // host's, and its result phase is answered below from the settlement the
+            // shell already holds, so an exit from a failing provider does not ask
+            // that provider for permission.
+            if (kind === 'decision' && turn?.hostGiveUp === true) {
+                return {
+                    status: 'ok',
+                    finalText: JSON.stringify({ action: 'dismiss' }),
+                };
+            }
+            if (kind === 'closingReply' && turn?.hostGiveUp === true) {
+                // The durable conversation did not receive this turn, so it is marked
+                // for the CAPTAIN-35 catch-up rather than left believing it is
+                // current: the next call carries the journal records it missed.
+                markConversationCatchUp();
+                // Through the one presentation seam, exactly where a model-composed
+                // reply is presented, so this reply is journaled and single-attempt
+                // like every other. It needs no reply validation or corrective re-ask:
+                // `giveUpReplyText` already validated what it composed.
+                await surfaceSettlement({ context, text: giveUpReplyText() });
+                return { status: 'ok', finalText: 'ok' };
+            }
             const outcome = await durableCall(context, compose);
             if (kind === 'decision') {
                 // A model-decided `respond` surfaces this call's own prose, so the
@@ -4537,8 +4694,18 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             return false;
         const label = frameLabel(root);
         // Dismissal leaves the procedure unfinished. Persist the latest safe
-        // generation captured for this turn before disposal erases the frames.
-        retainOrClearDisposedRoot(root);
+        // generation captured for this turn before disposal erases the frames —
+        // unless the Boss gave up on it (CAPTAIN-44), in which case retaining it
+        // would offer the abandoned run back on the idle digest's next reading.
+        if (activeTurn?.hostGiveUp === true) {
+            pendingRetentionUpdates.set(root.entry.id, {
+                kind: 'clear',
+                rootPlaybookId: root.entry.id,
+            });
+        }
+        else {
+            retainOrClearDisposedRoot(root);
+        }
         try {
             await runEffect(() => disposeStack('dismiss'));
             facts.push(`Dismissed the ${label} engagement.`);
@@ -4994,10 +5161,16 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             if (!leaf) {
                 return rejectSelection(selection, 'no engagement is active to dismiss');
             }
+            // CAPTAIN-63: a give-up ends the run. An ordinary dismissal of a nested
+            // call returns to its caller, which is the right reading of "stop this
+            // call" and the wrong one of "stop this workflow" — the Boss gave up on
+            // the root, not on whichever child was parked when they did.
+            const giveUp = turn.hostGiveUp === true;
+            const dismissed = giveUp ? (rootFrame() ?? leaf) : leaf;
             turn.settled = true;
-            journalAction({ action: 'dismiss', playbookId: leaf.entry.id });
-            const label = frameLabel(leaf);
-            if (leaf.parent) {
+            journalAction({ action: 'dismiss', playbookId: dismissed.entry.id });
+            const label = frameLabel(dismissed);
+            if (leaf.parent && !giveUp) {
                 // No boundary around the return itself: `resumeParent` disposes the
                 // child and drives the parent, and each of those is marked where it
                 // happens. A visibility rejection raised on the way back is shell
@@ -5291,6 +5464,28 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     // The reply composes from the authoritative report, never the early
     // `settled` guard. That guard closes duplicate submissions before an effect
     // starts; it is not evidence that anything ran.
+    // CAPTAIN-63: the give-up's closing reply, composed from the same settlement
+    // facts the result-phase prompt would have carried. Shell-authored Boss
+    // prose passes the validation every model reply passes (CAPTAIN-34); what it
+    // interpolates is not host-authored all the way down, so a fact set that
+    // fails validation is dropped rather than spoken and the reply still states
+    // the settlement truthfully.
+    const giveUpReplyText = () => {
+        const report = activeTurn?.report;
+        const facts = report?.bossFacts ?? report?.facts ?? [];
+        const opening = 'Stopped that workflow. I will not resume it.';
+        const closing = 'Send the command again to start fresh work.';
+        const composed = [
+            opening,
+            ...(facts.length === 0
+                ? []
+                : ['Here is what happened:', ...facts.map((fact) => `- ${fact}`)]),
+            closing,
+        ].join('\n');
+        return replyRejection(composed) === undefined
+            ? composed
+            : [opening, closing].join('\n');
+    };
     const failureReplyText = () => {
         const commands = [...enablementById.values()]
             .map((enablement) => `/${enablement.command} <task>`)
@@ -6151,6 +6346,10 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         exportSettlement,
         restore: restoreShellSnapshot,
         installRetainedGenerations,
+        describeRuntimeActions: advertisedRuntimeActions,
+        submitRuntimeAction: selectRuntimeAction,
+        describeShellActions: advertisedShellActions,
+        submitShellAction: selectShellAction,
         async handleBossTurn(turn, context) {
             if (lifecycle !== 'ready' || terminallyDisposed) {
                 throw new Error('init must be called first, or restore must complete before handling a Boss turn');
@@ -6184,13 +6383,25 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             const turnHostCalls = new Set();
             activeTurnHostCalls = turnHostCalls;
             activeContext = context;
-            const parsed = resolveCommandTurn(turn.prompt);
+            // CAPTAIN-7: one host selection is consumed by one turn. It decides only
+            // the turn carrying the exact text the selection was made for; any other
+            // turn drops it and resolves normally.
+            const selected = pendingHostSelection;
+            pendingHostSelection = undefined;
+            const decided = selected !== undefined && selected.text === turn.prompt
+                ? selected
+                : undefined;
+            const hostRuntimeActionId = decided?.kind === 'runtime' ? decided.actionId : undefined;
+            const hostGiveUp = decided?.kind === 'give-up' ? true : undefined;
+            const parsed = decided === undefined ? resolveCommandTurn(turn.prompt) : undefined;
             activeTurn = {
                 id: ++turnSequence,
                 captainSyncedJournalSeq: journalSeq,
                 bossText: turn.prompt,
                 authoritativeText: parsed?.authoritativeText ?? turn.prompt,
                 ...(parsed ? { resolution: parsed.resolution } : {}),
+                ...(hostRuntimeActionId === undefined ? {} : { hostRuntimeActionId }),
+                ...(hostGiveUp === undefined ? {} : { hostGiveUp }),
                 settled: false,
                 presentationAttempted: false,
                 settlementFacts: [],
@@ -6324,6 +6535,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 failure ??= error;
             }
         }
+        pendingHostSelection = undefined;
         // Quarantine is session-wide by design. Only terminal teardown may drop
         // its ownership after every frame host call and the Captain are drained.
         playerTransactions.clear();

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -24,6 +24,7 @@ import type {
   PlaybookCallRequest,
   PlaybookCallResult,
   PlaybookCallStart,
+  PlaybookControlAction,
   PlaybookControlView,
   PlaybookPorts,
   PlaybookRunResult,
@@ -353,6 +354,31 @@ export interface PlaybookCaptainShell extends Captain {
     session: CaptainSession,
     snapshot: PlaybookCaptainShellSnapshot,
   ): Promise<void>;
+  /**
+   * The active leaf's currently advertised runtime actions, as the host's own
+   * reading of the control view the ControlView digest reads (CAPTAIN-60).
+   * Declared optional because capability absence is member absence: a shell
+   * that publishes no reader advertises nothing.
+   */
+  describeRuntimeActions?(): readonly PlaybookControlAction[];
+  /**
+   * Select one currently advertised runtime action as the next Boss turn's
+   * decision and return that turn's Boss text, which the host submits through
+   * `handleBossTurn` (CAPTAIN-7).
+   */
+  submitRuntimeAction?(actionId: string): string;
+  /**
+   * The controls the shell effects on its own behalf, disjoint from the leaf's
+   * advertised runtime actions (CAPTAIN-62). Declared optional for the same
+   * reason: a shell that publishes no reader advertises nothing.
+   */
+  describeShellActions?(): readonly PlaybookControlAction[];
+  /**
+   * Select one currently advertised shell control as the next Boss turn's
+   * decision and return that turn's Boss text, which the host submits through
+   * `handleBossTurn` (CAPTAIN-7).
+   */
+  submitShellAction?(actionId: string): string;
 }
 
 // Per-enabled-playbook binding the shell resolves at init from the exact
@@ -575,6 +601,9 @@ function isCanonicalLocalRoleId(value: unknown): value is string {
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID =
   'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
+// CAPTAIN-62: the shell's own control, not a runtime action. The id is machine
+// data the host echoes back; the Boss never sees it (CAPPLAY-5).
+const GIVE_UP_ACTION_ID = 'give-up';
 // The fixed machine-syntax guard of a player's Boss-question suspension
 // (slc/link.md §Boss-reply suspension): the accepted outcome that parks on
 // Boss rather than sparing Boss a relay.
@@ -608,6 +637,19 @@ interface ActiveTurn {
    */
   readonly authoritativeText: string;
   readonly resolution?: CaptainParsedResolution;
+  /**
+   * The advertised action id the host selected for this turn (CAPTAIN-7). Its
+   * presence is the turn's decision: the decision state receives that
+   * selection from the shell and allocates no decision call.
+   */
+  readonly hostRuntimeActionId?: string;
+  /**
+   * Set where the host decided this turn by selecting the shell's own give-up
+   * control (CAPTAIN-62). Like `hostRuntimeActionId` its presence is the
+   * turn's decision, and it additionally settles the result phase in the shell
+   * so the turn makes no model call at all (CAPTAIN-63).
+   */
+  readonly hostGiveUp?: true;
   /** A settlement with status `ok` is final for the turn (DR-029). */
   settled: boolean;
   /**
@@ -3118,6 +3160,15 @@ export function createPlaybookCaptainShell(
         outcome: DurableCallOutcome;
       }
     | undefined;
+  // CAPTAIN-7: the control the host selected for the turn it is about to
+  // submit, held with the exact Boss text that turn carries so an unrelated
+  // turn never consumes the selection. One turn consumes it, whichever it is,
+  // and one slot holds it whichever surface it came from — the leaf's
+  // advertised actions or the shell's own controls (CAPTAIN-62).
+  let pendingHostSelection:
+    | { readonly kind: 'runtime'; readonly actionId: string; readonly text: string }
+    | { readonly kind: 'give-up'; readonly text: string }
+    | undefined;
   let lastAction: ControllerAction | undefined;
   let lastSettlementStatus: SettlementEvidence['status'] | undefined;
   // DR-038 §2: a turn can dispose its root before the durable caller asks
@@ -5900,6 +5951,132 @@ export function createPlaybookCaptainShell(
     return lines.join('\n');
   };
 
+  // CAPTAIN-60: the same reading the ControlView digest performs, published as
+  // data instead of prose. It states what the digest states and withholds what
+  // the digest withholds: an idle shell, a leaf with no control surface, and a
+  // control view that cannot be read all advertise nothing, and a leaf fenced
+  // for repository-effect reconciliation advertises only its fence controls.
+  // The pairs are detached and frozen, so a host holds the shell's reading
+  // rather than a live view the runtime can rewrite underneath it.
+  const advertisedRuntimeActions = (): readonly PlaybookControlAction[] => {
+    const empty: readonly PlaybookControlAction[] = Object.freeze([]);
+    if (lifecycle !== 'ready' || terminallyDisposed) return empty;
+    // Between turns: while a turn is running, the leaf's control view is the
+    // decision's grounding and the host can act on no selection, so the shell
+    // publishes none and reads nothing from a runtime mid-run.
+    if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+      return empty;
+    }
+    const leaf = leafFrame();
+    if (!leaf || typeof leaf.runtime.describe !== 'function') return empty;
+    refreshRetainedEffectFence();
+    const fenced = retainedEffectReconciliation !== undefined;
+    if (fenced && typeof leaf.runtime.apply !== 'function') return empty;
+    let actions: readonly PlaybookControlAction[];
+    try {
+      actions = leaf.runtime.describe().actions;
+    } catch {
+      // An unreadable control view advertises nothing.
+      return empty;
+    }
+    return Object.freeze(
+      actions
+        .filter(
+          (action) =>
+            !fenced ||
+            action.id === UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID ||
+            action.id === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID,
+        )
+        .map((action) => Object.freeze({ id: action.id, label: action.label })),
+    );
+  };
+
+  // CAPTAIN-62: the controls the shell effects itself, published beside the
+  // leaf's advertised actions and never mixed with them — these are the
+  // shell's own, so an engaged root offers one whatever its leaf advertises,
+  // fenced or not. A fenced root keeps its control because giving up reports
+  // unresolved effects (CAPTAIN-58) rather than reconciling them, and a run
+  // whose effects are unknown is exactly the run a Boss gives up on.
+  const advertisedShellActions = (): readonly PlaybookControlAction[] => {
+    const empty: readonly PlaybookControlAction[] = Object.freeze([]);
+    if (lifecycle !== 'ready' || terminallyDisposed) return empty;
+    // Between turns, on the same rule the leaf's actions take: mid-turn the
+    // host can act on no selection.
+    if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+      return empty;
+    }
+    const root = rootFrame();
+    if (!root) return empty;
+    return Object.freeze([
+      Object.freeze({
+        id: GIVE_UP_ACTION_ID,
+        // The label is the turn's durable Boss text, so it names the run the
+        // way the Boss started it rather than the frame that happens to be
+        // parked inside it.
+        label: `Stop ${frameLabel(root)}`,
+      }),
+    ]);
+  };
+
+  // CAPTAIN-7: the host's selection of the shell's own control, validated here
+  // against the same live reading. The returned text is the turn the host
+  // submits, exactly as for an advertised runtime action.
+  const selectShellAction = (actionId: string): string => {
+    if (lifecycle !== 'ready' || terminallyDisposed) {
+      throw new Error(
+        'a shell control requires an initialized or restored Captain shell',
+      );
+    }
+    if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+      throw new Error('a shell control cannot be selected during a Boss turn');
+    }
+    if (typeof actionId !== 'string' || actionId.length === 0) {
+      throw new TypeError('a shell control id must be a nonempty string');
+    }
+    const advertised = advertisedShellActions().find(
+      (action) => action.id === actionId,
+    );
+    if (advertised === undefined) {
+      throw new Error('the shell does not advertise that control');
+    }
+    pendingHostSelection = { kind: 'give-up', text: advertised.label };
+    return advertised.label;
+  };
+
+  // CAPTAIN-7: the host's own selection of one advertised action, validated
+  // here against the same live reading and validated again at the controller
+  // port before any effect. The returned text is the turn the host submits.
+  const selectRuntimeAction = (actionId: string): string => {
+    if (lifecycle !== 'ready' || terminallyDisposed) {
+      throw new Error(
+        'a runtime action requires an initialized or restored Captain shell',
+      );
+    }
+    if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+      throw new Error('a runtime action cannot be selected during a Boss turn');
+    }
+    if (typeof actionId !== 'string' || actionId.length === 0) {
+      throw new TypeError('a runtime action id must be a nonempty string');
+    }
+    const advertised = advertisedRuntimeActions().find(
+      (action) => action.id === actionId,
+    );
+    if (advertised === undefined) {
+      // CAPPLAY-5: the chosen id is control data whether or not the leaf
+      // advertises it, so the refusal names the fact and not the string.
+      throw new Error('the active leaf does not advertise that action');
+    }
+    const text =
+      typeof advertised.label === 'string' ? advertised.label.trim() : '';
+    if (text.length === 0) {
+      throw new Error(
+        'the advertised action carries no Boss-facing label to submit as its turn',
+      );
+    }
+    pendingHostSelection = { kind: 'runtime', actionId, text };
+    return text;
+  };
+
   // The catalog is registry-authored, not shell-authored: an id, a command,
   // and an intent all arrive from an enabled module. They pass the same seam
   // the ControlView lines do, so an intent carrying a newline cannot open a
@@ -6471,6 +6648,42 @@ export function createPlaybookCaptainShell(
             ? []
             : [labeledBlock('Conversation recap', options.reseedDigest)]),
         ]);
+      // CAPTAIN-7: a turn whose decision the host already made allocates no
+      // decision call. The host's selection is this state's decision reply, so
+      // it passes the runtime's own reply validation and reaches the shell
+      // through the controller port like every other selection — validation,
+      // execution, the outcome report, and the closing reply are the loop's.
+      if (kind === 'decision' && turn?.hostRuntimeActionId !== undefined) {
+        return {
+          status: 'ok' as const,
+          finalText: JSON.stringify({
+            action: 'runtime',
+            actionId: turn.hostRuntimeActionId,
+          }),
+        };
+      }
+      // CAPTAIN-63: a give-up allocates neither call. Its decision is the
+      // host's, and its result phase is answered below from the settlement the
+      // shell already holds, so an exit from a failing provider does not ask
+      // that provider for permission.
+      if (kind === 'decision' && turn?.hostGiveUp === true) {
+        return {
+          status: 'ok' as const,
+          finalText: JSON.stringify({ action: 'dismiss' }),
+        };
+      }
+      if (kind === 'closingReply' && turn?.hostGiveUp === true) {
+        // The durable conversation did not receive this turn, so it is marked
+        // for the CAPTAIN-35 catch-up rather than left believing it is
+        // current: the next call carries the journal records it missed.
+        markConversationCatchUp();
+        // Through the one presentation seam, exactly where a model-composed
+        // reply is presented, so this reply is journaled and single-attempt
+        // like every other. It needs no reply validation or corrective re-ask:
+        // `giveUpReplyText` already validated what it composed.
+        await surfaceSettlement({ context, text: giveUpReplyText() });
+        return { status: 'ok' as const, finalText: 'ok' };
+      }
       const outcome = await durableCall(context, compose);
       if (kind === 'decision') {
         // A model-decided `respond` surfaces this call's own prose, so the
@@ -6701,8 +6914,17 @@ export function createPlaybookCaptainShell(
     if (!root) return false;
     const label = frameLabel(root);
     // Dismissal leaves the procedure unfinished. Persist the latest safe
-    // generation captured for this turn before disposal erases the frames.
-    retainOrClearDisposedRoot(root);
+    // generation captured for this turn before disposal erases the frames —
+    // unless the Boss gave up on it (CAPTAIN-44), in which case retaining it
+    // would offer the abandoned run back on the idle digest's next reading.
+    if (activeTurn?.hostGiveUp === true) {
+      pendingRetentionUpdates.set(root.entry.id, {
+        kind: 'clear',
+        rootPlaybookId: root.entry.id,
+      });
+    } else {
+      retainOrClearDisposedRoot(root);
+    }
     try {
       await runEffect(() => disposeStack('dismiss'));
       facts.push(`Dismissed the ${label} engagement.`);
@@ -7276,10 +7498,16 @@ export function createPlaybookCaptainShell(
       if (!leaf) {
         return rejectSelection(selection, 'no engagement is active to dismiss');
       }
+      // CAPTAIN-63: a give-up ends the run. An ordinary dismissal of a nested
+      // call returns to its caller, which is the right reading of "stop this
+      // call" and the wrong one of "stop this workflow" — the Boss gave up on
+      // the root, not on whichever child was parked when they did.
+      const giveUp = turn.hostGiveUp === true;
+      const dismissed = giveUp ? (rootFrame() ?? leaf) : leaf;
       turn.settled = true;
-      journalAction({ action: 'dismiss', playbookId: leaf.entry.id });
-      const label = frameLabel(leaf);
-      if (leaf.parent) {
+      journalAction({ action: 'dismiss', playbookId: dismissed.entry.id });
+      const label = frameLabel(dismissed);
+      if (leaf.parent && !giveUp) {
         // No boundary around the return itself: `resumeParent` disposes the
         // child and drives the parent, and each of those is marked where it
         // happens. A visibility rejection raised on the way back is shell
@@ -7615,6 +7843,29 @@ export function createPlaybookCaptainShell(
   // The reply composes from the authoritative report, never the early
   // `settled` guard. That guard closes duplicate submissions before an effect
   // starts; it is not evidence that anything ran.
+  // CAPTAIN-63: the give-up's closing reply, composed from the same settlement
+  // facts the result-phase prompt would have carried. Shell-authored Boss
+  // prose passes the validation every model reply passes (CAPTAIN-34); what it
+  // interpolates is not host-authored all the way down, so a fact set that
+  // fails validation is dropped rather than spoken and the reply still states
+  // the settlement truthfully.
+  const giveUpReplyText = (): string => {
+    const report = activeTurn?.report;
+    const facts = report?.bossFacts ?? report?.facts ?? [];
+    const opening = 'Stopped that workflow. I will not resume it.';
+    const closing = 'Send the command again to start fresh work.';
+    const composed = [
+      opening,
+      ...(facts.length === 0
+        ? []
+        : ['Here is what happened:', ...facts.map((fact) => `- ${fact}`)]),
+      closing,
+    ].join('\n');
+    return replyRejection(composed) === undefined
+      ? composed
+      : [opening, closing].join('\n');
+  };
+
   const failureReplyText = (): string => {
     const commands = [...enablementById.values()]
       .map((enablement) => `/${enablement.command} <task>`)
@@ -8685,6 +8936,14 @@ export function createPlaybookCaptainShell(
 
     installRetainedGenerations,
 
+    describeRuntimeActions: advertisedRuntimeActions,
+
+    submitRuntimeAction: selectRuntimeAction,
+
+    describeShellActions: advertisedShellActions,
+
+    submitShellAction: selectShellAction,
+
     async handleBossTurn(
       turn: BossTurn,
       context: CaptainContext,
@@ -8724,13 +8983,28 @@ export function createPlaybookCaptainShell(
       const turnHostCalls = new Set<Promise<unknown>>();
       activeTurnHostCalls = turnHostCalls;
       activeContext = context;
-      const parsed = resolveCommandTurn(turn.prompt);
+      // CAPTAIN-7: one host selection is consumed by one turn. It decides only
+      // the turn carrying the exact text the selection was made for; any other
+      // turn drops it and resolves normally.
+      const selected = pendingHostSelection;
+      pendingHostSelection = undefined;
+      const decided =
+        selected !== undefined && selected.text === turn.prompt
+          ? selected
+          : undefined;
+      const hostRuntimeActionId =
+        decided?.kind === 'runtime' ? decided.actionId : undefined;
+      const hostGiveUp = decided?.kind === 'give-up' ? true : undefined;
+      const parsed =
+        decided === undefined ? resolveCommandTurn(turn.prompt) : undefined;
       activeTurn = {
         id: ++turnSequence,
         captainSyncedJournalSeq: journalSeq,
         bossText: turn.prompt,
         authoritativeText: parsed?.authoritativeText ?? turn.prompt,
         ...(parsed ? { resolution: parsed.resolution } : {}),
+        ...(hostRuntimeActionId === undefined ? {} : { hostRuntimeActionId }),
+        ...(hostGiveUp === undefined ? {} : { hostGiveUp }),
         settled: false,
         presentationAttempted: false,
         settlementFacts: [],
@@ -8880,6 +9154,7 @@ export function createPlaybookCaptainShell(
         failure ??= error;
       }
     }
+    pendingHostSelection = undefined;
     // Quarantine is session-wide by design. Only terminal teardown may drop
     // its ownership after every frame host call and the Captain are drained.
     playerTransactions.clear();

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -21,7 +21,8 @@
 # Drop an adapter from this file and you can skip its SDK entirely.
 # Every seeded agent runs in cligent's protected auto mode
 # (permissions.mode: auto): claude maps it to permissionMode auto, codex to
-# on-request + auto_review. Codex roles also grant writablePaths: ['.git']
+# on-request + auto_review. A codex agent additionally needs
+# writablePaths: ['.git'] to write git metadata under its sandbox.
 # so they can inspect and work with repository metadata under the sandbox.
 
 # The Captain/Judge agent.
@@ -46,15 +47,13 @@ notifications:
 # shares one provider conversation across those playbooks.
 players:
   dev.coder:
-    adapter: codex
-    model: gpt-5.6-sol
-    effort: ultra
+    adapter: claude
+    model: claude-opus-5
+    effort: high
     # Adapter-scoped fast mode is validated by the installed Cligent contract;
     # omitting it takes the provider default.
-    fastMode: true
     permissions:
       mode: auto
-      writablePaths: ['.git']
 
   dev.reviewer:
     adapter: claude

package/reference/sdlc/code.playbook/session-host.d.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
+import type { PlaybookControlAction } from '@sublang/playbook/runtime';
 import type { PlaybookCaptainShell, PlaybookCaptainShellSnapshot } from './playbook-captain.js';
 import type { PlaybookEffectLedger } from './host-capabilities.js';
 import type { PlaybookSessionLifecycle, SessionExecutionProjection, SessionStructuralProjection, SessionFreshBoundary, SessionRecovery } from './session-store.js';
@@ -68,6 +69,31 @@ export interface SessionHostController {
   readonly lease: PlaybookSessionLifecycle;
   read(): Promise<SessionRecovery | undefined>;
   handleBossTurn(input: string): Promise<SessionRecovery>;
+  /**
+   * The active leaf's currently advertised runtime actions, read live between
+   * turns; empty whenever nothing is advertised, a turn is active, or the
+   * leaf's control view cannot be read.
+   */
+  listRuntimeActions(): readonly PlaybookControlAction[];
+  /**
+   * Submit one currently advertised runtime action as the session's next turn.
+   * The turn is the same durable transaction `handleBossTurn` runs, and its
+   * decision is the submitted selection, so no decision model call is made.
+   */
+  submitRuntimeAction(actionId: string): Promise<SessionRecovery>;
+  /**
+   * The controls the shell offers on its own behalf, read live between turns;
+   * today one give-up while a root is engaged, and empty while idle or while a
+   * turn is active. Disjoint from `listRuntimeActions`, which reads the leaf.
+   */
+  listShellActions(): readonly PlaybookControlAction[];
+  /**
+   * Submit one currently advertised shell control as the session's next turn.
+   * The turn is the same durable transaction `handleBossTurn` runs; both its
+   * decision and its closing reply are the shell's, so the turn makes no model
+   * call and a give-up survives a provider that is refusing everything.
+   */
+  submitShellAction(actionId: string): Promise<SessionRecovery>;
   retry(): Promise<SessionRecovery>;
   dispose(): Promise<void>;
 }