@ctrl-spc/cs 0.7.6 → 0.7.8

package/dist/panel3/prompt.js

@@ -550,6 +550,23 @@ export function levelOnePrompt(cardTitle, messages, produced, attachments = [],
  * Every child it starts, and every grandchild THEY start, would be working
  * from nothing but a responsibility sentence somebody else wrote down.
  */
+export const OWNER_COMPLETION_RULES = [
+    'ASSIGNMENT STATUS — THIS OVERRIDES OLDER ENDING INSTRUCTIONS IN YOUR BRIEF.',
+    'A reply or process exit does not finish the assignment. Keep working through all remaining',
+    'required steps and checks. Status questions never cancel work already in progress.',
+    'When you yield to workers, write_report with what remains and exit; you resume with results.',
+    'When no worker is active and work remains, continue it yourself or dispatch it. If you exit',
+    'without declaring completion, the product starts you again to carry on.',
+    'Only when the latest user assignment is fulfilled, call write_report with work_complete=true',
+    'and a report explaining what fulfilled it. Check all required steps and verification first.',
+    'Then give the final answer and exit. Do not declare completion for an interim status answer.',
+    'A failed or skipped required step is unfinished work, even if all workers have returned.',
+    'Resolve it or ask for the real required intervention; never convert it into a completion caveat.',
+    'If a required user action prevents progress, use ask_question and stop. It must name the actual',
+    'approval, credential or manual action needed. Never ask just because no agent is running.',
+    'A handover explicitly requested by the person may finish that request without finishing a',
+    'feature. Say exactly what was handed over and do not claim the unfinished feature is done.',
+].join('\n');
 export function workBrief(level, responsibility, boundary, workItemId, attachments = [], codebase) {
     /* ═══ ONLY WHEN A WORKFLOW IS ACTUALLY ON THE CARD. ═══ An owner is not
        instructed about a process that is not there, which is the rule
@@ -562,6 +579,7 @@ export function workBrief(level, responsibility, boundary, workItemId, attachmen
             ? [
                 'You see one thing a person asked for through to done. Keep the whole picture and stay',
                 'available to the person while the work moves.',
+                OWNER_COMPLETION_RULES,
                 '',
                 /* ═══ THE FIRST THING, EVERY TIME, AND IT IS NOT THE REPLY. ═══ Nothing
                    an owner writes reaches the person until its process exits, and a turn
@@ -836,7 +854,7 @@ export const landingOutcomeContext = (landing) => {
             'They chose neither of the two answers, so nothing was merged and the work is still on '
                 + `${landing.branch ?? 'its branch'}.`,
             'Read what they actually wrote and answer it. If they still want the work put back, offer the',
-            'ending again with `offer_ending` rather than replying: a reply finishes the card, and an',
+            'ending again with `offer_ending` rather than declaring completion: an',
             'offer leaves it with them.',
         ];
     }
@@ -915,6 +933,7 @@ landing = null) {
     });
     return [
         'YOU OWN THIS CTRL+SPC CONVERSATION.',
+        OWNER_COMPLETION_RULES,
         'You are this conversation\'s one owner, started for one serialized activation. Speak directly to the',
         'person as CTRL+SPC. The launcher is finished and cannot answer or receive an escalation.',
         '',

package/dist/panel3/run.js

@@ -133,7 +133,7 @@
 // `import type` loses its v3 header in the published `dist/`.
 import { out, returned, signedInClient } from './client.js';
 import { readableWriteError } from '../firewall.js';
-import { answerPrompt, escalationPrompt, levelOnePrompt, ownerActivationPrompt, readBackPrompt, landingOutcomeContext, presentedArtifactAnswerContext, resumePrompt, retryPrompt, standingRules, whatWasAttached, workingRules, } from './prompt.js';
+import { answerPrompt, escalationPrompt, levelOnePrompt, ownerActivationPrompt, readBackPrompt, landingOutcomeContext, presentedArtifactAnswerContext, resumePrompt, retryPrompt, standingRules, whatWasAttached, workingRules, OWNER_COMPLETION_RULES, } from './prompt.js';
 import { ASK_CONTENT_COLUMNS, attachmentLine, gitRulesFor, loadAttachments, loadOutputNames, outputOf, recordBaseProtection, standingRulesFor, withAskContent, } from './show.js';
 import { forgetSecrets, redactSecrets } from './secrets.js';
 import { sayListening, stopListening } from './presence.js';
@@ -1950,8 +1950,17 @@ export function ownerContinuationPrompt(brief, report, events, children, deliver
     const messages = events.filter((event) => event.kind === 'user' && event.needsReply);
     return [
         'CONTINUE THE CTRL+SPC CONVERSATION YOU ALREADY OWN.',
+        OWNER_COMPLETION_RULES,
         'Use only the new facts below as the new turn. Keep coordinating the whole card and speak as CTRL+SPC.',
         '',
+        ...(messages.length === 0 && delivered === null ? [
+            'WHY YOU WERE STARTED AGAIN',
+            'The assignment is still open. Your previous final reply did not record completion.',
+            'Do not repeat a completion reply by itself. If the assignment is fulfilled, call',
+            'write_report with work_complete=true NOW, then give the final answer. Otherwise do the',
+            'remaining work or resolve the new worker results below. No new user message is needed.',
+            '',
+        ] : []),
         'NEW USER MESSAGES',
         ...(messages.length === 0
             ? ['None.']
@@ -2425,15 +2434,17 @@ export async function reconcileOwnerSessions(client, machineId, _machineHarness,
 async function killStopped(client, machineId) {
     const stopped = await returned(client
         .from('panel3_runs')
-        .select('id, card_id, pid, started_at, resumed_at')
+        .select('id, card_id, pid, state, started_at, resumed_at')
         .eq('machine_id', machineId)
-        .in('state', ENDED_BY_THE_PERSON)
+        .in('state', [...ENDED_BY_THE_PERSON, 'finished', 'failed'])
         .not('pid', 'is', null), 'read', 'the runs on this machine that are not coming back');
     if (stopped.length === 0)
         return;
     const booted = bootedAt();
     for (const run of stopped) {
         if (runProcessIsAlive(run, booted)) {
+            if (!ENDED_BY_THE_PERSON.includes(run.state))
+                continue;
             try {
                 process.kill(run.pid);
                 out(`stopped  run ${run.id}  card ${run.card_id}  killed pid ${run.pid}`);
@@ -2455,11 +2466,11 @@ async function killStopped(client, machineId) {
             await returned(client
                 .from('panel3_runs')
                 .update({ pid: null })
-                // STILL NOT COMING BACK. Nothing starts either of these states, so
-                // this cannot lose a race, and saying so in the statement is what
-                // keeps that true if something one day does.
+                // A finished owner may activate again between this read and write.
+                // Only acknowledge the exact process whose exit was observed.
                 .eq('id', run.id)
-                .in('state', ENDED_BY_THE_PERSON)
+                .eq('pid', run.pid)
+                .in('state', [...ENDED_BY_THE_PERSON, 'finished', 'failed'])
                 .select('id'), 'clear the process id of', `run ${run.id}`);
         }
         catch (error) {
@@ -2562,7 +2573,9 @@ async function recoverStranded(client, tools, machineId, mine, hold) {
                     await writeAnswer(client, run.id, run.card_id, null, run.process_token ?? undefined);
                 }
                 else {
-                    const resumed = await activateOwner(client, tools, machineId, run.id, run.process_token, run.pid);
+                    // This process belonged to a previous daemon. Use the fenced recovery
+                    // claim, not a failed-attempt retry whose budget may already be spent.
+                    const resumed = await activateOwner(client, tools, machineId, run.id, run.process_token, null);
                     if (resumed)
                         hold(run.id, resumed.settled);
                 }
@@ -2914,7 +2927,7 @@ export async function sweepFinishedWorktrees(client) {
     const live = new Set((await returned(client.from('panel3_runs')
         .select('card_id')
         .in('card_id', cards)
-        .is('ended_at', null), 'read', 'which of those cards still have an agent going')).map((row) => row.card_id));
+        .or('ended_at.is.null,pid.not.is.null'), 'read', 'which of those cards still have an agent going')).map((row) => row.card_id));
     const touched = new Set();
     for (const one of held) {
         const cardIds = cardOfFolder.get(one.folder) ?? [];

package/dist/panel3/tools.js

@@ -112,6 +112,10 @@
 // The runtime import comes FIRST, deliberately: `tsc` elides a type-only import
 // and takes the leading comment with it, so a file whose first statement is
 // `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 { captureUrlScreenshot } from '../browser.js';
 import { createServer as createHttpServer } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -126,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 } from '../workflows.js';
+import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage, workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_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
@@ -738,7 +742,173 @@ async function stageForWriting(caller, stageId, consequence) {
     await carriedWorkItem(caller, stage.workItemId, consequence);
     return stage;
 }
+function productResult(result) {
+    const text = result.content.filter((item) => Boolean(item && typeof item === 'object' && 'text' in item)).map(item => item.text).join('\n');
+    if (result.isError)
+        throw new Error(text);
+    return text;
+}
 const TOOLS = [
+    {
+        name: 'get_document', levels: ALL,
+        description: 'Read a project context document or instruction in full by id. Read-only.',
+        input: { id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await getDocumentHandler(caller.client, args)),
+    },
+    {
+        name: 'add_comment', levels: ALL,
+        description: 'Leave a durable note or handover on a work item. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), body: z.string().min(1) },
+        handler: async (caller, args) => {
+            const { work_item_id, body } = args;
+            await carriedWorkItem(caller, work_item_id, 'a comment cannot be added to it');
+            const comment = await only(caller.client.from('comments')
+                .insert({ task_id: work_item_id, body, author_id: caller.userId }).select('id'), 'add', 'the comment');
+            return `Added comment ${comment.id}.`;
+        },
+    },
+    {
+        name: 'create_product_idea', levels: [1],
+        description: 'Capture a potential improvement without committing to implementation. First read existing work items, including Product Ideas, and the product to avoid duplicates. Only a human can promote an idea. ' + FIREWALL_WRITING_RULE,
+        input: { project_id: z.string().uuid(), title: z.string().min(1), description: z.string().optional() },
+        handler: async (caller, args) => {
+            const a = args;
+            const id = await returned(caller.client.rpc('create_product_idea', {
+                p_project: a.project_id, p_name: a.title, p_description: a.description ?? '', p_owner: caller.userId,
+            }), 'create', 'the product idea');
+            if (!id)
+                throw new Error('The product idea was not created.');
+            await receipt(caller, 'work_item', id, a.title);
+            return `Created Product Idea ${a.title}, id ${id}. No work has started. Only a human can promote it.`;
+        },
+    },
+    {
+        name: 'place_work_item', levels: [1],
+        description: 'Move a work item into an epic or sprint in its project. Null removes placement. Its status stays the same.',
+        input: { work_item_id: z.string().uuid(), epic_id: z.string().uuid().nullable().optional(),
+            sprint_id: z.string().uuid().nullable().optional(), before_work_item_id: z.string().uuid().optional() },
+        handler: async (caller, args) => productResult(await placeWorkItemHandler(caller.client, args)),
+    },
+    {
+        name: 'reorder_backlog', levels: [1],
+        description: 'Move one backlog work item before another, or to the bottom. Read the current order first and explain the reason.',
+        input: { project_id: z.string().uuid(), task_id: z.string().uuid(), before_task_id: z.string().uuid().optional(), reason: z.string().min(1) },
+        handler: async (caller, args) => {
+            const a = args;
+            const items = await rows(caller.client.from('tasks').select('id, revision')
+                .eq('project_id', a.project_id).eq('status', 'backlog').is('archived_at', null).eq('is_idea', false).order('position').order('created_at').order('id'), 'read', 'the backlog');
+            const moving = items.find(item => item.id === a.task_id);
+            if (!moving || (a.before_task_id && !items.some(item => item.id === a.before_task_id)))
+                throw new Error('Both items must be live backlog work in this project. Nothing was moved.');
+            if (a.task_id === a.before_task_id)
+                throw new Error('An item cannot be placed before itself. Nothing was moved.');
+            await returned(caller.client.rpc('save_task_if_current', { p_task_id: a.task_id,
+                p_expected_revision: moving.revision, p_changes: {}, p_tag_ids: null, p_reorder: true,
+                p_before_task_id: a.before_task_id ?? null }), 'reorder', 'the backlog');
+            return `Reordered the backlog: ${a.reason}`;
+        },
+    },
+    {
+        name: 'propose_project_context', levels: [2, 3],
+        description: 'Submit repository guidance for human review in Project settings. Pending proposals for this scan are replaced; accepted context is never changed. Name the scanned codebase and use repository-relative source paths. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), codebase: z.string().min(1), proposals: z.array(z.object({
+                title: z.string().min(1), type: z.enum(PROJECT_DOCUMENT_TYPES), content: z.string().min(1),
+                source_path: z.string().min(1), reason: z.string().min(1), scope: z.enum(['project', 'codebase']),
+            })) },
+        handler: async (caller, args) => {
+            const { work_item_id, ...a } = args;
+            await carriedWorkItem(caller, work_item_id, 'project context cannot be proposed for it');
+            return productResult(await proposeProjectContextHandler(caller.client, null, { ...a, task_id: work_item_id }));
+        },
+    },
+    {
+        name: 'record_context_exploration', levels: ALL,
+        description: 'Save explored context and research in the work item’s Findings artifact. Repeated calls update the same artifact. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), content: z.string().min(1) },
+        handler: async (caller, args) => {
+            const { work_item_id, content } = args;
+            await carriedWorkItem(caller, work_item_id, 'findings cannot be recorded on it');
+            const existing = await rows(caller.client.from('artifacts').select('id')
+                .eq('task_id', work_item_id).eq('purpose_key', 'workflow_findings').is('deleted_at', null), 'read', 'existing findings');
+            if (existing.length > 1)
+                throw new Error('More than one Findings artifact exists. Choose the artifact to edit explicitly.');
+            const artifact = existing[0]
+                ? await only(caller.client.from('artifacts').update({ content, updated_by: caller.userId })
+                    .eq('id', existing[0].id).select('id'), 'update', 'the findings')
+                : await only(caller.client.from('artifacts').insert({ task_id: work_item_id, title: 'Findings',
+                    type: 'analysis', format: 'md', content, purpose_key: 'workflow_findings', created_by: caller.userId }).select('id'), 'record', 'the findings');
+            await receiptOnce(caller, 'artifact', artifact.id, 'Findings');
+            return `Recorded Findings artifact ${artifact.id}.`;
+        },
+    },
+    {
+        name: 'resolve_feedback', levels: ALL,
+        description: 'Mark specified feedback rounds addressed after revising their artifact. Supply the new revision. This does not approve the artifact.',
+        input: { work_item_id: z.string().uuid(), feedback_ids: z.array(z.string().uuid()).min(1), revision: z.number().int().positive() },
+        handler: async (caller, args) => {
+            const a = args;
+            await carriedWorkItem(caller, a.work_item_id, 'its feedback cannot be resolved');
+            await validateWorkflowToolTarget(caller.client, a.work_item_id, 'resolve_feedback', a);
+            return productResult(await resolveFeedbackHandler(caller.client, { taskId: a.work_item_id }, a));
+        },
+    },
+    ...['present_mocks', 'present_wireframes'].map((name) => ({
+        name, levels: [2],
+        description: 'Create a self-contained HTML design and open its artifact review. Use html, with scripts inline for interactive mocks. Only the active conversation owner may present for review. Revise the same artifact for changes; do not present it again. Stop after opening review. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), title: z.string().min(1), html: z.string().min(1),
+            ...(name === 'present_wireframes' ? { kind: z.enum(['ui', 'architecture']) } : {}) },
+        handler: async (caller, args) => {
+            if (!caller.isOwner || !caller.processToken)
+                throw new Error('Escalate this design presentation to the current conversation owner. Nothing was written.');
+            const a = args;
+            await carriedWorkItem(caller, a.work_item_id, 'a design cannot be presented for it');
+            const mock = name === 'present_mocks';
+            const result = await presentDesign(caller.client, caller.userId, a.work_item_id, a, {
+                tool: name, unit: mock ? 'mock' : 'diagram', htmlSpec: 'self-contained HTML',
+                artifactType: mock ? 'mock' : a.kind === 'architecture' ? 'diagram' : 'wireframe',
+                artifactNoun: mock ? 'mock' : 'wireframe',
+            }, async (kind, id) => {
+                if (kind === 'artifact')
+                    await receiptOnce(caller, 'artifact', id, a.title);
+            }, async (review) => {
+                await asked(caller, { work_item_id: a.work_item_id, related_artifact_id: review.artifactId,
+                    category: 'wireframe_review', context: review.title, question: review.question,
+                    answer_mode: 'single_select', options: review.options }, true);
+                const decision = await only(caller.client.from('decisions').select('id')
+                    .eq('related_artifact_id', review.artifactId).eq('category', 'wireframe_review'), 'read', 'the design review');
+                return decision.id;
+            });
+            const text = productResult(result);
+            return text + '\nStop now. The conversation resumes when the user answers. Do not poll.';
+        },
+    })),
+    {
+        name: 'propose_scope_change', levels: [2],
+        description: 'Present a proposed change to approved scope, with the user request, classification, and quoted evidence, as an artifact for review. Only the conversation owner may open its approval. Stop; permission to propose does not approve expanded work. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), request: z.string().min(1),
+            classification: z.enum(['completion_gap', 'clarification', 'expansion', 'replacement']),
+            evidence: z.string().min(1), measured_against_version: z.number().int().positive() },
+        handler: async (caller, args) => {
+            if (!caller.isOwner || !caller.processToken)
+                throw new Error('Escalate the scope proposal to the current conversation owner. Nothing was written.');
+            const a = args;
+            await carriedWorkItem(caller, a.work_item_id, 'a scope change cannot be proposed for it');
+            const artifact = await only(caller.client.from('artifacts').insert({ task_id: a.work_item_id,
+                title: 'Scope change proposal', type: 'spec', format: 'md', created_by: caller.userId,
+                content: `# Proposed scope change\n\n${a.request}\n\nClassification: ${a.classification}\n\nCompared with approved scope version ${a.measured_against_version}:\n\n${a.evidence}\n\nProposed only. Do not implement until the user approves.`,
+            }).select('id'), 'create', 'the scope change proposal');
+            await receipt(caller, 'artifact', artifact.id, 'Scope change proposal');
+            try {
+                return await asked(caller, { work_item_id: a.work_item_id, related_artifact_id: artifact.id,
+                    category: 'scope_change', context: 'Review the proposed change before any expanded work begins.',
+                    question: 'Approve this scope change, or request changes?', answer_mode: 'single_select',
+                    options: ['approve', 'request changes'] }, true);
+            }
+            catch (error) {
+                throw new Error(`Proposal artifact ${artifact.id} was created, but review did not open: ${errorMessage(error)}. Do not create it again. Use ask_question to request approval of this artifact; do not implement it.`);
+            }
+        },
+    },
     // ── Read the record ──────────────────────────────────────────────────────
     {
         name: 'list_projects',
@@ -789,6 +959,9 @@ const TOOLS = [
                 .eq('id', work_item_id), 'read', `work item ${work_item_id}`);
             const artifacts = await rows(client.from('artifacts').select('id, type, title, created_at').eq('task_id', work_item_id)
                 .is('deleted_at', null).order('created_at'), 'read', `the artifacts on work item ${work_item_id}`);
+            const feedback = await rows(client.from('artifact_feedback').select('*').eq('task_id', work_item_id).order('created_at'), 'read', 'the artifact feedback');
+            const decisions = await rows(client.from('decisions').select('id, category, question, state, selected_options, answer_note, related_artifact_id').eq('task_id', work_item_id).order('asked_at'), 'read', 'the work item decisions');
+            const comments = await rows(client.from('comments').select('id, body, created_at').eq('task_id', work_item_id).order('created_at'), 'read', 'the work item comments');
             return [
                 `${item.name}`,
                 `id        ${item.id}`,
@@ -801,6 +974,7 @@ const TOOLS = [
                 'DESCRIPTION',
                 item.description.trim() === '' ? '(empty)' : item.description,
                 '',
+                'DECISIONS', JSON.stringify(decisions), 'FEEDBACK', JSON.stringify(feedback), 'COMMENTS', JSON.stringify(comments),
                 `ARTIFACTS  ${artifacts.length}`,
                 listed(artifacts.map((a) => line(a.id, a.type, a.title ?? '(untitled)')), 'none'),
             ].join('\n');
@@ -1879,12 +2053,12 @@ const TOOLS = [
     {
         name: 'create_sprint',
         levels: [1],
-        description: 'Create a sprint in a project. Both dates are required and the start must not be after the end.',
+        description: 'Create an ordered batch of work in a project. Dates are optional; use them only for a stated calendar constraint.',
         input: {
             project_id: z.string(),
             name: z.string().min(1),
-            start_date: z.string().describe('YYYY-MM-DD'),
-            end_date: z.string().describe('YYYY-MM-DD'),
+            start_date: z.string().optional().describe('YYYY-MM-DD'),
+            end_date: z.string().optional().describe('YYYY-MM-DD'),
         },
         handler: async (caller, args) => {
             const { project_id, name, start_date, end_date } = args;
@@ -2332,6 +2506,26 @@ const TOOLS = [
     // because a conversation is one person's. An artifact belongs to a work item
     // the whole org can see, so it goes where every other artifact goes. Two
     // visibility models, two buckets, both deliberate.
+    {
+        name: 'attach_screenshot',
+        levels: [2, 3],
+        description: 'Capture a web page and keep the screenshot as an artifact on this work item. Pass url; the tool takes the picture. ' + WORKFLOW_TOOL_TEACHING,
+        input: {
+            url: z.string().url(), work_item_id: z.string().uuid(), title: z.string().min(1).max(200),
+            platform: z.literal('web'), target: z.string().min(1).max(200),
+        },
+        handler: async (caller, args) => {
+            const a = args;
+            await carriedWorkItem(caller, a.work_item_id, 'a screenshot cannot be attached to it');
+            const capture = await captureUrlScreenshot(a.url);
+            try {
+                return await toolNamed('attach_image_artifact').handler(caller, { ...a, path: capture.path });
+            }
+            finally {
+                await capture.cleanup();
+            }
+        },
+    },
     {
         name: 'attach_image_artifact',
         levels: [2, 3],
@@ -2481,11 +2675,21 @@ const TOOLS = [
         description: 'Write down what is true NOW: what you have done, what you decided and why, and what is still '
             + 'open. It REPLACES your last report rather than adding to it, and it is what you are handed if '
             + 'you are respawned, so write it as the thing you would want to read to carry on. Write it as '
-            + 'you go, not only at the end. '
+            + 'you go, not only at the end. The conversation owner MUST set work_complete=true only when '
+            + 'the latest user assignment is fulfilled, including its required steps and checks. A status '
+            + 'reply is not completion. This records intent; Done waits for all agents to exit. '
             + FIREWALL_WRITING_RULE,
-        input: { report: z.string().min(1) },
-        handler: async ({ client, runId, processToken }, args) => {
-            const { report } = args;
+        input: { report: z.string().min(1), work_complete: z.boolean().optional() },
+        handler: async ({ client, runId, processToken, isOwner }, args) => {
+            const { report, work_complete } = args;
+            if (work_complete) {
+                if (!isOwner || processToken === undefined)
+                    throw new Error('Only the conversation owner can declare the assignment complete.');
+                await whileRunning(client.rpc('panel3_request_completion', {
+                    p_run_id: runId, p_process_token: processToken, p_summary: report,
+                }), runId, 'declare completion of');
+                return 'Completion recorded. Give your final answer and exit. Done waits until all processes have exited.';
+            }
             await whileRunning(processToken === undefined
                 ? client.from('panel3_runs').update({ report }).eq('id', runId)
                     .in('state', STILL_WRITING).is('ended_at', null).select('id')
@@ -2590,7 +2794,11 @@ const TOOLS = [
                 + 'or sends back for changes. Only the current Level 2 conversation owner may name it, and '
                 + 'its current process token is required. Leave it out for every ordinary question.'),
         },
-        handler: async (caller, args) => asked(caller, args, true),
+        handler: async (caller, args) => {
+            if (String(args.category).startsWith('workflow_tool_'))
+                throw new Error('That category is reserved for tool permissions. The tool opens its own approval question; do not create one yourself.');
+            return asked(caller, args, true);
+        },
     },
     {
         name: 'escalate',
@@ -2895,9 +3103,60 @@ async function receiptOnce(caller, kind, refId, label) {
  *  the same reason `cs show` exists: a rule nobody can print is a rule nobody
  *  can check. */
 export function toolNamesForLevel(level, isOwner = false) {
-    return TOOLS.filter((t) => t.levels.includes(level) && !(isOwner && t.name === 'escalate'))
+    return TOOLS.filter((t) => toolAvailable(t, level, isOwner))
         .map((t) => t.name);
 }
+/** The stage owns the setting; the existing question path owns permission.
+ * An exact-call fingerprint prevents approval of one edit authorizing another. */
+async function invokeWorkflowTool(caller, tool, args) {
+    const canonical = workflowToolForName(tool.name);
+    const a = args;
+    const { workflow_tool_instance: instance, workflow_work_item_id: explicitSource, ...inputs } = a;
+    const invoke = () => tool.handler(caller, inputs);
+    if (!canonical || workflowToolAlwaysAllowed(canonical))
+        return invoke();
+    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;
+    if (!workItemId && ids.length === 1)
+        workItemId = ids[0];
+    if (!workItemId && ids.includes(String(a.work_item_id ?? a.task_id)))
+        workItemId = String(a.work_item_id ?? a.task_id);
+    if (!workItemId && tool.name === 'create_step') {
+        const stage = await stageById(caller.client, String(a.stage_id));
+        workItemId = stage?.workItemId ?? undefined;
+    }
+    if (!workItemId && ids.length > 1)
+        throw new Error('Name workflow_work_item_id from the card attachments so the correct stage controls this action.');
+    if (workItemId)
+        await carriedWorkItem(caller, workItemId, 'its workflow permissions cannot be used', attached);
+    const permission = await workflowToolPermission(caller.client, workItemId ?? null, canonical, instance);
+    if (!tool.levels.includes(caller.level) && !permission)
+        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')
+        return invoke();
+    const fingerprint = canonicalArgsHash({ tool: tool.name, workItemId, instance: permission.id, 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);
+    if (previous?.answered_at) {
+        if (previous.selected_options?.length === 1 && previous.selected_options[0] === 'approve')
+            return invoke();
+        throw new Error('The user did not approve this workflow tool action. Nothing was written.');
+    }
+    if (previous)
+        throw new Error('This workflow tool action is waiting for user approval. Stop until the user answers.');
+    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.',
+        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.');
+}
 /**
  * One tool's handler, by name. Exported for the same reason `toolNamesForLevel`
  * is: a test that only calls `workBrief` with a hand-built array proves the
@@ -2917,6 +3176,11 @@ export function toolShape(name) {
     const { description, input } = toolNamed(name);
     return { description, input };
 }
+function toolAvailable(tool, level, isOwner) {
+    if (isOwner && tool.name === 'escalate')
+        return false;
+    return tool.levels.includes(level) || (level === 2 && isOwner && workflowToolForName(tool.name) !== undefined);
+}
 function toolNamed(name) {
     const tool = TOOLS.find((t) => t.name === name);
     if (!tool)
@@ -2938,9 +3202,14 @@ function buildServer(caller) {
             + 'hold rather than one that is missing.',
     });
     for (const tool of TOOLS) {
-        if (!tool.levels.includes(caller.level) || (caller.isOwner && tool.name === 'escalate'))
+        if (!toolAvailable(tool, caller.level, caller.isOwner))
             continue;
-        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.input }, (async (args) => {
+        server.registerTool(tool.name, { description: tool.description + ' ' + WORKFLOW_TOOL_TEACHING, inputSchema: { ...tool.input,
+                ...(workflowToolForName(tool.name) ? {
+                    workflow_tool_instance: z.string().uuid().optional(),
+                    workflow_work_item_id: z.string().uuid().optional().describe('The attached work item whose workflow stage instructs this action. Needed when the card carries multiple work items.'),
+                } : {}),
+            } }, (async (args) => {
             try {
                 /* ═══ NOTHING THIS RUN READ GOES BACK OUT THROUGH A TOOL. ═══ Every
                    argument of every tool, redacted before the handler sees it: see
@@ -2949,7 +3218,7 @@ function buildServer(caller) {
                    on; `writeAnswer` in run.ts is the other. It is identity for the
                    runs that read no credential, which is nearly all of them. */
                 const safe = redactArgs(secretScope(caller), args);
-                return { content: [{ type: 'text', text: await tool.handler(caller, safe) }] };
+                return { content: [{ type: 'text', text: await invokeWorkflowTool(caller, tool, safe) }] };
             }
             catch (error) {
                 /* ═══ A FAILURE REACHES THE AGENT AS A FAILURE. ═══ Constraint 7, at