@ctrl-spc/cs 0.7.8 → 0.7.10

package/dist/codex-home.js

@@ -215,12 +215,6 @@ subagentsEnabled = true, persistentPanelOwner = false) {
     const lines = [
         '# Written by CTRL+SPC for ONE codex run. Not the user\'s config; never read',
         '# by anything but the worker this was written for.',
-        /* The Windows Desktop bundle can lag the account's server-selected default
-           model. When that default requires a newer client, every headless worker
-           exits before its first action. Pin the current broadly-supported model
-           only for that bundled runtime; other platforms keep Codex's own model
-           selection. */
-        ...(runtimePlatform === 'win32' ? ['model = "gpt-5.5"', ''] : []),
         ...(persistentPanelOwner ? [
             'sandbox_mode = "workspace-write"',
             '',
@@ -258,6 +252,9 @@ subagentsEnabled = true, persistentPanelOwner = false) {
     if (server) {
         const url = mcpUrl(server, runTodoId);
         lines.push('[mcp_servers.ctrl-spc]', `url = ${JSON.stringify(url)}`, 
+        // A missing product tool connection must fail startup, not leave a run
+        // producing answers without its dispatch and completion tools.
+        'required = true', 
         /* See the block comment above: without this every tool call is cancelled
            client-side before it leaves the worker. */
         'default_tools_approval_mode = "approve"', '');

package/dist/mcp.js

@@ -14,8 +14,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING, assertAgentToolMentions } from './workflows.js';
-import { workflowToolForName } from './workflow-tool-mentions.js';
+import { workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING, WORKFLOW_AUTHORING_TEACHING, authorToolMentions } from './workflows.js';
+import { workflowToolForName, validateApprovalAction } from './workflow-tool-mentions.js';
 import { TOOLS_SERVER_PORT, SESSION_TTL_MS } from './env.js';
 import { agentPath } from './agents.js';
 import { mcpToken, readMcpToken, readSession } from './config.js';
@@ -7802,24 +7802,19 @@ export async function readWorkflowLibraryHandler(client, args, userId) {
         // workflow ids actually present rather than as PostgREST embeds, the same
         // two-step `listClientsHandler` uses.
         const workflowIds = workflows.map((workflow) => workflow.id);
-        const links = workflowIds.length
-            ? ((await must(client
-                .from('cliv2_workflow_stages_in_workflow')
-                .select('workflow_id, stage_id, position')
-                .in('workflow_id', workflowIds))) ?? [])
-            : [];
-        const exits = workflowIds.length
-            ? ((await must(client
-                .from('cliv2_workflow_stage_exits')
-                .select('workflow_id, stage_id, to_stage_id, condition, position')
-                .in('workflow_id', workflowIds))) ?? [])
-            : [];
-        const branches = workflowIds.length
-            ? ((await must(client
-                .from('cliv2_workflow_branches')
-                .select('workflow_id, when_condition, runs_workflow_id, position')
-                .in('workflow_id', workflowIds))) ?? [])
-            : [];
+        const links = [];
+        const exits = [];
+        const branches = [];
+        // Like artifact counts above, bound GET filters so a large library remains readable.
+        for (let offset = 0; offset < workflowIds.length; offset += COUNT_BATCH) {
+            const ids = workflowIds.slice(offset, offset + COUNT_BATCH);
+            links.push(...(await must(client.from('cliv2_workflow_stages_in_workflow')
+                .select('workflow_id, stage_id, position').in('workflow_id', ids))) ?? []);
+            exits.push(...(await must(client.from('cliv2_workflow_stage_exits')
+                .select('workflow_id, stage_id, to_stage_id, condition, position').in('workflow_id', ids))) ?? []);
+            branches.push(...(await must(client.from('cliv2_workflow_branches')
+                .select('workflow_id, when_condition, runs_workflow_id, position').in('workflow_id', ids))) ?? []);
+        }
         const orgIds = [
             ...new Set([...stages.map((s) => s.org_id), ...workflows.map((w) => w.org_id)]),
         ];
@@ -7952,7 +7947,7 @@ export async function buildWorkflowHandler(client, args, fromAgent) {
                 prose.push([`stages[${index}].description`, stage.description]);
             }
             if (typeof stage.body === 'string') {
-                assertAgentToolMentions(stage.body);
+                stage.body = authorToolMentions(stage.body);
                 prose.push([`stages[${index}].body`, stage.body]);
             }
         });
@@ -8050,7 +8045,7 @@ export async function editWorkflowHandler(client, args, fromAgent) {
                 prose.push([`stages[${index}].description`, stage.description]);
             }
             if (typeof stage.body === 'string') {
-                assertAgentToolMentions(stage.body);
+                stage.body = authorToolMentions(stage.body);
                 prose.push([`stages[${index}].body`, stage.body]);
             }
         });
@@ -8693,6 +8688,7 @@ export const TOOL_NAMES = [
     // 18c Slice 1: the run's own activity, unasked, on the request's card.
     'report_activity',
     'ask_question',
+    'require_approval',
     'present_wireframes',
     'present_mocks',
     'resolve_feedback',
@@ -8801,6 +8797,7 @@ const SERVER_INSTRUCTIONS = `You are connected to CTRL+SPC, where this user's wo
    - The PLAN for a work item: create_stage and create_step to lay it out, then update_step to record progress — in_progress when you start, a rewritten next_action as it changes, done when finished. Never create a second step to report on the first. These need a WORK ITEM and an approved scope: they are its committed plan, not a log of what you did. A panel request with no work item has no plan to write, so use report_activity and, if the work deserves an item of its own, ask for one. Never attach it to an unrelated work item to get past a refusal.
    - Anything learned, decided or discovered: record_user_input, add_comment, record_context_exploration, propose_project_context. The transcript is never the record.
    - Following a process: read_workflow_library, then start_workflow on the work item so its stages appear where the user can watch them.
+   - Creating a reusable workflow: build_workflow. Describe the requested process in its stages; do not execute those stages or create a plan artifact about creating the workflow. Ask only the clarification needed to author it, through ask_question. A work item used to hold this conversation does not turn workflow authoring into code implementation. ${WORKFLOW_AUTHORING_TEACHING}
    - A method the team has already written down: list_skills, then get_skill. A skill is a document TO FOLLOW for the rest of the work, not reference material to summarise. Look before improvising your own method.
    - A secret the work needs: list_credentials, then get_credential. Fetch it rather than asking the user for something they have already stored, and never write a value into a file, a commit, a log or your answer.
    Call list_tasks or get_task first when you need to know what the work is, and LOOK BEFORE YOU CREATE: if a work item already covers this, use it instead of adding a near-duplicate. If you are unsure whether a tool exists, look before falling back to the terminal.
@@ -10726,8 +10723,28 @@ runTodoIdSource = null) {
         touchSession(connectionId);
         return readWorkflowLibraryHandler(client, args, userId);
     });
+    server.registerTool('require_approval', {
+        description: 'Pause for the user to approve a specific action before you perform it, including editing code, running a migration, or pushing commits. Name its exact scope in action and details; use relative paths, never absolute local paths. Stop on pending or denial; retry the identical call after the answer. Only an approved result permits that action. This tool does not execute it. ' + WORKFLOW_TOOL_TEACHING,
+        inputSchema: {
+            action: z.string().trim().min(1).max(240),
+            details: z.string().trim().min(1).max(8000),
+            workflow_tool_instance: z.string().uuid().optional(),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        try {
+            validateApprovalAction(args.action, args.details);
+            const session = openSessions.get(connectionId) ?? null;
+            await permissionForWorkflowCall(client, session, 'require_approval', args);
+            return runGated(client, userId, session, 'require_approval', args, `${args.action} — ${args.details}`, async () => textResult({ approved: true, action: args.action, details: args.details,
+                instruction: 'The user approved only this action and scope. You may now perform it.' }), await runTodoIdOf());
+        }
+        catch (error) {
+            return errorResult(errorMessage(error));
+        }
+    });
     server.registerTool('build_workflow', {
-        description: 'Build a WHOLE workflow in one call in CTRL+SPC — its stages, the order they run in, the ' +
+        description: WORKFLOW_AUTHORING_TEACHING + 'Build a WHOLE workflow in one call in CTRL+SPC — its stages, the order they run in, the ' +
             'loops back between them, and the branch conditions that apply everywhere. This is the ' +
             'only way to create a workflow: there is no create-stage tool, because assembling one ' +
             'piece at a time is the work this removes. ' +

package/dist/panel3/prompt.js

@@ -598,6 +598,12 @@ export function workBrief(level, responsibility, boundary, workItemId, attachmen
                 'time, and before any reading that takes a while. It does not end your turn and it is not',
                 'your reply; you carry on straight afterwards.',
                 '',
+                'WORKFLOW AUTHORING',
+                'When asked to create a workflow, use create_workflow to save it; do not execute the workflow.',
+                'Ask clarifying questions with ask_question only when the missing answer changes its behavior.',
+                'Write the requested tool mentions and per-use permissions in the stage bodies using the tool schema instructions.',
+                'The saved workflow appears as a reviewable card in this conversation. Do not substitute a plan artifact or a prose-only reply.',
+                '',
                 'TRACEABILITY BEFORE A CODEBASE FILE CHANGES',
                 'A codebase-file change means ANY file change: source, config, docs, tests, migrations,',
                 'generated inputs, and assets all count. "Non-code" means no codebase file changes at all.',
@@ -1159,3 +1165,14 @@ function respawnPrompt(opening, brief, report, children) {
         brief,
     ].join('\n');
 }
+/** Selection belongs to each dispatch, not to the card or its parent's model. */
+export function modelChoiceRules(harness) {
+    return [
+        'MODEL AND EFFORT FOR EACH DISPATCH',
+        `You run under ${harness}. Your dispatched children use the same harness.`,
+        'The dispatch tool accepts optional model and effort strings. Honor the user\'s exact stated model and effort for the work they apply to, including downstream workers. Copy each requested value byte-for-byte into the dispatch argument: do not expand aliases, normalize spelling or case, or replace it with a canonical provider identifier. Carry those wishes and their scope verbatim in every applicable responsibility and boundary.',
+        'When the user requests separate workers or assigns choices to separate parts, call dispatch for those parts. Doing their work yourself does not satisfy that request. If product tools are deferred, discover dispatch before starting; use the product ask_question and write_report tools for questions and completion.',
+        'When the user has not specified a value, choose for this child\'s task using your knowledge of this harness. Pass your choice in the tool arguments; a sentence alone does not select it. Different workers may use different choices.',
+        'Omitting a value chooses the harness default (or the machine-local model default), never the parent\'s model or effort. No product model catalog exists. Pass provider values unchanged; do not silently substitute after a rejection.',
+    ].join('\n');
+}

package/dist/panel3/run.js

@@ -748,6 +748,17 @@ async function setCardState(client, cardId, state) {
         .select('id'), 'set the state of', `card ${cardId}`);
 }
 // ---------------------------------------------------------------------------
+/** Each start reloads only this run's durable choices, including null defaults. */
+export async function settingsForRun(client, runId) {
+    const rows = await returned(client.from('panel3_runs').select('model, effort, harness').eq('id', runId), 'read', `model and effort for run ${runId}`);
+    const row = rows[0];
+    if (!row || (row.harness !== null && row.harness !== 'claude' && row.harness !== 'codex')
+        || (row.model !== null && typeof row.model !== 'string')
+        || (row.effort !== null && typeof row.effort !== 'string')) {
+        throw new Error('The run has no readable harness, model and effort selection.');
+    }
+    return { model: row.model, effort: row.effort, harness: row.harness ?? undefined };
+}
 /**
  * One card, from the turns the take handed over to the answer on its thread.
  *
@@ -804,9 +815,11 @@ async function answerCard(client, tools, machineId, cardId, turns) {
        no rules" — that is a different project than the one the person is on. So it
        joins the three reads above inside this ending rather than beside it. */
     let rules;
+    let settings;
     try {
         brief = briefFor(turns[0].card_title, turns, await receiptsFor(client, cardId), await attachmentsFor(client, cardId), await codebasesForRun(client, runId));
         rules = await standingRulesFor(client, runId);
+        settings = await settingsForRun(client, runId);
         where = await workingDirectory(client, runId, LEVEL, false);
     }
     catch (error) {
@@ -823,7 +836,7 @@ async function answerCard(client, tools, machineId, cardId, turns) {
     /* AN EMPTY DIRECTORY OF THE USER'S OWN, because level 1 has no code tool to
        use a real one with, and the daemon's inherited cwd under a launchd login
        item is the filesystem root. */
-    const started = startAgent(withStandingRules(rules, brief, where.block), LEVEL, tools.urlFor(runId), where.cwd);
+    const started = startAgent(withStandingRules(rules, brief, where.block), LEVEL, tools.urlFor(runId), where.cwd, undefined, settings);
     out(`run      ${runId}  level ${LEVEL}  ${started.pid ? `pid ${started.pid}` : 'no process'}`);
     try {
         /* THE BRIEF, NOT WHAT THE PROCESS WAS HANDED. The rules are current at the
@@ -1162,14 +1175,16 @@ async function workingDirectory(client, runId, level, isOwner, knownCodebase) {
  * Then the row, then the process, then the pid — constraint 8, in the only order
  * that satisfies it.
  */
-async function startChild(client, tools, machineId, parentRunId, brief, codebase, parentProcessToken) {
+async function startChild(client, tools, machineId, parentRunId, brief, codebase, parentProcessToken, choice = {}) {
     const { data, error } = await client.rpc('panel3_dispatch', {
         p_parent_run_id: parentRunId,
         p_brief: brief,
         p_machine_id: machineId,
         p_codebase_id: codebase?.id ?? null,
         p_codebase_label: codebase?.name ?? null,
-        ...(parentProcessToken === undefined ? {} : { p_process_token: parentProcessToken }),
+        p_process_token: parentProcessToken ?? null,
+        p_model: choice.model ?? null,
+        p_effort: choice.effort ?? null,
     });
     if (error)
         throw new Error(`could not start an agent under run ${parentRunId}: ${readableWriteError(error.message)}`);
@@ -1200,12 +1215,14 @@ async function startChild(client, tools, machineId, parentRunId, brief, codebase
        exists (`panel3_dispatch` wrote it above) and it carries this child's
        codebase, which is what decides which codebase-scoped rules it is under. */
     let rules;
+    let settings;
     try {
         where = await workingDirectory(client, row.run_id, level, level === 2, codebase);
         prompt = level === 2
             ? await initialOwnerPrompt(client, row.run_card_id, parentRunId, brief)
             : brief;
         rules = await standingRulesFor(client, row.run_id);
+        settings = await settingsForRun(client, row.run_id);
         /* Inside this site's own try, for `standingRulesFor`'s reason: a failure to
            assemble what the agent needs ends the run the way this path already ends
            runs, rather than starting a process that is missing it. */
@@ -1218,7 +1235,7 @@ async function startChild(client, tools, machineId, parentRunId, brief, codebase
     }
     const processToken = row.process_token ?? undefined;
     const isOwner = level === 2;
-    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id, processToken), where.cwd, isOwner ? { ownerId: row.run_id } : undefined);
+    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id, processToken), where.cwd, isOwner ? { ownerId: row.run_id } : undefined, settings);
     if (started.pid === null) {
         /* THERE IS A ROW AND THERE IS NO PROCESS, which is the one shape the record
            must never be left in quietly. The answer is already settled — nothing ran
@@ -1688,9 +1705,11 @@ async function resumeRun(client, tools, machineId, runId, afterPid) {
        is a `returned()` message naming tables and columns, which carries no local
        path and is therefore shareable. */
     let rules;
+    let settings;
     let pictures;
     try {
         rules = await standingRulesFor(client, runId);
+        settings = await settingsForRun(client, runId);
         /* ═══ WRITTEN AGAIN ON EVERY START, LIKE THE RULES. ═══ A resumed process is
            a NEW process with a new copy of the working directory, so the files a
            previous one was handed are not there any more, and the stored brief this
@@ -1709,7 +1728,7 @@ async function resumeRun(client, tools, machineId, runId, afterPid) {
        still running. See `retryPrompt`. */
     withStandingRules(rules, afterPid === null
         ? resumePrompt(claimed.run_brief, claimed.run_report, children)
-        : retryPrompt(claimed.run_brief, claimed.run_report, children), where.block, [], pictures), level, tools.urlFor(runId), where.cwd);
+        : retryPrompt(claimed.run_brief, claimed.run_report, children), where.block, [], pictures), level, tools.urlFor(runId), where.cwd, undefined, settings);
     if (started.pid === null) {
         /* THE CLAIM HAPPENED AND NO PROCESS DID, which is the one shape the record
            must never be left in quietly. Same handling as a dispatch that could not
@@ -1816,9 +1835,11 @@ async function startRearmed(client, tools, machineId, row) {
        same way: the re-arm's claim has already happened, so a failure here ends
        the run with its reason rather than leaving it claimed with no process. */
     let rules;
+    let settings;
     let pictures;
     try {
         rules = await standingRulesFor(client, row.run_id);
+        settings = await settingsForRun(client, row.run_id);
         pictures = await picturesOnDisk(client, row.run_card_id, where, level);
     }
     catch (error) {
@@ -1826,7 +1847,7 @@ async function startRearmed(client, tools, machineId, row) {
         await endRun(client, level, row.run_id, row.run_card_id, why);
         throw new Error(`NO AGENT IS RUNNING: ${why}`);
     }
-    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id), where.cwd);
+    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id), where.cwd, undefined, settings);
     if (started.pid === null) {
         const answer = await started.answered;
         const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
@@ -2064,6 +2085,7 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
        says what the product DID with the person's answer, and the landing needs
        the card's copy. Nothing in the prompt depended on it before. */
     let rules;
+    let settings;
     /* THE CARD'S COPY IS MADE IN THE SAME WINDOW AND UNDER THE SAME ENDING, for
        the reason the check above gives: it writes, so it happens after the claim,
        and a failure to make it is an activation that ends rather than one that
@@ -2087,6 +2109,7 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
     try {
         where = await ownerDirectory(client, candidate);
         rules = await standingRulesFor(client, runId);
+        settings = await settingsForRun(client, runId);
         attached = whatWasAttached((await attachmentsFor(client, claimed.run_card_id))
             .filter((line) => !line.startsWith('codebase  ')));
         /* ═══ THE OWNER'S OWN ACTIVATION, WHICH IS WHERE MOST PICTURES ARRIVE. ═══
@@ -2119,7 +2142,7 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
            are not the same event and `prompt.ts` exists to stop an agent being
            told an untrue reason for its own restart. */
         afterPid !== null, landing);
-    const started = startAgent(withStandingRules(rules, prompt, where.block, attached, pictures), 2, tools.urlFor(runId, claimed.process_token), where.cwd, { ownerId: runId, ...(resumeSessionId ? { resumeSessionId } : {}) });
+    const started = startAgent(withStandingRules(rules, prompt, where.block, attached, pictures), 2, tools.urlFor(runId, claimed.process_token), where.cwd, { ownerId: runId, ...(resumeSessionId ? { resumeSessionId } : {}) }, settings);
     if (started.pid === null) {
         const answer = await started.answered;
         const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
@@ -3100,8 +3123,8 @@ export async function run(args, injected) {
        `tools` is referenced inside the callback it is being given, which is safe
        for the plain reason that the callback can only run once a request has
        arrived at a server that by then exists. */
-    const tools = await startToolsServer(current(), async (parentRunId, brief, codebase, processToken) => {
-        const child = await startChild(current(), tools, machineId, parentRunId, brief, codebase, processToken);
+    const tools = await startToolsServer(current(), async (parentRunId, brief, codebase, processToken, choice) => {
+        const child = await startChild(current(), tools, machineId, parentRunId, brief, codebase, processToken, choice);
         hold(child.runId, child.settled);
         return { runId: child.runId };
     });

package/dist/panel3/show.js

@@ -83,7 +83,7 @@ const read = (query, what) => returned(query, 'read', what);
 const CARD_COLUMNS = 'id, project_id, title, state, created_at, archived_at';
 const TURN_COLUMNS = 'id, card_id, role, body, created_at, addressed_at, run_id';
 const RUN_COLUMNS = 'id, card_id, codebase_id, branch, parent_run_id, level, state, brief, report, failed_because, '
-    + 'activity, machine_id, pid, started_at, resumed_at, read_back_at, ended_at';
+    + 'activity, machine_id, pid, started_at, resumed_at, read_back_at, ended_at, model, effort';
 const ASK_COLUMNS = `id, card_id, run_id, pending_run_id, answered_at, delivered_at, created_at, ${ASK_CONTENT_COLUMNS}`;
 const OUTPUT_COLUMNS = 'id, card_id, run_id, kind, ref_id, label, created_at';
 const ATTACHMENT_COLUMNS = 'id, card_id, kind, ref_id, label, created_at';
@@ -1125,6 +1125,10 @@ async function showRun(client, run) {
     out(`RUN  ${run.id}`);
     out(`  card     ${run.card_id}${card ? `  ${card.title}` : '  (card not readable)'}`);
     out(`  level    ${run.level}`);
+    if (run.model != null)
+        out(`  model    ${run.model}`);
+    if (run.effort != null)
+        out(`  effort   ${run.effort}`);
     out(`  state    ${run.state}${isLive(run) ? '  (live)' : ''}`);
     out(`  parent   ${run.parent_run_id ?? 'none, dispatched by the daemon'}`);
     out(`  machine  ${run.machine_id}${run.pid ? `  pid ${run.pid}` : '  no pid recorded'}`);

package/dist/panel3/spawn.js

@@ -124,6 +124,7 @@ import { randomUUID } from 'node:crypto';
 import { agentPath } from '../agents.js';
 import { ensureCodexRunHome, ensurePanel3CodexOwnerHome, removeCodexRunHome, } from '../codex-home.js';
 import { windowsSafeSpawn } from '../win-shell.js';
+import { modelChoiceRules } from './prompt.js';
 const AGENT_VAR = 'CTRL_SPC_V3_AGENT';
 /**
  * The harness named on this machine, or the reason the name is not one.
@@ -169,9 +170,9 @@ const allowedTools = (level) => [`mcp__${SERVER}__*`, ...(level === 1 ? [] : COD
  * checked without starting a process — which is how the allowlist is proved,
  * and how it stays provable after this task.
  */
-export function agentArgs(level, toolsUrl, agent = harness(), platform = process.platform, ownerSession) {
+export function agentArgs(level, toolsUrl, agent = harness(), platform = process.platform, ownerSession, choice = {}) {
     if (agent === 'codex')
-        return codexArgs(level, toolsUrl, platform, ownerSession);
+        return codexArgs(level, toolsUrl, platform, ownerSession, choice);
     const session = ownerSession
         ? ownerSession.resumeSessionId
             ? ['--resume', ownerSession.resumeSessionId]
@@ -187,6 +188,8 @@ export function agentArgs(level, toolsUrl, agent = harness(), platform = process
         '--tools', builtIns(level),
         '--allowedTools', allowedTools(level),
         ...session,
+        ...(choice.model == null ? [] : ['--model', choice.model]),
+        ...(choice.effort == null ? [] : ['--effort', choice.effort]),
         /* STATED WHERE THERE IS SOMETHING TO STATE. `acceptEdits` grants file edits
            to a headless process with nobody at a prompt to approve them, and it is
            passed only to the levels that have a file tool to use it with: at level 1
@@ -221,7 +224,7 @@ export function agentArgs(level, toolsUrl, agent = harness(), platform = process
  * `--json` makes the answer an `agent_message` item read out of the stream
  * rather than whatever prose happened to reach stdout (see `codexAnswer`).
  */
-function codexArgs(level, toolsUrl, platform, ownerSession) {
+function codexArgs(level, toolsUrl, platform, ownerSession, choice = {}) {
     const resume = ownerSession?.resumeSessionId;
     return [
         'exec',
@@ -229,6 +232,8 @@ function codexArgs(level, toolsUrl, platform, ownerSession) {
         // The prompt arrives on stdin, exactly as it does for claude: `codex exec`
         // reads it from there when no prompt argument is given.
         '--json',
+        ...(choice.model == null ? [] : ['-m', choice.model]),
+        ...(choice.effort == null ? [] : ['-c', `model_reasoning_effort=${JSON.stringify(choice.effort)}`]),
         // The level 1 scratch directory is not a repository, and neither need a
         // working copy be.
         '--skip-git-repo-check',
@@ -241,13 +246,13 @@ function codexArgs(level, toolsUrl, platform, ownerSession) {
            proven per-run home below. */
         ...(platform === 'win32' ? [
             '--ignore-user-config',
-            '-c', 'model="gpt-5.5"',
             '-c', 'features.apps=false',
             // The same closing `codex-home.ts` writes into the per-run config, and
             // for the same measured reason: `features.multi_agent=false` parses and
             // leaves the tool reachable.
             '-c', 'agents.enabled=false',
             '-c', `mcp_servers.${SERVER}.url=${JSON.stringify(toolsUrl)}`,
+            '-c', `mcp_servers.${SERVER}.required=true`,
             '-c', `mcp_servers.${SERVER}.default_tools_approval_mode="approve"`,
             '-c', 'windows.sandbox="unelevated"',
             '-c', 'windows.sandbox_private_desktop=false',
@@ -291,7 +296,7 @@ function runKey(toolsUrl) {
  * is the forbidden state ux.md is about, so the failure wins wherever both are
  * present.
  */
-export function codexAnswer(stdout) {
+export function codexAnswer(stdout, exitCode = 0, stderr = '') {
     let text = null;
     let failure = null;
     for (const line of stdout.split('\n')) {
@@ -319,6 +324,9 @@ export function codexAnswer(stdout) {
     if (failure !== null) {
         return { ok: false, reason: `codex could not finish the turn${failure ? `: ${failure}` : ''}` };
     }
+    if (exitCode !== 0) {
+        return { ok: false, reason: `codex exited ${exitCode}${tail(stderr) || tail(stdout)}` };
+    }
     if (text === null || text.trim() === '') {
         return { ok: false, reason: 'codex exited 0 without saying anything to the person' };
     }
@@ -377,7 +385,7 @@ function tail(text, chars = 500) {
  * process still alive" after the daemon that started it has been killed. So the
  * caller gets the pid immediately, writes it, and then waits.
  */
-export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
+export function startAgent(prompt, level, toolsUrl, cwd, ownerSession, settings = {}) {
     const failed = (reason) => ({
         pid: null,
         session: Promise.resolve(null),
@@ -385,7 +393,7 @@ export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
     });
     let agent;
     try {
-        agent = harness();
+        agent = settings.harness ?? harness();
     }
     catch (err) {
         // A machine configured for a harness this build has never heard of. See
@@ -395,7 +403,10 @@ export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
     const launchedOwnerSession = ownerSession && !ownerSession.resumeSessionId
         ? { ...ownerSession, freshSessionId: randomUUID() }
         : ownerSession;
-    const ARGS = agentArgs(level, toolsUrl, agent, process.platform, launchedOwnerSession);
+    // A local default applies only to an omitted choice; explicit run values always win.
+    const choice = { ...settings, model: settings.model ?? process.env[`CTRL_SPC_V3_${agent.toUpperCase()}_DEFAULT_MODEL`] };
+    const ARGS = agentArgs(level, toolsUrl, agent, process.platform, launchedOwnerSession, choice);
+    prompt = `${modelChoiceRules(agent)}\n\n${prompt}`;
     const bin = agentPath(agent);
     if (!bin) {
         return failed(`${agent} is not installed on this machine`);
@@ -531,6 +542,11 @@ export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
                    respawn behind it is refused. Naming the signal is the whole fix. */
                 finish({ ok: false, reason: `${agent} was ended by ${signal}${tail(stderr) || tail(stdout)}` });
             }
+            else if (agent === 'codex') {
+                // Startup failures can put the real error in JSON stdout and only
+                // 'Reading prompt from stdin' on stderr, including on non-zero exits.
+                finish(codexAnswer(stdout, code ?? 1, stderr));
+            }
             else if (code !== 0) {
                 /* STDOUT WHEN STDERR IS EMPTY, because `claude -p` prints its own
                    failure on stdout and exits non-zero having written nothing to
@@ -541,11 +557,6 @@ export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
             else if (stdout.trim() === '') {
                 finish({ ok: false, reason: `${agent} exited 0 and said nothing${tail(stderr)}` });
             }
-            else if (agent === 'codex') {
-                /* The stream, not the buffer. See `codexAnswer`: stdout here is
-                   protocol, and a failed turn that exited 0 is still a failure. */
-                finish(codexAnswer(stdout));
-            }
             else {
                 const text = stdout.trim();
                 finish({

package/dist/panel3/tools.js

@@ -114,7 +114,7 @@
 // `import type` loses its v3 header in the published `dist/`.
 import { presentDesign } from '../design-review.js';
 import { canonicalArgsHash, getDocumentHandler, proposeProjectContextHandler, placeWorkItemHandler, resolveFeedbackHandler, PROJECT_DOCUMENT_TYPES, errorMessage } from '../product-tools.js';
-import { workflowToolForName, workflowToolAlwaysAllowed } from '../workflow-tool-mentions.js';
+import { workflowToolForName, workflowToolAlwaysAllowed, validateApprovalAction } from '../workflow-tool-mentions.js';
 import { captureUrlScreenshot } from '../browser.js';
 import { createServer as createHttpServer } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -130,7 +130,7 @@ import { workBrief } from './prompt.js';
    here is the same fact without a second round trip. */
 import { harness } from './spawn.js';
 import { listCodebases } from '../codebases.js';
-import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage, workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING } from '../workflows.js';
+import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage, workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING, WORKFLOW_AUTHORING_TEACHING } from '../workflows.js';
 /* ═══ 38-panel3-steps: THE FIFTH NEUTRAL MODULE, AND A DECISION LIKE THE OTHERS.
    ═══ Stages and steps are the work item's own record, shared by both
    generations and read by the web's Steps section. `steps.ts` owns the rows so
@@ -749,6 +749,13 @@ function productResult(result) {
     return text;
 }
 const TOOLS = [
+    {
+        name: 'require_approval', levels: [1, 2],
+        description: 'Pause for the user to approve a specific action before you perform it, including editing code, running a migration, or pushing commits. Name the action and exact scope using relative paths, never absolute local paths. Stop on pending or denial and retry the identical call after the answer. Only an approved result permits that action. This tool does not execute it.',
+        input: { action: z.string().trim().min(1).max(240), details: z.string().trim().min(1).max(8000) },
+        handler: async (_caller, args) => JSON.stringify({ approved: true, action: args.action, details: args.details,
+            instruction: 'The user approved only this action and scope. You may now perform it.' }),
+    },
     {
         name: 'get_document', levels: ALL,
         description: 'Read a project context document or instruction in full by id. Read-only.',
@@ -1164,7 +1171,7 @@ const TOOLS = [
            described and can write it down as it was described. A launcher writes one
            line and exits; a worker owns one piece of somebody else's process. */
         levels: [2],
-        description: "Write a new workflow into this organisation's library: a name, what it is about, and its "
+        description: WORKFLOW_AUTHORING_TEACHING + "Write a new workflow into this organisation's library: a name, what it is about, and its "
             + 'stages in order, each with a one-line description and the markdown document an agent '
             + 'following it reads. Stages are numbered from 1, the way get_workflow prints them. exits '
             + 'are the conditional ways back: from_stage N, if condition, go back to to_stage M, where M '
@@ -1826,11 +1833,11 @@ const TOOLS = [
             const agents = await rows(client.from('panel3_runs')
                 // `resumed_at` is read because "how long it has been going" is about
                 // the attempt that is running now. See `elapsed`.
-                .select('id, level, parent_run_id, state, activity, started_at, resumed_at, ended_at')
+                .select('id, level, parent_run_id, state, activity, started_at, resumed_at, ended_at, model, effort')
                 .eq('card_id', cardId).order('started_at'), 'read', 'the agents on this card');
             return listed(agents.map((a) => {
                 const live = a.state === 'running' && !a.ended_at;
-                return line(a.id, `L${a.level}`, a.parent_run_id ? `parent ${a.parent_run_id}` : 'no parent, dispatched by the daemon', live ? 'still running' : a.state, a.activity ?? null, live
+                return line(a.id, `L${a.level}`, a.parent_run_id ? `parent ${a.parent_run_id}` : 'no parent, dispatched by the daemon', live ? 'still running' : a.state, a.activity ?? null, a.model == null ? null : `model ${a.model}`, a.effort == null ? null : `effort ${a.effort}`, live
                     ? `going ${elapsed(a.started_at, null, a.resumed_at)}`
                     : `went ${elapsed(a.started_at, a.ended_at, a.resumed_at)}`);
             }), 'Nothing has run on this card.');
@@ -1844,9 +1851,11 @@ const TOOLS = [
             + 'in your prompt; this is here for when you need to re-read them mid-run.',
         input: {},
         handler: async ({ client, runId }) => {
-            const run = await only(client.from('panel3_runs').select('level, brief, report, activity').eq('id', runId), 'read', 'your own run');
+            const run = await only(client.from('panel3_runs').select('level, brief, report, activity, model, effort').eq('id', runId), 'read', 'your own run');
             return [
                 `You are a level ${run.level} agent.`,
+                ...(run.model == null ? [] : [`MODEL  ${run.model}`]),
+                ...(run.effort == null ? [] : [`EFFORT  ${run.effort}`]),
                 '',
                 'BRIEF, written when you were dispatched and never changed',
                 run.brief,
@@ -1871,9 +1880,9 @@ const TOOLS = [
             + 'dispatch the same work twice.',
         input: {},
         handler: async ({ client, runId }) => {
-            const children = await rows(client.from('panel3_runs').select('id, level, state, activity, started_at, ended_at')
+            const children = await rows(client.from('panel3_runs').select('id, level, state, activity, started_at, ended_at, model, effort')
                 .eq('parent_run_id', runId).order('started_at'), 'read', 'the runs you dispatched');
-            return listed(children.map((c) => line(c.id, `L${c.level}`, c.state === 'running' && !c.ended_at ? 'still running' : c.state, c.activity ?? null)), 'You have dispatched nothing.');
+            return listed(children.map((c) => line(c.id, `L${c.level}`, c.state === 'running' && !c.ended_at ? 'still running' : c.state, c.activity ?? null, c.model == null ? null : `model ${c.model}`, c.effort == null ? null : `effort ${c.effort}`)), 'You have dispatched nothing.');
         },
     },
     {
@@ -2887,6 +2896,8 @@ const TOOLS = [
                 + 'context: what to find out or change, and in which part of the codebase.'),
             boundary: z.string().min(1).describe('What it must not touch, and where its work stops.'),
             work_item_id: z.string().optional().describe('The work item it is working, if there is one.'),
+            model: z.string().min(1).optional().describe('Exact model for this child. Copy the user\'s applicable value verbatim, including aliases; never expand or normalize it. Otherwise choose for the task. Omit for the harness or machine default, never parent inheritance.'),
+            effort: z.string().min(1).optional().describe('Exact effort for this child. Honor the user\'s applicable wish; otherwise choose independently. Passed unchanged to the harness.'),
             work_name: z.string().optional().describe(`A few words, ${WORK_NAME_WORDS} at most, naming the WORK this conversation is doing, such `
                 + 'as "Fix the sign-out checklist bug". Pass it when the conversation has NO work item '
                 + 'attached: the conversation is called this from now on, and the branch the work goes on is '
@@ -2894,7 +2905,7 @@ const TOOLS = [
                 + 'attached, because that item is already the name.'),
         },
         handler: async (caller, args) => {
-            const { codebase_id, responsibility, boundary, work_item_id, work_name } = args;
+            const { codebase_id, responsibility, boundary, work_item_id, work_name, model, effort } = args;
             if (caller.level === 2 && !codebase_id) {
                 throw new Error('A worker must be attached to a registered project codebase.');
             }
@@ -2957,7 +2968,7 @@ const TOOLS = [
             const attachments = attached.map(attachmentLine);
             const { runId } = await caller.dispatch(caller.runId, workBrief(childLevel, responsibility, boundary, work_item_id, attachments, codebase === null ? undefined : {
                 id: codebase.id, name: codebase.name, identity: codebase.gitRemoteUrl,
-            }), codebase, caller.processToken);
+            }), codebase, caller.processToken, { model, effort });
             /* ═══ WHERE ITS ANSWER GOES DEPENDS ON WHICH LEVEL THIS IS, AND THAT IS
                KNOWN HERE RATHER THAN GUESSED. ═══ The description above cannot say it,
                because it is registered once for both levels that hold the tool; this
@@ -3115,6 +3126,8 @@ async function invokeWorkflowTool(caller, tool, args) {
     const invoke = () => tool.handler(caller, inputs);
     if (!canonical || workflowToolAlwaysAllowed(canonical))
         return invoke();
+    if (canonical === 'require_approval')
+        validateApprovalAction(String(a.action), String(a.details));
     const attached = await loadAttachments(caller.client, caller.cardId);
     const ids = attached.filter(item => item.kind === 'work_item').map(item => item.ref_id);
     let workItemId = explicitSource;
@@ -3135,9 +3148,9 @@ async function invokeWorkflowTool(caller, tool, args) {
         throw new Error('This planning action requires an explicit tool mention in the current workflow stage. Nothing was written.');
     if (permission)
         await validateWorkflowToolTarget(caller.client, workItemId, canonical, a);
-    if (!permission || permission.approval === 'not-required')
+    if (canonical !== 'require_approval' && (!permission || permission.approval === 'not-required'))
         return invoke();
-    const fingerprint = canonicalArgsHash({ tool: tool.name, workItemId, instance: permission.id, args: inputs });
+    const fingerprint = canonicalArgsHash({ tool: tool.name, workItemId, instance: permission?.id ?? null, args: inputs });
     const category = `workflow_tool_${fingerprint}`;
     const questions = await withAskContent(caller.client, await rows(caller.client.from('panel3_asks').select(`pending_run_id, answered_at, ${ASK_CONTENT_COLUMNS}`).eq('card_id', caller.cardId), 'read', 'workflow tool approvals'));
     const previous = questions.find(question => question.category === category && question.decision_id !== null);
@@ -3151,8 +3164,8 @@ async function invokeWorkflowTool(caller, tool, args) {
     if (caller.level === 3)
         throw new Error('This workflow tool action requires user approval. Escalate the exact action to the conversation owner and stop; the owner must perform the approved call.');
     await asked(caller, {
-        question: `May I ${tool.name.replaceAll('_', ' ')}${a.title ? `: ${String(a.title).slice(0, 180)}` : ''}?`,
-        category, context: 'This use of the tool requires approval in the workflow stage.',
+        question: canonical === 'require_approval' ? `May I ${String(a.action)}?` : `May I ${tool.name.replaceAll('_', ' ')}${a.title ? `: ${String(a.title).slice(0, 180)}` : ''}?`,
+        category, context: canonical === 'require_approval' ? String(a.details) : 'This use of the tool requires approval in the workflow stage.',
         answer_mode: 'single_select', options: ['approve', 'deny'], work_item_id: workItemId,
     }, true);
     throw new Error('This workflow tool action is waiting for user approval. Nothing was written. Stop until the user answers, then retry the same call with the same arguments.');

package/dist/workflow-tool-mentions.js

@@ -1,6 +1,8 @@
+import { absolutePathToken } from './local-paths.js';
 /** Shared by the stage editor and both tool servers. The stage body remains
  * the record: each Markdown link names one invocation, never a tool-wide grant. */
 export const WORKFLOW_TOOLS = [
+    { id: 'require_approval', name: 'Require Approval', detail: 'Pause before any action, such as editing code, running migrations, or pushing commits.', alwaysAllowed: false, advanced: false },
     { id: 'create_artifact', name: 'Create Artifact', detail: 'Write a user story, plan, spec, diagram, or interactive mock.', alwaysAllowed: false, advanced: false },
     { id: 'update_artifact', name: 'Edit Artifact', detail: 'Revise an existing artifact.', alwaysAllowed: false, advanced: false },
     { id: 'ask_question', name: 'Ask Question', detail: 'Ask for feedback, a decision, or approval. Always available.', alwaysAllowed: true, advanced: false },
@@ -35,7 +37,7 @@ export function workflowToolForName(name) {
 }
 export function toolMentionText(tool, id, approval = 'required') {
     const entry = WORKFLOW_TOOLS.find(entry => entry.id === tool);
-    return `[@${entry.name}](ctrl-spc://tool/${tool}/${id}?approval=${workflowToolAlwaysAllowed(tool) ? 'not-required' : approval})`;
+    return `[@${entry.name}](ctrl-spc://tool/${tool}/${id}?approval=${tool === 'require_approval' ? 'required' : workflowToolAlwaysAllowed(tool) ? 'not-required' : approval})`;
 }
 export function toolMentions(body) {
     const mentions = [];
@@ -45,7 +47,7 @@ export function toolMentions(body) {
             continue;
         mentions.push({
             id: match[2], tool: match[1],
-            approval: workflowToolAlwaysAllowed(match[1]) ? 'not-required' : match[3],
+            approval: match[1] === 'require_approval' ? 'required' : workflowToolAlwaysAllowed(match[1]) ? 'not-required' : match[3],
             from: match.index, to: match.index + match[0].length,
         });
     }
@@ -78,6 +80,7 @@ export const WORKFLOW_TOOL_TEACHING = 'Tool mentions in workflow stage documents
     'the tool itself opens the permission question before writing anything. Do not open a separate ask_question for permission to use that tool. ' +
     'When the user approves that tool question, retry the same call with exactly the same arguments. Read tools and Ask Question never need permission. Permission does not grant access to another project or change your agent level. If an action is only available to your coordinator, escalate that action with its mention id. ' +
     'Approval to use a tool is separate from approval of its output: still ask every review question written in the stage. Present Mock and Present Wireframe open their own output review; do not ask a duplicate review question. Proposing a scope or context change never accepts it. ' +
+    'Require Approval is a separate checkpoint for ANY action, including native shell and code tools: call require_approval with the specific action and its scope BEFORE doing it, then stop until that tool returns approval. It does not execute the action or approve other actions. Do not use ask_question instead of this checkpoint. ' +
     'If your level cannot ask the user, escalate the review to the conversation owner and stop.';
 /** Agents may preserve existing settings, but cannot author their own grants. */
 export function assertAgentToolMentions(body, previous = '') {
@@ -91,3 +94,35 @@ export function assertAgentToolMentions(body, previous = '') {
         }
     }
 }
+/** Library authoring accepts compact links; the server owns occurrence IDs so
+ * agent-created mentions render exactly like ones inserted in the editor. */
+export function authorToolMentions(body) {
+    const expanded = body.replace(/\[@[^\]\n]+\]\(ctrl-spc:\/\/tool\/([a-z_]+)\?approval=(required|not-required)\)/g, (_match, name, approval) => {
+        const tool = workflowToolForName(name);
+        if (!tool)
+            throw new Error(`Unknown workflow tool: ${name}. Nothing was written.`);
+        return toolMentionText(tool, crypto.randomUUID(), approval);
+    });
+    validateToolMentions(expanded);
+    let result = expanded;
+    for (const mention of toolMentions(expanded).reverse()) {
+        result = result.slice(0, mention.from) + toolMentionText(mention.tool, crypto.randomUUID(), mention.approval) + result.slice(mention.to);
+    }
+    return result;
+}
+export const WORKFLOW_AUTHORING_TEACHING = 'When the user asks you to create a workflow, build it in the library; do not merely describe it or execute it. ' +
+    'Use ask_question for missing requirements that materially change the workflow, then continue after the answer. ' +
+    'Encode every requested tool use and permission as a Markdown mention in the stage body. ' +
+    'Use compact links: [@Create Artifact](ctrl-spc://tool/create_artifact?approval=not-required) to write a plan without asking; ' +
+    '[@Ask Question](ctrl-spc://tool/ask_question?approval=not-required) to review its output; ' +
+    'before editing code, [@Require Approval](ctrl-spc://tool/require_approval?approval=required). ' +
+    'The server assigns unique IDs and the user sees editable controls in the stage editor. ' +
+    'Set not-required only when the user permits that use. Otherwise default to required. Never convert permission to write a plan into permission to execute it. ' +
+    'Each occurrence has its own setting. Put the action and scope beside each Require Approval mention, including migrations or pushing commits. ' +
+    'Available tool IDs: ' + WORKFLOW_TOOLS.map(tool => `${tool.id} (${tool.name})`).join(', ') + '. ';
+/** Approval prose is displayed in the hosted app; keep machine-local paths local. */
+export function validateApprovalAction(action, details) {
+    if (absolutePathToken(action) || absolutePathToken(details)) {
+        throw new Error('Use repo-relative or scratch-relative paths in the approval action and scope, never absolute local paths. No approval was requested.');
+    }
+}

package/dist/workflows.js

@@ -1,7 +1,7 @@
 import { absolutePathToken } from './local-paths.js';
 import { listSteps } from './steps.js';
-import { assertAgentToolMentions, toolMentions, validateToolMentions } from './workflow-tool-mentions.js';
-export { WORKFLOW_TOOL_TEACHING, assertAgentToolMentions } from './workflow-tool-mentions.js';
+import { assertAgentToolMentions, authorToolMentions, toolMentions, validateToolMentions } from './workflow-tool-mentions.js';
+export { WORKFLOW_TOOL_TEACHING, WORKFLOW_AUTHORING_TEACHING, authorToolMentions, assertAgentToolMentions } from './workflow-tool-mentions.js';
 /** Resolve permission from the current stage's saved document, never agent
  * prose or a supplied boolean. Both harnesses use the same stage resolver. */
 export async function workflowToolPermission(client, workItemId, tool, instance) {
@@ -140,7 +140,7 @@ export async function readWorkflow(client, workflowId) {
 export async function buildWorkflow(client, input) {
     const prose = [['name', input.name], ['description', input.description]];
     input.stages.forEach((stage, i) => {
-        assertAgentToolMentions(stage.body);
+        stage.body = authorToolMentions(stage.body);
         prose.push([`stage ${i + 1} name`, stage.name], [`stage ${i + 1} description`, stage.description], [`stage ${i + 1} body`, stage.body]);
     });
     input.exits.forEach((exit, i) => prose.push([`exit ${i + 1} condition`, exit.condition]));
@@ -253,7 +253,7 @@ export async function editWorkflow(client, input) {
     input.stages.forEach((stage, i) => {
         if ('stage_id' in stage)
             return;
-        assertAgentToolMentions(stage.body);
+        stage.body = authorToolMentions(stage.body);
         prose.push([`stage ${i + 1} name`, stage.name], [`stage ${i + 1} description`, stage.description], [`stage ${i + 1} body`, stage.body]);
     });
     input.exits.forEach((exit, i) => prose.push([`exit ${i + 1} condition`, exit.condition]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"