@ctrl-spc/cs 0.7.7 → 0.7.8

package/dist/mcp.js

@@ -1,4 +1,7 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { presentDesign } from './design-review.js';
+import { must, errorMessage, textResult, errorResult, canonicalArgsHash, TASK_PLACEMENT, placeWorkItemHandler, UUID_RE, resolveFeedbackHandler, PROJECT_DOCUMENT_TYPES, countCharacters, resolveContextProject, resolveContextCodebase, getDocumentHandler, PROPOSAL_SCOPES, MAX_PROPOSALS, MAX_PROPOSAL_BATCH_CHARS, proposeProjectContextHandler } from './product-tools.js';
+export { canonicalArgsHash, placeWorkItemHandler, resolveFeedbackHandler, getDocumentHandler, proposeProjectContextHandler } from './product-tools.js';
+import { randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { chmodSync, existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -11,14 +14,16 @@ 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 { TOOLS_SERVER_PORT, SESSION_TTL_MS } from './env.js';
 import { agentPath } from './agents.js';
 import { mcpToken, readMcpToken, readSession } from './config.js';
-import { readableWriteError, FIREWALL_WRITING_RULE } from './firewall.js';
+import { FIREWALL_WRITING_RULE } from './firewall.js';
 /* The path rule itself, moved out so `workflows.ts` can ask the same question
    before it builds a workflow. `refuseAbsolutePaths` below is still v2's own
    wrapper: it is the one that answers in a `CallToolResult`. */
-import { ABSOLUTE_PATH_RE, absolutePathToken } from './local-paths.js';
+import { absolutePathToken } from './local-paths.js';
 import { readPngScreenshot, screenshotArtifactId, screenshotRequestId, } from './screenshots.js';
 /* 18c Slice 7 correction: the product captures the PNG itself, because a
    spawned worker has no reachable way to run a capture command. The whole
@@ -239,26 +244,6 @@ function validateGrounding(value) {
     }
     return { ok: true, value: manifest };
 }
-/** Awaits a Supabase call and throws on error — callers catch once, at the
- *  handler boundary (mirrors v1's `must`). */
-async function must(query) {
-    const { data, error } = await query;
-    if (error)
-        throw new Error(readableWriteError(error.message));
-    return data;
-}
-/** The message of a thrown value, WITHOUT assuming it is an `Error`. `(err as
- *  Error).message` is a lie the type system permits: a thrown string, a
- *  `DOMException` from an aborted fetch, or a rejected non-Error makes it a
- *  `TypeError` raised from inside the very catch block that exists to contain
- *  failures — which escapes the catch and defeats it. */
-const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
-function textResult(payload) {
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
-}
-function errorResult(message) {
-    return { content: [{ type: 'text', text: message }], isError: true };
-}
 /** Columns v1 returns for a freshly created artifact (cli/src/mcp.ts:2239) —
  *  reused verbatim so get_task and create_artifact hand back the same shape, plus
  *  `revision` so the agent has the optimistic-concurrency token update_artifact
@@ -270,12 +255,6 @@ const ARTIFACT_COLUMNS = 'id,task_id,type,format,title,purpose_key,system_kind,c
 const DECISION_COLUMNS = 'id,task_id,state,category,context,question,answer_mode,options,answer,selected_options,answer_note,question_comment_id,related_artifact_id,asked_by,asked_by_agent_run_id,asked_at,decided_by,decided_at';
 /** Tags come from the same `task_tags`→`tags` join the web reads. */
 const TASK_TAGS = 'task_tags:task_tags!task_tags_task_id_fkey(tag:tags!task_tags_tag_id_fkey(id,name))';
-/* !Cleanup PHASE 5 (I13) — WHERE EACH ITEM SITS. `epics` and `sprints` are
-   to-one relations off real FKs (`tasks.epic_id`, `tasks.sprint_id`), so
-   PostgREST embeds them, but it returns an ARRAY shape whenever it cannot prove
-   the cardinality — the same hazard `readAttachedItems` handles for `projects`.
-   Both shapes are handled below rather than assumed. */
-const TASK_PLACEMENT = 'epic:epics(id,name), sprint:sprints(id,name)';
 /** The one embedded row, whichever shape PostgREST chose. Null stays null: an
  *  item in no epic is the common case, not a missing value. */
 function oneOf(embedded) {
@@ -2477,83 +2456,6 @@ export async function updateStructureHandler(client, args) {
         return errorResult(`update_structure failed: ${errorMessage(err)}`);
     }
 }
-/**
- * MOVE A WORK ITEM BETWEEN EPICS AND SPRINTS (I14) — the thing nothing could do.
- *
- * THROUGH `save_task_if_current`, THE SHIPPED PATH. It is the same RPC the
- * board's own epic picker calls, so an agent's move is identical to a user's:
- * the same allowed-field whitelist, the same compare-and-swap on `revision`, the
- * same project-membership validation for the epic and sprint. Writing the
- * columns directly would bypass all of it.
- *
- * THE REVISION IS READ HERE rather than asked of the agent. An agent has no way
- * to know a revision it was never given, and requiring one would make every move
- * a two-call dance whose first call this function can make correctly. The
- * conflict case is still real and still reported: a peer editing between the
- * read and the write loses the swap, and the agent is told to retry.
- *
- * DETERMINISTIC POSITION, which the Gherkin asks for by name. `p_reorder`
- * renormalises the destination's positions to integers, so "after the move, this
- * item is where you put it" is true rather than approximately true — and
- * `before_work_item_id` names the neighbour to land in front of.
- */
-export async function placeWorkItemHandler(client, args) {
-    try {
-        const id = typeof args.work_item_id === 'string' ? args.work_item_id.trim() : '';
-        if (!id || !UUID_RE.test(id)) {
-            return errorResult(`place_work_item: "${id}" is not a work item id. Call list_tasks to see them. Nothing was changed.`);
-        }
-        if (args.epic_id === undefined && args.sprint_id === undefined) {
-            return errorResult('place_work_item: pass epic_id, sprint_id, or both — there is nothing to place. Pass null to ' +
-                'take it out of one. Nothing was changed.');
-        }
-        const task = await must(client.from('tasks').select('id, revision, name').eq('id', id).maybeSingle());
-        if (!task) {
-            return errorResult(`place_work_item: no work item found for id "${id}". Nothing was changed.`);
-        }
-        /* NULL MEANS "TAKE IT OUT", and the RPC spells that as an empty string:
-           `nullif(p_changes ->> 'epic_id', '')::uuid`. Sending JSON null would read
-           back as the string "null" and fail the uuid cast, so the two are
-           translated here rather than left for the agent to discover. */
-        const changes = {};
-        if (args.epic_id !== undefined)
-            changes.epic_id = args.epic_id === null ? '' : String(args.epic_id);
-        if (args.sprint_id !== undefined)
-            changes.sprint_id = args.sprint_id === null ? '' : String(args.sprint_id);
-        const { error } = await client.rpc('save_task_if_current', {
-            p_task_id: id,
-            p_expected_revision: task.revision,
-            p_changes: changes,
-            p_tag_ids: null,
-            /* Renormalise the destination order so the placement is deterministic. */
-            p_reorder: true,
-            p_before_task_id: args.before_work_item_id ?? null,
-        });
-        if (error) {
-            const message = error.message ?? '';
-            if (message.includes('edit_conflict')) {
-                return errorResult(`place_work_item: "${task.name}" was changed by someone else while this was being placed. ` +
-                    'Call list_tasks again and retry. Nothing was changed.');
-            }
-            /* The database's own words for a cross-project epic or sprint are already
-               plain ("epic must belong to the task's project"), so they are passed
-               through rather than replaced with a worse paraphrase. */
-            return errorResult(`place_work_item: ${message} Nothing was changed.`);
-        }
-        const moved = await must(client
-            .from('tasks')
-            .select(`id, name, status, ${TASK_PLACEMENT}`)
-            .eq('id', id)
-            .maybeSingle());
-        return textResult({
-            work_item: moved,
-            note: 'Placed. The board shows this immediately.',
-        });
-    }
-    catch (err) {
-        return errorResult(`place_work_item failed: ${errorMessage(err)}`);
-    }
-}
 /* ═══════════════════════ 16d SLICE 3a — THE PERMISSION GATE ═══════════════
    `.implementations/z-done-16d-inbox-and-permission/ux.md` § "3a — One tool asks
    first, and waits".
@@ -2575,33 +2477,6 @@ export async function placeWorkItemHandler(client, args) {
    THE GRANT BINDS TO THE EXACT CALL. `argsHash` is over the canonical arguments,
    so approving "create epic Onboarding" grants exactly that — not "Billing", and
    not a second Onboarding. */
-/** Stable hash of a tool's arguments.
- *
- *  KEYS ARE SORTED and the digest is over canonical JSON, because
- *  `JSON.stringify` preserves insertion order: the same call built two ways
- *  would otherwise hash differently and a legitimate re-call would find no
- *  grant. `undefined` values are dropped for the same reason — an argument the
- *  agent omitted and one it passed as undefined are the same call.
- *
- *  Nested objects are canonicalised too. A shallow sort would let
- *  `{a:{x:1,y:2}}` and `{a:{y:2,x:1}}` — the same call — miss each other. */
-export function canonicalArgsHash(args) {
-    const canonical = (value) => {
-        if (Array.isArray(value))
-            return value.map(canonical);
-        if (value && typeof value === 'object') {
-            const out = {};
-            for (const key of Object.keys(value).sort()) {
-                const v = value[key];
-                if (v !== undefined)
-                    out[key] = canonical(v);
-            }
-            return out;
-        }
-        return value;
-    };
-    return createHash('sha256').update(JSON.stringify(canonical(args))).digest('hex');
-}
 /** The sentinel category the web keys on to render a permission card, and the
  *  reserved labels the approval predicate keys on.
  *
@@ -2751,6 +2626,26 @@ async function consumeGrant(client, grantId) {
         .update({ state: 'consumed', consumed_at: new Date().toISOString() })
         .eq('id', grantId));
 }
+async function permissionForWorkflowCall(client, session, tool, args) {
+    const permission = await workflowToolPermission(client, session?.taskId ?? null, tool, args.workflow_tool_instance);
+    if (permission)
+        await validateWorkflowToolTarget(client, session.taskId, tool, args);
+    return permission;
+}
+/** Apply the current stage permission before the tool's ordinary write path. */
+export async function runWorkflowTool(client, userId, session, tool, args, write, fallback = write, connectionTodoId = null) {
+    try {
+        const permission = await permissionForWorkflowCall(client, session, tool, args);
+        if (!permission)
+            return fallback();
+        if (permission.approval === 'not-required')
+            return write();
+        return runGated(client, userId, session, tool, args, `Use ${tool.replaceAll('_', ' ')}: ${String(args.title ?? 'the workflow action')}`, write, connectionTodoId);
+    }
+    catch (error) {
+        return errorResult(error.message);
+    }
+}
 /**
  * 16d SLICE 3b — ASK, THEN WRITE, THEN SPEND: the whole gated call in one place.
  *
@@ -2923,6 +2818,20 @@ export async function runDirected(client, userId, session, tool, args, summary,
  *  the same source `report_activity` reads, which is 18c Slice 1's ruling that
  *  provenance cannot be a matter of agent judgement. */
 connectionTodoId = null) {
+    try {
+        const workflowTool = workflowToolForName(tool);
+        if (workflowTool) {
+            const permission = await permissionForWorkflowCall(client, session, workflowTool, args);
+            if (permission) {
+                if (permission.approval === 'not-required')
+                    return write();
+                return runGated(client, userId, session, tool, args, summary, write, connectionTodoId);
+            }
+        }
+    }
+    catch (error) {
+        return errorResult(errorMessage(error));
+    }
     const instruction = await readTodoInstruction(client, todoId);
     const direction = checkDirection(instruction, directedBy);
     if (direction.directed)
@@ -3085,12 +2994,11 @@ export async function reorderBacklogHandler(client, userId, session, args) {
            test passed. `\n` cannot appear in a task name. */
         const summary = `Reorder the backlog: ${after.map((i, n) => `${n + 1}. ${i.name}`).join('\n')}` +
             `\nWhy: ${args.reason.trim()}`;
-        return runGated(client, userId, session, 'reorder_backlog', args, summary, async () => {
+        const write = async () => {
             /* THE SHIPPED PRIMITIVE. `p_reorder := true` makes the RPC renumber the
                whole status column with the moved item placed before
                `p_before_task_id` — the same statement the web board runs, so agent
                and human reorders cannot disagree.
-    
                `p_expected_revision` is the moved row's CURRENT revision, read back
                here rather than taken from the agent: the agent has been waiting for
                an approval, so any revision it captured before asking is stale by
@@ -3115,7 +3023,8 @@ export async function reorderBacklogHandler(client, userId, session, args) {
                 order: applied.map((i, n) => ({ rank: n + 1, id: i.id, name: i.name })),
                 note: 'The user approved this order. Do not reorder again unless they ask.',
             });
-        });
+        };
+        return runWorkflowTool(client, userId, session, 'reorder_backlog', args, write, () => runGated(client, userId, session, 'reorder_backlog', args, summary, write));
     }
     catch (err) {
         return errorResult(`reorder_backlog failed: ${errorMessage(err)} Nothing was moved.`);
@@ -3488,330 +3397,29 @@ connectionTodoId = null) {
         return errorResult(`ask_question failed: ${err.message}`);
     }
 }
-/** Option labels the review outcome reserves (feature 09, Phase 2): 'approve'
- *  is the single-shape approval sentinel `answer_task_decision_v2`'s machinery
- *  keys on to auto-write `artifact_approvals`, and 'request changes' is the
- *  iterate outcome appended to EVERY review decision's options. A user-named
- *  option matching either (case-insensitively) would collide with the outcome
- *  derivation, so validation rejects them. */
-const RESERVED_OPTION_LABELS = ['approve', 'request changes'];
-/**
- * Present 1..N renders to the user for fullscreen review — the composition BOTH
- * review tools run (feature 09-present-wireframes-tool Phase 2, which REPLACED
- * Phase 1's free_text shape; feature 10-present-mocks-tool Phase 1–2). The caller
- * supplies a `spec`; the plumbing below is identical for wireframes and mocks
- * on purpose, so the web's ONE review surface serves both. A COMPOSITION of
- * existing plumbing — no new tables, no migrations, no new RPCs:
- *   1. each render becomes a normal artifact on the SESSION'S task, inserted
- *      exactly the way create_artifact does (AS THE USER, `from_agent` null —
- *      the deployed guard reserves agent attribution for the coordinated path
- *      this feature does not use — plus the same best-effort
- *      cliv2_agent_outputs attribution, one row per artifact): type
- *      'wireframe' for a UI diagram, 'diagram' for an architecture diagram,
- *      'mock' for an interactive mock, format 'html'. The multi shape
- *      (options: 2..11 of {label, html})
- *      creates one artifact per option, in order, and maps option ↔ artifact
- *      through purpose_key 'wireframe_option:<presentation-uuid>:<idx>' on
- *      EVERY option artifact (idx 0 included) — the web matches decision
- *      options[i] to the artifact with idx i. Idx 0 is the PRIMARY: it carries
- *      the presentation title verbatim (idx > 0 titles are '<title> — <label>')
- *      and the review decision relates to it. The single shape (html) stays
- *      exactly Phase 1's one untagged artifact — NO purpose_key.
- *   2. the review request becomes a single_select decision opened through the
- *      SAME `cliv2_ask_question` RPC ask_question uses — category
- *      'wireframe_review' is the sentinel the web keys on to render the
- *      fullscreen review surface instead of a plain question, the context
- *      carries the title, and `p_related_artifact` points at the primary
- *      artifact. Options: ['approve', 'request changes'] (single) or
- *      [...labels, 'request changes'] (multi). One uniform outcome for 1..N:
- *      the user either APPROVES — 'approve' is the exact shape
- *      answer_task_decision_v2 keys on to auto-write artifact_approvals;
- *      picking an option label IS approving that option (derived in the web) —
- *      or requests changes; their comment rides along as answer_note. Hence
- *      'approve' / 'request changes' are RESERVED label values, and the DB's
- *      12-option decision cap bounds the labels at 11.
- * The review loop (Phase 5 — cumulative feedback rounds): the user sends any
- * number of feedback rounds, any time, without waiting — each is a web-written
- * `artifact_feedback` row tagged with the presentation's PRIMARY (idx 0)
- * artifact and its artifact_revision at send time. That tag is the version
- * stamp of the presentation as a whole, NOT a per-option pointer: in a
- * multi-option presentation, which option a note concerns is named inline in
- * the note's "(…)" option label within the round's body. The agent reads the
- * rounds from get_task's `feedback` list (oldest first). The
- * decision above is the APPROVAL GATE only: it stays open across rounds and
- * decides ONLY when the user approves (selected_options[0] 'approve' or an
- * option label; answer_note may carry a final comment). To iterate, the agent
- * revises the presented render IN PLACE with update_artifact — the DB bumps
- * its revision automatically, so later rounds self-identify against the new
- * version — and keeps polling; it must NOT call the presentation tool again for
- * iterations of the same design. Requires an open session (like ask_question —
- * the decision lives on the session's task, so there's no task_id arg). Full
- * version history is a later phase.
- */
-async function presentationHandler(client, userId, session, args, spec, 
-/** 18c Slice 6: the request THIS CONNECTION is working. See
- *  createArtifactHandler's attribution block (ux.md § "Slice 6"). */
-connectionTodoId = null) {
-    try {
-        if (!session) {
-            return errorResult(`${spec.tool} needs an open work session — call begin_work first.`);
-        }
-        const noItem = requiresWorkItem(session, spec.tool);
-        if (noItem)
-            return noItem;
-        if (!args.title || !args.title.trim())
-            return errorResult(`${spec.tool} requires a non-empty title.`);
-        const extra = spec.extraValidation?.();
-        if (extra)
-            return errorResult(extra);
-        // Exactly ONE of the two shapes: html (a single render, exactly Phase 1)
-        // or options (2..11 competing renders).
-        const hasHtml = args.html !== undefined;
-        const hasOptions = args.options !== undefined;
-        if (hasHtml && hasOptions) {
-            return errorResult(`${spec.tool} takes either html (one ${spec.unit}) or options (2..11 competing ${spec.unit}s), not both.`);
-        }
-        if (!hasHtml && !hasOptions) {
-            return errorResult(`${spec.tool} requires html (one ${spec.unit}) or options (2..11 competing ${spec.unit}s).`);
-        }
-        const multi = hasOptions;
-        let opts = [];
-        if (multi) {
-            if (!Array.isArray(args.options) || args.options.length < 2 || args.options.length > 11) {
-                return errorResult(`${spec.tool} requires 2..11 options (use html for a single ${spec.unit}; a review decision is capped at 12 options including the reserved one).`);
-            }
-            opts = args.options.map((option) => ({ label: (option.label ?? '').trim(), html: option.html ?? '' }));
-            if (opts.some((o) => !o.label)) {
-                return errorResult(`${spec.tool} requires a non-empty label for every option.`);
-            }
-            if (opts.some((o) => !o.html.trim())) {
-                return errorResult(`${spec.tool} requires non-empty html for every option (${spec.htmlSpec}).`);
-            }
-            const lowered = opts.map((o) => o.label.toLowerCase());
-            if (new Set(lowered).size !== lowered.length) {
-                return errorResult(`${spec.tool} requires distinct option labels (case-insensitive).`);
-            }
-            if (lowered.some((label) => RESERVED_OPTION_LABELS.includes(label))) {
-                return errorResult(`${spec.tool} option labels 'approve' and 'request changes' are reserved review outcomes — rename the option.`);
-            }
-        }
-        else if (!args.html || !args.html.trim()) {
-            return errorResult(`${spec.tool} requires non-empty html (${spec.htmlSpec}).`);
-        }
-        const title = args.title.trim();
-        // Sentence-initial form of the artifact noun, for the attribution warning.
-        const capitalNoun = spec.artifactNoun.charAt(0).toUpperCase() + spec.artifactNoun.slice(1);
-        // The review decision's question — the recovery message below quotes it
-        // LITERALLY, so both must come from this one string.
-        const question = `Review the ${spec.artifactNoun} and leave feedback.`;
-        // One entry per artifact to create, in presentation order (idx 0 = the
-        // primary). Multi tags EVERY entry with the option ↔ artifact mapping key;
-        // single stays untagged, exactly Phase 1.
-        const presentationId = multi ? randomUUID() : null;
-        const renders = multi
-            ? opts.map((option, idx) => ({
-                title: idx === 0 ? title : `${title} — ${option.label}`,
-                html: option.html,
-                purpose_key: `wireframe_option:${presentationId}:${idx}`,
-            }))
-            : [{ title, html: args.html, purpose_key: null }];
-        // The review decision's options: the approval outcome(s) first, 'request
-        // changes' always last (the DB caps decision options at 12, hence ≤11 labels).
-        const reviewOptions = multi ? [...opts.map((o) => o.label), 'request changes'] : ['approve', 'request changes'];
-        // The renders land on the session's task. Confirm it is live under the
-        // user's RLS first (mirrors create_artifact) so a task archived after
-        // begin_work gets a clean error instead of an opaque insert failure.
-        const task = await must(client.from('tasks').select('id').eq('id', session.taskId).is('archived_at', null).maybeSingle());
-        if (!task)
-            return errorResult(`No task found for id "${session.taskId}".`);
-        // 1. Each render as a normal artifact — the SAME insert create_artifact
-        // does, one row per render, in presentation order.
-        const created = [];
-        const attributionWarnings = [];
-        for (const render of renders) {
-            let row = null;
-            try {
-                row = await must(client
-                    .from('artifacts')
-                    .insert({
-                    task_id: session.taskId,
-                    type: spec.artifactType,
-                    format: 'html',
-                    // 18d Slice 3, gate A: a mock or wireframe IS "a presented
-                    // document" in story 2's list, and its body is agent-authored
-                    // HTML the user opens fullscreen.
-                    title: redactSecrets(connectionTodoId, render.title),
-                    ...(render.purpose_key ? { purpose_key: render.purpose_key } : {}),
-                    content: redactSecrets(connectionTodoId, render.html),
-                    created_by: userId,
-                    from_agent: null,
-                    agent_run_id: null,
-                })
-                    .select(ARTIFACT_COLUMNS)
-                    .single());
-                if (!row)
-                    throw new Error('Artifact insert returned no row.');
-            }
-            catch (err) {
-                // Nothing created yet → fatal and generic, exactly the Phase 1 path.
-                if (created.length === 0)
-                    throw err;
-                // A later option insert failing orphans the already-created options:
-                // return them (ids included) with guidance the agent can actually act
-                // on. No tool can delete an artifact (update_artifact has no deleted_at
-                // and there is no delete tool), so "clean up" is not an instruction the
-                // agent can execute — removal is a manual web action, and the agent's
-                // job is to surface it and hold off re-presenting (a blind retry would
-                // duplicate the created options).
-                const createdIds = created.map((row) => row.id).join(', ');
-                const failure = {
-                    artifacts: created,
-                    error: `${spec.tool}: created ${created.length} of ${renders.length} option artifacts, then the insert for ` +
-                        `'${render.title}' failed: ${err.message}. No review request was opened. There is no delete ` +
-                        `tool: the created artifacts (${createdIds}) are inert until removed manually in the web. Report this ` +
-                        `failure to the user with those ids, and do NOT call ${spec.tool} again (it would duplicate the ` +
-                        'created options) until the user confirms.',
-                };
-                if (attributionWarnings.length)
-                    failure.attribution_warning = attributionWarnings.join(' ');
-                return { ...textResult(failure), isError: true };
-            }
-            created.push(row);
-            // Best-effort session attribution per artifact (mirrors create_artifact:
-            // the session's task matches by construction). The artifact already exists
-            // and is part of the real return value, so a failed attribution write must
-            // NOT fail the tool — it is surfaced in the returned text, never dropped.
-            //
-            /* 18c SLICE 6: `todo_id` records WHICH RUN produced this render, off the
-               connection rather than the session. See createArtifactHandler's
-               attribution block (ux.md § "Slice 6"). This tool refuses outright
-               without a session AND without a work item (requiresWorkItem above), so
-               its session is always work-item-anchored and its `todoId` is always
-               null: this is the exact case gap 13 names, and the connection is the
-               only place the request can be read from. */
-            try {
-                await must(client.from('cliv2_agent_outputs').insert({
-                    user_id: userId,
-                    session_id: session.sessionId,
-                    kind: 'artifact',
-                    product_id: row.id,
-                    todo_id: connectionTodoId,
-                }));
-            }
-            catch (err) {
-                attributionWarnings.push(`${capitalNoun} artifact created, but recording session attribution failed: ${err.message}`);
-            }
-        }
-        const primary = created[0];
-        // 2. The review request as a single_select decision — the SAME RPC
-        // ask_question uses; 'wireframe_review' is the sentinel category the web
-        // keys on (feature 09). The artifacts above already exist, so from here a
-        // failure must NOT be the generic fatal error: swallowing them would orphan
-        // them in the DB (plain cards with no "feedback requested"), leave the
-        // agent with no ids to recover with, and invite a blind retry that
-        // duplicates artifacts. So this step gets its OWN try/catch (the FIRST
-        // artifact-insert failure path above stays fatal and generic), and on
-        // failure the error result STILL carries the created artifact(s) plus a
-        // message telling the agent to retry the review step — via ask_question
-        // with related_artifact_id — or clean up, not re-present.
-        let decision;
-        try {
-            const decisionId = await must(client.rpc('cliv2_ask_question', {
-                p_session: session.sessionId,
-                p_category: 'wireframe_review',
-                p_context: title,
-                p_question: question,
-                p_answer_mode: 'single_select',
-                p_options: reviewOptions,
-                p_related_artifact: primary.id,
-            }));
-            if (!decisionId)
-                throw new Error('Review request insert returned no decision id.');
-            // Best-effort attribution for the decision (mirrors ask_question exactly),
-            // 18c Slice 6 `todo_id` included.
-            try {
-                await must(client.from('cliv2_agent_outputs').insert({
-                    user_id: userId,
-                    session_id: session.sessionId,
-                    kind: 'decision',
-                    product_id: decisionId,
-                    todo_id: connectionTodoId,
-                }));
-            }
-            catch (err) {
-                attributionWarnings.push(`Review request created, but recording session attribution failed: ${err.message}`);
-            }
-            // Re-fetch the created decision with the SAME columns get_task returns, so
-            // the agent sees what it made and can later read the feedback back with
-            // get_task.
-            const fetched = await must(client.from('decisions').select(DECISION_COLUMNS).eq('id', decisionId).maybeSingle());
-            if (!fetched)
-                throw new Error('Created review decision could not be re-fetched.');
-            decision = fetched;
-        }
-        catch (err) {
-            // The recovery instruction must be LITERAL and complete: the web's review
-            // surface matches ONLY category === 'wireframe_review' (a sentinel that is
-            // deliberately not in any tool description, and that mocks reuse verbatim
-            // — there is no 'mock_review'), and the decision-consistency
-            // guard makes category immutable — so a plausible-but-wrong retry category
-            // would leave the review permanently stuck as a generic question. Spell out
-            // the exact ask_question call, with the real title, the full literal
-            // options array, and the primary artifact id. The multi failure payload
-            // carries ALL created artifacts (ids included).
-            const optionsLiteral = `[${reviewOptions.map((label) => `'${label}'`).join(', ')}]`;
-            const failure = {
-                ...(multi ? { artifacts: created } : { artifact: primary }),
-                error: `${spec.tool}: the ${spec.artifactNoun} artifact${multi ? 's were' : ' was'} created, but opening the review request failed: ` +
-                    `${err.message}. Do NOT call ${spec.tool} again (it would duplicate the artifact${multi ? 's' : ''}) — ` +
-                    `retry the review step with ask_question({ category: 'wireframe_review', context: '${title}', ` +
-                    `question: '${question}', answer_mode: 'single_select', ` +
-                    `options: ${optionsLiteral}, related_artifact_id: '${primary.id}' }) — the category string must be exactly ` +
-                    "'wireframe_review' or the web will not show the review UI — or clean up.",
-            };
-            if (attributionWarnings.length)
-                failure.attribution_warning = attributionWarnings.join(' ');
-            return { ...textResult(failure), isError: true };
-        }
-        const payload = {
-            ...(multi ? { artifacts: created } : { artifact: primary }),
-            decision,
-            instruction: multi
-                ? `The user has been asked to review ${created.length} competing options. They send CUMULATIVE feedback ` +
-                    "rounds — any number, any time, without waiting for you: poll get_task and read them from its `feedback` " +
-                    'list (oldest first). Every round is tagged with the presentation PRIMARY artifact (the first option) and ' +
-                    'its artifact_revision at send time — the version stamp of the presentation, NOT a per-option pointer. ' +
-                    "Which OPTION a note concerns is named inline in the note's \"(…)\" option label within the round's body. " +
-                    'This decision is the approval gate only: it stays open across rounds and decides ONLY when the user ' +
-                    'approves — once its state is decided, selected_options[0] is the approved option label and answer_note ' +
-                    'may carry a final comment. To act on feedback, revise the option artifact each note names IN PLACE with ' +
-                    'update_artifact (its revision bumps automatically), then call resolve_feedback with the ids of the ' +
-                    "rounds that revision actually addressed and the revised OPTION artifact's NEW revision number — only " +
-                    'rounds you genuinely acted on. Option revisions are their own number-space (not the primary v-tags): ' +
-                    'the review surface shows a multi round as resolved WITHOUT a version number, so name WHICH option you ' +
-                    'revised in any accompanying update, and never expect the primary revision to move when only options ' +
-                    "changed. A round the user flips back to 'reopened' is open feedback again: address it on the next pass " +
-                    `and re-resolve. Keep polling. Do NOT call ${spec.tool} ` +
-                    'again for iterations of this same design.'
-                : `The user has been asked to review the ${spec.artifactNoun}. They send CUMULATIVE feedback rounds — any number, any ` +
-                    "time, without waiting for you: poll get_task and read them from its `feedback` list (oldest first), each " +
-                    'tagged with the artifact_revision it critiques so you know which version the notes are about. This ' +
-                    'decision is the approval gate only: it stays open across rounds and decides ONLY when the user approves ' +
-                    "— once its state is decided, selected_options[0] is 'approve' and answer_note may carry a final comment. " +
-                    `To act on feedback, revise this ${spec.artifactNoun} IN PLACE with update_artifact (its revision bumps ` +
-                    'automatically, so later rounds name the new version), then call resolve_feedback with the ids of the ' +
-                    'rounds that revision actually addressed and the NEW revision number — only rounds you genuinely acted ' +
-                    "on. A round the user flips back to 'reopened' is open feedback again: address it on the next pass and " +
-                    `re-resolve. Keep polling. Do NOT call ${spec.tool} ` +
-                    'again for iterations of this same design.',
-        };
-        if (attributionWarnings.length)
-            payload.attribution_warning = attributionWarnings.join(' ');
-        return textResult(payload);
-    }
-    catch (err) {
-        return errorResult(`${spec.tool} failed: ${err.message}`);
-    }
+async function presentationHandler(client, userId, session, args, spec, connectionTodoId = null) {
+    if (!session)
+        return errorResult(`${spec.tool} needs an open work session — call begin_work first.`);
+    const noItem = requiresWorkItem(session, spec.tool);
+    if (noItem)
+        return noItem;
+    return presentDesign(client, userId, session.taskId, {
+        ...args, title: redactSecrets(connectionTodoId, args.title),
+        ...(args.html === undefined ? {} : { html: redactSecrets(connectionTodoId, args.html) }),
+        ...(!Array.isArray(args.options) ? {} : { options: args.options.map(option => ({ label: option?.label, html: redactSecrets(connectionTodoId, option?.html ?? '') })) }),
+    }, spec, async (kind, id) => {
+        await must(client.from('cliv2_agent_outputs').insert({ user_id: userId, session_id: session.sessionId,
+            kind, product_id: id, todo_id: connectionTodoId }));
+    }, async (review) => {
+        const id = await must(client.rpc('cliv2_ask_question', {
+            p_session: session.sessionId, p_category: 'wireframe_review', p_context: review.title,
+            p_question: review.question, p_answer_mode: 'single_select', p_options: review.options,
+            p_related_artifact: review.artifactId,
+        }));
+        if (!id)
+            throw new Error('Review request insert returned no decision id.');
+        return id;
+    });
 }
 /**
  * present_wireframes (feature 09) — 1..N lo-fi HTML wireframes (kind 'ui') or
@@ -3877,66 +3485,6 @@ connectionTodoId = null) {
         artifactNoun: 'mock',
     }, connectionTodoId);
 }
-/** Loose UUID shape check (any version), so a malformed id gets a clean tool
- *  error naming it instead of a Postgres `invalid input syntax for type uuid`
- *  failing the whole batch. */
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/**
- * Mark feedback rounds resolved by a revision (feature 09, Phase 5 — hybrid
- * resolution). After update_artifact ships a revision, the agent calls this
- * with the ids of the rounds that revision actually addressed and the NEW
- * revision number; each round flips to status 'resolved' with
- * resolved_in_revision = revision. The user can flip a round back to
- * 'reopened' in the web when the change wasn't material, and this same call
- * re-resolves it on the next pass. This is the ONE write the CLI makes to
- * `artifact_feedback`: a plain UPDATE as the user through RLS
- * `artifact_feedback_update` (task access + the 'comment' grant) and the
- * column-level grant on the four resolution columns. The DB's status-only
- * guard keeps round bodies immutable and stamps status_changed_at/_by itself
- * (never trusted from here), so only status + resolved_in_revision are sent.
- *
- * The UPDATE's `.in(...)` silently skips ids that don't exist, aren't visible
- * under RLS, or belong to a task the user can't touch — so the result rows are
- * compared against the request and ANY shortfall is an error that lists the
- * missing ids (and the ones that DID update, since those flips committed).
- * Requires an open session, like the sibling review tools. Exported (like
- * presentWireframesHandler) so the self-check can exercise it with a stub
- * client.
- */
-export async function resolveFeedbackHandler(client, session, args) {
-    try {
-        if (!session) {
-            return errorResult('resolve_feedback needs an open work session — call begin_work first.');
-        }
-        if (!Array.isArray(args.feedback_ids) || args.feedback_ids.length === 0) {
-            return errorResult('resolve_feedback requires feedback_ids (at least one feedback round id).');
-        }
-        if (!Number.isInteger(args.revision) || args.revision < 1) {
-            return errorResult('resolve_feedback requires revision (a positive integer — the artifact revision that addressed the rounds).');
-        }
-        const ids = [...new Set(args.feedback_ids.map((id) => id.trim()))];
-        const malformed = ids.filter((id) => !UUID_RE.test(id));
-        if (malformed.length) {
-            return errorResult(`resolve_feedback: not valid feedback round id(s): ${malformed.join(', ')}.`);
-        }
-        const rows = (await must(client
-            .from('artifact_feedback')
-            .update({ status: 'resolved', resolved_in_revision: args.revision })
-            .in('id', ids)
-            .select('id'))) ?? [];
-        const updated = rows.map((row) => row.id);
-        if (updated.length !== ids.length) {
-            const missing = ids.filter((id) => !updated.includes(id));
-            return errorResult(`resolve_feedback: ${updated.length} of ${ids.length} round(s) updated. Not found (or not accessible): ` +
-                `${missing.join(', ')}.${updated.length ? ` Already marked resolved: ${updated.join(', ')}.` : ''} ` +
-                'Check the ids against the most recent get_task `feedback` list.');
-        }
-        return textResult({ resolved: updated, revision: args.revision });
-    }
-    catch (err) {
-        return errorResult(`resolve_feedback failed: ${err.message}`);
-    }
-}
 /**
  * Record the user's answer to an OPEN decision on the work item (feature 05 / D4 —
  * the run-free twin of v1's `record_user_input`). Unlike v1, this does NOT go through a
@@ -5341,40 +4889,6 @@ export async function readSkillFileHandler(client, args) {
         return errorResult(`read_skill_file failed: ${errorMessage(err)}`);
     }
 }
-// ---------------------------------------------------------------------------
-// Project context (feature 13a, Phase 3) — `get_project_context`.
-//
-// READ-ONLY, and read-only over a V1-OWNED PRODUCT TABLE. `public.project_documents`
-// is the table the web app writes under Project settings → Project context (Phase 1)
-// and on a codebase page (Phase 2). AGENTS.md § "Database schema naming" allows
-// exactly this: the v2 surface may `select` shared product data through the signed-in
-// user's RLS, as the web app does; what it may not do is WRITE outside `cliv2_*` or
-// hold its own state there. This tool writes nothing and adds no `cliv2_*` row.
-//
-// SCOPE IS FILTERED IN THE QUERY, NOT IN JS. A document is project-scoped when
-// `codebase_id is null` and codebase-scoped when `codebase_id = <id>` — the whole
-// model, per 20260726220000_project_documents_codebase_scope.sql. Both scopes are
-// read with their own predicate (`.is('codebase_id', null)` / `.eq('codebase_id', id)`)
-// so a codebase document can NEVER reach a project-only response, whatever the
-// caller passed. Filtering after the fact would make that a code-path property
-// instead of a query property; both earlier phases were reviewed on this point.
-//
-// NO OPEN SESSION IS REQUIRED when `task_id` is passed. That is a deliberate
-// departure from the '<tool> needs an open work session — call begin_work first.'
-// gate every WRITE tool carries: reading a project's standing context BEFORE
-// opening a work session is a legitimate and expected flow (an agent orienting
-// itself), and the tool mutates nothing that would need attributing to a session.
-// With neither a session nor a task_id there is genuinely no project to resolve,
-// and the refusal is phrased as the instruction (the doctrine at registerTool):
-// it names both ways out.
-// ---------------------------------------------------------------------------
-/** The five types `public.project_documents.type` admits, verbatim from the
- *  migration's check constraint and the web composer's Select. */
-const PROJECT_DOCUMENT_TYPES = ['instructions', 'architecture', 'design', 'conventions', 'other'];
-/** Phase 4's `propose_project_context` resolves the project exactly as Phase 3's
- *  reader does, so the refusal copy is written once and parameterized by the
- *  tool doing the asking rather than duplicated and left to drift. */
-const noProjectContextError = (tool) => `${tool} needs to know which project. Call begin_work first, or pass task_id.`;
 /** The empty-state note, verbatim from the approved transcript. It says where the
  *  documents come from, so an agent that finds none doesn't try to create one —
  *  there is no write path, by design.
@@ -5501,11 +5015,6 @@ async function fetchProjectDocumentTypes(client, projectId, codebaseId) {
     return [...new Set((rows ?? []).map((row) => row.type))];
 }
 const jsonBytes = (value) => Buffer.byteLength(JSON.stringify(value, null, 2), 'utf8');
-/** CHARACTERS, meaning code points — what `content_length` claims to be and what a
- *  person counting emoji would say. `String.length` is UTF-16 code units, which
- *  double-counts every astral character (60,000 emoji would report 120,000).
- *  The surrogate test short-circuits the allocating spread for the ordinary case. */
-const countCharacters = (text) => /[\uD800-\uDFFF]/.test(text) ? [...text].length : text.length;
 /**
  * Fit the shaped documents into MAX_RESPONSE_BYTES, in order, cutting content
  * first and dropping the tail only when even the metadata will not fit.
@@ -5636,115 +5145,6 @@ function fitToBudget(envelope, documents, extraNotes) {
     }
     return { documents: fitted, truncated, omitted: 0 };
 }
-/**
- * PROJECT RESOLUTION, shared by `get_project_context` (Phase 3) and
- * `propose_project_context` (Phase 4). Both paths reduce to one task id — `task_id` when given,
- * otherwise the open session's task (the session registry carries `taskId`, not a
- * project) — and the project is read off that task. Agents therefore never have to
- * find, or be trusted with, a project id. An archived or deleted task resolves to
- * nothing and is refused by id, which is also what happens when a session's task
- * was archived or deleted after begin_work.
- *
- * The task id is UUID-shape-checked BEFORE the read, exactly as resolve_feedback
- * does, so `{ task_id: "task-1" }` gets a clean tool error naming it instead of a
- * Postgres `invalid input syntax for type uuid`. A `task_id` that was supplied but
- * is blank is refused rather than falling through to the open session's task —
- * silently answering about a DIFFERENT task and reporting success is the worst
- * possible reading of "   ".
- *
- * The project's NAME rides along on the task select (`projects(name)`) rather than
- * costing a second round-trip; the FK makes the embed non-null, so there is no
- * "no project for task" state to write copy for.
- */
-async function resolveContextProject(client, session, taskIdArg, tool) {
-    if (taskIdArg !== undefined && taskIdArg.trim() === '') {
-        return {
-            ok: false,
-            error: errorResult(`${tool}: task_id was blank. Pass a task id, or omit it to use the open session's task.`),
-        };
-    }
-    const taskId = taskIdArg?.trim() || session?.taskId;
-    if (!taskId)
-        return { ok: false, error: errorResult(noProjectContextError(tool)) };
-    if (!UUID_RE.test(taskId)) {
-        return { ok: false, error: errorResult(`${tool}: not a valid task id: "${taskId}".`) };
-    }
-    const task = await must(client
-        .from('tasks')
-        .select('project_id, projects(name)')
-        .eq('id', taskId)
-        .is('archived_at', null)
-        .maybeSingle());
-    if (!task)
-        return { ok: false, error: errorResult(`${tool}: no task found for id "${taskId}".`) };
-    // PostgREST returns a to-one embed as an object, but has returned an array
-    // for the same shape across versions, so both are unwrapped. A MISSING name
-    // is not defaulted to '': `tasks.project_id` is a non-null FK, so a blank
-    // project in the envelope could only mean the read did not return what it
-    // was asked for, and answering with an empty project name is a silent wrong
-    // value in a field the agent uses to know which project it is reading.
-    const embedded = Array.isArray(task.projects) ? (task.projects[0] ?? null) : task.projects;
-    if (!embedded?.name) {
-        return {
-            ok: false,
-            error: errorResult(`${tool}: could not read the project for task "${taskId}". Try again, ` +
-                'and if it keeps happening report it — a task always has a project.'),
-        };
-    }
-    return { ok: true, value: { id: task.project_id, name: embedded.name } };
-}
-/**
- * CODEBASE MATCHING is over the project's own `cliv2_codebases` rows only, on
- * either the display name or the canonical `host/path` git remote (case-insensitive;
- * a raw remote URL is canonicalized with the same `hostedRemoteIdentity` the CLI
- * uses to register one, so `https://github.com/acme/web.git` matches `github.com/acme/web`).
- * A miss names the known codebases rather than just refusing — the agent can retry
- * without a second call.
- *
- * A NAME CAN BE AMBIGUOUS. `cliv2_codebases` is unique on `(project_id,
- * git_remote_url)` and NOT on `name`, so one project holding `github.com/acme/web`
- * and `gitlab.com/acme/web` — both named "web" — is normal. Taking the first hit
- * would silently answer about whichever was created first, with nothing in the
- * response for the agent to notice. Every match is collected and more than one is
- * an error listing the candidates by remote, phrased like the unknown-codebase
- * miss: it tells the agent exactly what to pass instead.
- */
-async function resolveContextCodebase(client, projectId, wanted, tool) {
-    const rows = (await must(client
-        .from('cliv2_codebases')
-        .select('id, name, git_remote_url')
-        .eq('project_id', projectId)
-        .order('created_at', { ascending: true }))) ?? [];
-    // `normalizeRemoteUrl` already lowercases (src/git-remote.ts:32) and is
-    // idempotent, and `git_remote_url` is STORED canonical (src/codebases.ts:87),
-    // so the identity comparison subsumes any raw-value comparison. Name matching
-    // stays case-insensitive.
-    const needle = wanted.toLowerCase();
-    const identity = hostedRemoteIdentity(wanted) ?? null;
-    const found = rows.filter((row) => row.name.toLowerCase() === needle ||
-        (identity !== null && row.git_remote_url.toLowerCase() === identity));
-    if (found.length === 0) {
-        return {
-            ok: false,
-            error: errorResult(`${tool}: no codebase named "${wanted}" in this project. ` +
-                (rows.length
-                    ? // Deduped: `name` has no unique constraint (only (project_id,
-                        // git_remote_url) does), so two codebases can share one name.
-                        // Listing it twice tells the agent nothing and reads as a bug.
-                        `Known codebases: ${[...new Set(rows.map((row) => row.name))].join(', ')}.`
-                    : 'This project has no codebases yet.')),
-        };
-    }
-    if (found.length > 1) {
-        return {
-            ok: false,
-            error: errorResult(`${tool}: more than one codebase named "${wanted}" in this project. ` +
-                `Matching git remotes: ${found.map((row) => row.git_remote_url).join(', ')}. ` +
-                'Pass the git remote instead of the name.'),
-        };
-    }
-    return { ok: true, value: { id: found[0].id, name: found[0].name } };
-}
 /**
  * Read the context documents for the project a task belongs to, optionally also
  * those of one of its codebases, optionally narrowed to some types. Project and
@@ -5884,340 +5284,6 @@ async function unnarrowedEmptyNote(client, projectId) {
     }
     return NO_PROJECT_DOCUMENTS_NOTE;
 }
-export async function getDocumentHandler(client, args) {
-    const id = typeof args.id === 'string' ? args.id.trim() : '';
-    if (!id) {
-        return errorResult('get_document requires id — the id of the document to read, as the web app’s “Copy for agent” ' +
-            'button pastes it.');
-    }
-    // Shape-checked once, here at the boundary, exactly as resolveContextProject
-    // does with task_id: without it a mistyped id comes back as a Postgres
-    // "invalid input syntax for type uuid", which reads like a bug in the tool.
-    if (!UUID_RE.test(id)) {
-        return errorResult(`get_document: not a valid document id: "${id}".`);
-    }
-    try {
-        // Context documents first, then instructions. RLS scopes both reads, so a
-        // row the caller may not see is simply absent and falls through to the
-        // not-found below.
-        const documents = await must(client
-            .from('project_documents')
-            .select('title, content, codebase_id, type')
-            .eq('id', id));
-        const document = (documents ?? [])[0];
-        if (document)
-            return textResult(shapeDocument(document));
-        const instructions = await must(client.from('agent_instructions').select('title, content, codebase_id').eq('id', id));
-        const instruction = (instructions ?? [])[0];
-        if (instruction) {
-            return textResult({
-                ...shapeDocument(instruction),
-                // Said plainly, so an agent that fetched one does not conclude these are
-                // reference material it may choose to consult: it already has them.
-                note: 'This is an agent instruction. Every instruction on this project is already delivered in ' +
-                    'your prompt — reading one here does not make it optional.',
-            });
-        }
-        return errorResult(`get_document: no document with id ${id}. It may have been deleted, or belong to a project you ` +
-            'cannot see. Call get_project_context to read the documents on the project you are working.');
-    }
-    catch (err) {
-        return errorResult(`get_document failed: ${errorMessage(err)}`);
-    }
-}
-/** The one shape both tables report in, so a caller never has to branch on
- *  which table answered. `scope` is what `codebase_id` MEANS — null is the
- *  project's own document, a value is that codebase's. */
-function shapeDocument(row) {
-    return {
-        title: row.title,
-        ...(row.type ? { type: row.type } : {}),
-        scope: row.codebase_id === null ? 'project' : 'codebase',
-        content: row.content,
-    };
-}
-// ---------------------------------------------------------------------------
-// Project context (feature 13a, Phase 4) — `propose_project_context`.
-//
-// THE ONLY WRITE THIS FEATURE'S CLI SURFACE MAKES, AND IT CREATES NO DOCUMENT.
-// An agent that has just read the repo it is working in hands over a batch of
-// PROPOSALS; approval happens in the web app, one by one or all at once, and
-// only an accept creates a `public.project_documents` row. So this tool writes
-// `public.cliv2_context_proposals` — a `cliv2_*` table, per AGENTS.md
-// § "Database schema naming": v2 may READ shared product data through the
-// user's RLS (that is what Phase 3 does), but its own state and every write it
-// makes live behind the `cliv2_` prefix. `project_id`, `codebase_id` and
-// `scanned_codebase_id` are held BY VALUE with no FK, for the same reason.
-//
-// SCOPE IS PER PROPOSAL, NOT PER CALL. A settled user ruling: one scan produces
-// both project-scoped and codebase-scoped proposals at once and they are
-// reviewed together in project settings. `scope: "project"` stores
-// `codebase_id = null`; `scope: "codebase"` stores the SCANNED codebase's id.
-// There is deliberately no way to target a different codebase — the agent read
-// one repo, and a proposal aimed somewhere it never looked is a claim it cannot
-// support.
-//
-// A RE-SCAN REPLACES, AND AN EMPTY SCAN CLEARS. Before inserting, this user's
-// pending rows for (project_id, scanned_codebase_id) are deleted. A scan
-// reports what the repo holds NOW; it carries no memory of past answers — so a
-// scan that finds NOTHING is a real finding and is accepted: it runs the same
-// replace-delete, inserts nothing, and reports what it cleared. Refusing it
-// would mean a repo whose context files were deleted could never get back to
-// "no proposals", which the review surface models as a state (user ruling,
-// 2026-07-27). `codebase` stays required either way — a scan always names the
-// repo it read. The user ruled explicitly
-// that rejecting a proposal DISCARDS it and stores nothing — there is no
-// rejected list and no "already rejected" state to suppress against, and a
-// later scan is free to propose the same thing again (ux.md § Corrections,
-// Phase 4 / 2026-07-27). Anything that looked like suppression here would be
-// inventing that state.
-//
-// NOTHING IS EVER SILENTLY TRUNCATED. The batch is bounded by a proposal COUNT
-// and a total CHARACTER budget, and a batch over either is REFUSED with the
-// limit and the actual figure named. Phase 3's log is a catalogue of what
-// silent truncation costs; a write path has an easier answer than a read path —
-// refuse, and let the agent send a smaller batch — so it takes it.
-//
-// NO ABSOLUTE PATH REACHES THE CLOUD — IN `source_path`. That column, and not
-// the whole row, is what this rule covers, because `source_path` is
-// PRODUCT-EMITTED: the agent derives it from the filesystem it just walked, and
-// it is rendered in `mono` on every proposal card by hosted browser JS, where
-// this product hard-enforces that absolute local paths never appear (AGENTS.md;
-// the contract test at web/src/lib/hosted-path-privacy.contract.test.ts).
-// `content` is deliberately NOT policed the same way: it is AUTHORED prose that
-// the agent read verbatim out of the repo, a hand-typed document may legally
-// contain any text at all, and a check there would refuse AGENTS.md itself —
-// the very document this feature exists to import (user ruling, 2026-07-27).
-// The table cannot police the path either — no check constraint tells a legal
-// relative path from an absolute one across POSIX, Windows drive-letter,
-// drive-relative and UNC forms without knowing the platform — so this tool
-// does, and it REFUSES rather than rewriting: silently rewriting a path the
-// agent sent is how a proposal ends up pointing at a file that isn't there.
-// ---------------------------------------------------------------------------
-/** The scopes a proposal may carry. `project` stores `codebase_id = null`;
- *  `codebase` stores the scanned codebase's id. */
-const PROPOSAL_SCOPES = ['project', 'codebase'];
-/** `public.project_documents.title` is `length(title) <= 100` (Phase 1 §1).
- *  Refused HERE so the agent learns at propose time, rather than the user
- *  discovering at accept time that a proposal can never become a document. */
-const MAX_PROPOSAL_TITLE_CHARS = 100;
-/** How many proposals one scan may hand over. A review surface is a human
- *  reading cards; a hundred of them is not a review. Refused, never trimmed. */
-const MAX_PROPOSALS = 50;
-/** Total characters across the whole batch (content + title + reason +
- *  source_path). `content` has no length cap on `project_documents` and gets
- *  none here — a bound this table enforced but the document table did not would
- *  make a legal document un-acceptable — so the BATCH is what is bounded, which
- *  is the thing that actually protects the write. */
-const MAX_PROPOSAL_BATCH_CHARS = 400_000;
-/** A `..` segment under either separator. A relative path that climbs out of
- *  the scanned repo names a file the scan had no business reading, and it is
- *  refused for the same privacy reason an absolute path is. */
-const ESCAPING_PATH_RE = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
-/** Where the user reviews what was proposed. The agent's job ends at proposing,
- *  so the success result has to say this in prose it can relay verbatim. */
-const REVIEW_LOCATION = 'Project settings → Project context';
-/**
- * Validate one proposal into the row it will become, or refuse it by index AND
- * by title — an agent that sent twelve proposals needs to know WHICH one, and
- * an index alone is a poor handle when it is re-reading its own array.
- */
-function validateProposal(proposal, index, project, scanned) {
-    const at = `proposal ${index + 1}`;
-    const refuse = (message) => ({
-        ok: false,
-        error: errorResult(`propose_project_context: ${at} ${message}`),
-    });
-    if (!proposal || typeof proposal !== 'object') {
-        return refuse('is not an object. Each proposal needs title, type, content, source_path, reason and scope.');
-    }
-    const title = typeof proposal.title === 'string' ? proposal.title.trim() : '';
-    if (!title)
-        return refuse('has no title.');
-    if (countCharacters(title) > MAX_PROPOSAL_TITLE_CHARS) {
-        return refuse(`has a ${countCharacters(title)}-character title; the limit is ${MAX_PROPOSAL_TITLE_CHARS}. ` +
-            'Shorten it — a document title is a heading, not a summary.');
-    }
-    if (!PROJECT_DOCUMENT_TYPES.includes(proposal.type)) {
-        return refuse(`("${title}") has type "${String(proposal.type)}", which is not a context document type. ` +
-            `Use one of: ${PROJECT_DOCUMENT_TYPES.join(', ')}.`);
-    }
-    if (!PROPOSAL_SCOPES.includes(proposal.scope)) {
-        return refuse(`("${title}") has scope "${String(proposal.scope)}". Use "project" for context that applies to the ` +
-            `whole project, or "codebase" for context that belongs to "${scanned.name}" alone.`);
-    }
-    const content = typeof proposal.content === 'string' ? proposal.content : '';
-    if (content.trim() === '') {
-        return refuse(`("${title}") has no content. Propose only what you actually read — an empty document helps nobody.`);
-    }
-    const reason = typeof proposal.reason === 'string' ? proposal.reason.trim() : '';
-    if (!reason) {
-        return refuse(`("${title}") has no reason. Every proposal carries one line saying why this belongs in the ` +
-            "project's context, so the user can judge the judgement and not just the text.");
-    }
-    const rawPath = typeof proposal.source_path === 'string' ? proposal.source_path.trim() : '';
-    if (!rawPath) {
-        return refuse(`("${title}") has no source_path. Name the file in the repo this content came from.`);
-    }
-    if (ABSOLUTE_PATH_RE.test(rawPath)) {
-        return refuse(`("${title}") has an absolute source_path: "${rawPath}". Pass it relative to the root of ` +
-            `"${scanned.name}" (e.g. "docs/architecture.md"). Absolute local paths must never leave this machine.`);
-    }
-    if (ESCAPING_PATH_RE.test(rawPath)) {
-        return refuse(`("${title}") has a source_path that climbs out of the repo: "${rawPath}". Propose only files ` +
-            `inside "${scanned.name}".`);
-    }
-    // A leading "./" is the one rewrite made, because it changes nothing about
-    // which file is named and "./AGENTS.md" renders as noise on a card.
-    const sourcePath = rawPath.replace(/^\.\//, '');
-    return {
-        ok: true,
-        value: {
-            project_id: project.id,
-            codebase_id: proposal.scope === 'project' ? null : scanned.id,
-            scanned_codebase_id: scanned.id,
-            title,
-            type: proposal.type,
-            content,
-            source_path: sourcePath,
-            reason,
-        },
-    };
-}
-/**
- * Hand over a batch of proposed context documents for a repo the agent has read.
- *
- * WRITES PENDING ROWS ONLY. No `project_documents` row is created here under any
- * argument — the web app's accept does that. The success result therefore ends
- * by telling the agent where the human reviews them, because that is the only
- * remaining step and the agent cannot take it.
- *
- * REQUIRES NO OPEN SESSION when `task_id` is passed, matching Phase 3. This is a
- * write, and every other write tool in this file demands a session — but the
- * session exists to ATTRIBUTE work to a task, and a proposal is attributed to a
- * project and a codebase, neither of which the session supplies. Scanning a repo
- * before opening a work session is the ordinary flow (an agent orienting itself),
- * and refusing it would buy nothing.
- *
- * THE REPLACE AND THE INSERT ARE NOT ATOMIC. Two statements, no transaction —
- * PostgREST has none to offer, and an RPC to get one would put v2 logic in the
- * database for a case that cannot corrupt anything: the delete is scoped to this
- * user's rows for exactly this (project, scanned codebase), so a failure between
- * the two leaves the previous scan's proposals gone and the new ones unwritten.
- * The recovery is to run the scan again, which is precisely what this tool does.
- * The insert failing after the delete is reported as a failure, so nothing is
- * silently lost.
- */
-export async function proposeProjectContextHandler(client, session, args) {
-    try {
-        const resolvedProject = await resolveContextProject(client, session, args.task_id, 'propose_project_context');
-        if (!resolvedProject.ok)
-            return resolvedProject.error;
-        const project = resolvedProject.value;
-        // The scanned codebase is REQUIRED — every proposal, project-scoped ones
-        // included, records which repo the claim came from, and a project-scoped
-        // proposal with no provenance is unreviewable.
-        const wanted = args.codebase?.trim();
-        if (!wanted) {
-            return errorResult('propose_project_context: name the codebase you scanned in `codebase` (its name or git remote). ' +
-                'Every proposal records which repo it came from.');
-        }
-        const resolvedCodebase = await resolveContextCodebase(client, project.id, wanted, 'propose_project_context');
-        if (!resolvedCodebase.ok)
-            return resolvedCodebase.error;
-        const scanned = resolvedCodebase.value;
-        // AN EMPTY BATCH IS A REAL SCAN RESULT, NOT A MISTAKE. `[]` says the repo
-        // holds no standing context now, and it clears whatever an earlier scan left
-        // pending — without it there is no path from a real scan back to "no
-        // proposals" (user ruling, 2026-07-27). A MISSING or non-array `proposals`
-        // is still a malformed call, and is refused so the empty-scan meaning stays
-        // something the agent has to state on purpose.
-        const proposals = args.proposals;
-        if (!Array.isArray(proposals)) {
-            return errorResult('propose_project_context: `proposals` must be an array. Send the documents you found, or send ' +
-                '`[]` to report that this repo holds no standing context — an empty scan is a finding, and it ' +
-                'clears anything an earlier scan left waiting for review.');
-        }
-        if (proposals.length > MAX_PROPOSALS) {
-            return errorResult(`propose_project_context: ${proposals.length} proposals is more than the limit of ${MAX_PROPOSALS}. ` +
-                'Nothing was written. Propose the documents that carry standing context for the whole team, ' +
-                'not every file you read.');
-        }
-        const rows = [];
-        for (const [index, proposal] of proposals.entries()) {
-            const validated = validateProposal(proposal, index, project, scanned);
-            if (!validated.ok)
-                return validated.error;
-            rows.push(validated.value);
-        }
-        // Measured AFTER per-proposal validation so the agent hears about a broken
-        // proposal before it hears about the batch's size — the specific fault is
-        // more useful than the aggregate one.
-        const totalChars = rows.reduce((total, row) => total +
-            countCharacters(row.content) +
-            countCharacters(row.title) +
-            countCharacters(row.reason) +
-            countCharacters(row.source_path), 0);
-        if (totalChars > MAX_PROPOSAL_BATCH_CHARS) {
-            return errorResult(`propose_project_context: this batch is ${totalChars.toLocaleString('en-US')} characters, over the ` +
-                `limit of ${MAX_PROPOSAL_BATCH_CHARS.toLocaleString('en-US')}. Nothing was written, and nothing was ` +
-                'truncated. Send the batch in smaller parts, or drop the documents that are too long to be ' +
-                'standing context.');
-        }
-        // A RE-SCAN REPLACES: this user's pending rows for this (project, scanned
-        // codebase) go first. RLS scopes the delete to the user; the two eq filters
-        // scope it to this scan's subject, so another codebase's pending proposals —
-        // and another user's — are untouched. `.select('id')` makes the replaced
-        // COUNT knowable, which is what the result reports instead of leaving the
-        // agent to guess whether its earlier scan is still standing.
-        const replaced = (await must(client
-            .from('cliv2_context_proposals')
-            .delete()
-            .eq('project_id', project.id)
-            .eq('scanned_codebase_id', scanned.id)
-            .select('id'))) ?? [];
-        // Nothing to insert on an empty scan — the delete above WAS the whole call.
-        if (rows.length)
-            await must(client.from('cliv2_context_proposals').insert(rows));
-        const projectScoped = rows.filter((row) => row.codebase_id === null).length;
-        const codebaseScoped = rows.length - projectScoped;
-        const noun = rows.length === 1 ? 'proposal' : 'proposals';
-        const sentences = [];
-        if (rows.length === 0) {
-            sentences.push(`Nothing was found: this scan of "${scanned.name}" turned up no standing context to propose for ` +
-                `"${project.name}", so nothing is waiting for review.`);
-            sentences.push(replaced.length
-                ? `It cleared ${replaced.length} proposal${replaced.length === 1 ? '' : 's'} from an earlier scan ` +
-                    `of "${scanned.name}", which no longer stand — a scan reports what the repo holds now.`
-                : 'There was nothing pending to clear.');
-            sentences.push('No document was touched: accepted context documents are not proposals and are unaffected. Tell ' +
-                'the user the repo holds no standing context worth importing.');
-        }
-        else {
-            sentences.push(`${rows.length} context document ${noun} ${rows.length === 1 ? 'is' : 'are'} now waiting for review ` +
-                `in the web app, under ${REVIEW_LOCATION} for "${project.name}".`);
-            if (replaced.length) {
-                sentences.push(`This re-scan replaced ${replaced.length} proposal${replaced.length === 1 ? '' : 's'} from an ` +
-                    `earlier scan of "${scanned.name}" — a scan reports what the repo holds now.`);
-            }
-            sentences.push('Nothing has been created yet: the user accepts or rejects each one there, and only an accept ' +
-                'makes it a context document. Tell them where to look.');
-        }
-        return textResult({
-            project: project.name,
-            scanned_codebase: scanned.name,
-            proposed: rows.length,
-            project_scoped: projectScoped,
-            codebase_scoped: codebaseScoped,
-            replaced: replaced.length,
-            review_in: REVIEW_LOCATION,
-            instruction: sentences.join(' '),
-        });
-    }
-    catch (err) {
-        return errorResult(`propose_project_context failed: ${errorMessage(err)}`);
-    }
-}
 // ---------------------------------------------------------------------------
 // Client context intake (feature 24c, Slice 1) — `get_client_context` /
 // `propose_client_context`.
@@ -8293,7 +7359,7 @@ export async function listStepsHandler(client, args) {
         }
         const stageRows = (await must(client
             .from('cliv2_stages')
-            .select('id, title, position, source_kind, source_label, source_ref, created_at')
+            .select('id, title, position, source_kind, source_label, source_ref, source_workflow_ref, created_at')
             .eq('work_item_id', workItemId)
             .order('position', { ascending: true })
             .order('created_at', { ascending: true }))) ?? [];
@@ -8308,6 +7374,15 @@ export async function listStepsHandler(client, args) {
         // THE shared answer — the RPC computes it over the same rows under the
         // same RLS, and what it said is what gets returned (drift rule).
         const upNext = await must(client.rpc('cliv2_steps_up_next', { p_work_item_id: workItemId }));
+        const documentIds = [...new Set(stageRows.filter(stage => stage.source_workflow_ref && stage.source_ref).map(stage => stage.source_ref))];
+        const documents = documentIds.length
+            ? await must(client.from('cliv2_workflow_stages').select('id, body').in('id', documentIds))
+            : [];
+        const stageDocuments = new Map((documents ?? []).map(document => [document.id, document.body]));
+        for (const id of documentIds) {
+            if (!stageDocuments.has(id))
+                throw new Error(`The saved workflow stage ${id} is unavailable.`);
+        }
         const stages = stageRows.map((stage) => ({
             id: stage.id,
             title: stage.title,
@@ -8315,6 +7390,7 @@ export async function listStepsHandler(client, args) {
             source_kind: stage.source_kind,
             source_label: stage.source_label,
             source_ref: stage.source_ref,
+            ...(stage.source_workflow_ref ? { workflow_id: stage.source_workflow_ref, body: stageDocuments.get(stage.source_ref) } : {}),
             steps: stepRows
                 .filter((step) => step.stage_id === stage.id)
                 .map(({ stage_id: _stageId, created_at: _createdAt, ...step }) => step),
@@ -8875,8 +7951,10 @@ export async function buildWorkflowHandler(client, args, fromAgent) {
             if (typeof stage.description === 'string') {
                 prose.push([`stages[${index}].description`, stage.description]);
             }
-            if (typeof stage.body === 'string')
+            if (typeof stage.body === 'string') {
+                assertAgentToolMentions(stage.body);
                 prose.push([`stages[${index}].body`, stage.body]);
+            }
         });
         (Array.isArray(args.exits) ? args.exits : []).forEach((exit, index) => {
             if (typeof exit.condition === 'string') {
@@ -8971,8 +8049,10 @@ export async function editWorkflowHandler(client, args, fromAgent) {
             if (typeof stage.description === 'string') {
                 prose.push([`stages[${index}].description`, stage.description]);
             }
-            if (typeof stage.body === 'string')
+            if (typeof stage.body === 'string') {
+                assertAgentToolMentions(stage.body);
                 prose.push([`stages[${index}].body`, stage.body]);
+            }
         });
         (Array.isArray(args.exits) ? args.exits : []).forEach((exit, index) => {
             if (typeof exit.condition === 'string') {
@@ -9729,7 +8809,7 @@ const SERVER_INSTRUCTIONS = `You are connected to CTRL+SPC, where this user's wo
 
 The terminal conversation disappears when the process does. What you put in CTRL+SPC is what survives.
 
-Everything you write into CTRL+SPC is saved the same way, whichever tool you use. ${FIREWALL_WRITING_RULE}`;
+Everything you write into CTRL+SPC is saved the same way, whichever tool you use. ${FIREWALL_WRITING_RULE}\n\n${WORKFLOW_TOOL_TEACHING}`;
 export function buildToolsServer(client, userId, machineId, connectionId, 
 /** 18c SLICE 1 — the request (`cliv2_loose_todos.id`) this connection is
  *  working, from the connection's own URL rather than a tool argument the
@@ -9814,10 +8894,13 @@ runTodoIdSource = null) {
                 .optional()
                 .describe('From a client intake run: the client this idea came from. The project must be attached to this client, '
                 + 'and the call is refused if it is not.'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return createProductIdeaHandler(client, userId, args);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'create_product_idea', args, async () => {
+            touchSession(connectionId);
+            return createProductIdeaHandler(client, userId, args);
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('get_task', {
         description: 'Read a full task — its tags, comments, artifacts, decisions (so you can read the answers to questions ' +
@@ -9829,7 +8912,9 @@ runTodoIdSource = null) {
             'addressed them; mark rounds resolved with resolve_feedback after revising). ' +
             'Read-only; it has no status or presence side effects. '
             + 'If the item is a Product Idea (pre-backlog, not agreed work), the result carries a product_idea_boundary block — follow it: explore and write artifacts, never implement.',
-        inputSchema: { id: z.string().describe('Task id') },
+        inputSchema: { id: z.string().describe('Task id'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
+        },
     }, async ({ id }) => {
         touchSession(connectionId);
         return getTaskHandler(client, { id });
@@ -9851,6 +8936,7 @@ runTodoIdSource = null) {
             CITATION_LINE_TEACHING + ' ' +
             FIREWALL_WRITING_RULE,
         inputSchema: {
+            workflow_tool_instance: z.string().uuid().optional().describe('The id of this tool mention in the active workflow stage. ' + WORKFLOW_TOOL_TEACHING),
             task_id: z.string(),
             type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe', 'user_story']),
             format: z.enum(['md', 'html', 'json', 'svg']).optional().describe('Defaults to md'),
@@ -9884,18 +8970,10 @@ runTodoIdSource = null) {
     }, async (args) => {
         touchSession(connectionId);
         const artifactArgs = args;
-        return runDirected(client, userId, openSessions.get(connectionId) ?? null, 'create_artifact', artifactArgs, `Write the ${artifactArgs.type} "${artifactArgs.title ?? 'untitled'}"`, artifactArgs.directed_by, artifactArgs.todo_id, 
-        /* 18c Slice 6: the connection's own request id, so the receipt on the
-           finished card can list what this run made. Resolved INSIDE the
-           deferred write, not before it, because runDirected may not call the
-           write at all. */
-        /* 18c Slice 6, gap 4: the session for ATTRIBUTION, which may have ended.
-           The artifact is created either way; what this decides is whether the
-           run that made it is recorded. Saving an artifact is routinely the
-           LAST thing a run does, which is exactly the case gap 4 names. */
-        async () => createArtifactHandler(client, userId, sessionForAttribution(connectionId), args, await runTodoIdOf()), 
-        // 18k Slice 10b — the connection's own run id, for the permission row.
-        await runTodoIdOf());
+        // Resolve attribution inside the write: the gate may stop before it runs,
+        // and a finished session still identifies the run that made the artifact.
+        const write = async () => createArtifactHandler(client, userId, sessionForAttribution(connectionId), artifactArgs, await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'create_artifact', args, write, async () => runDirected(client, userId, openSessions.get(connectionId) ?? null, 'create_artifact', artifactArgs, `Write the ${artifactArgs.type} "${artifactArgs.title ?? 'untitled'}"`, artifactArgs.directed_by, artifactArgs.todo_id, write, await runTodoIdOf()), await runTodoIdOf());
     });
     server.registerTool('attach_screenshot', {
         description: 
@@ -9918,6 +8996,7 @@ runTodoIdSource = null) {
             'and the exact browser/simulator/emulator target. No local path is ever uploaded or ' +
             'stored. Requires an open session (begin_work).',
         inputSchema: {
+            workflow_tool_instance: z.string().uuid().optional().describe('The id of this tool mention in the active workflow stage. ' + WORKFLOW_TOOL_TEACHING),
             url: z
                 .string()
                 .optional()
@@ -9933,9 +9012,9 @@ runTodoIdSource = null) {
         },
     }, async (args) => {
         touchSession(connectionId);
-        return attachScreenshotHandler(client, userId, openSessions.get(connectionId) ?? null, args, 
-        // `deps` left at its default; the request id follows it (18c Slice 6).
-        {}, await runTodoIdOf());
+        // Keep screenshot capture deferred until its workflow approval passes.
+        const write = async () => attachScreenshotHandler(client, userId, openSessions.get(connectionId) ?? null, args, {}, await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'attach_screenshot', args, write, undefined, await runTodoIdOf());
     });
     server.registerTool('update_task', {
         description: "On a Product Idea the description is the human's own thinking: you may write it only while it is EMPTY, and never edit or overwrite one they wrote — put your analysis in an artifact (create_artifact) instead. "
@@ -9957,10 +9036,13 @@ runTodoIdSource = null) {
                 description: z.string().optional(),
                 due_date: z.string().nullable().optional().describe('ISO date, or null to clear'),
             }),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return updateTaskHandler(client, args);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'update_task', args, async () => {
+            touchSession(connectionId);
+            return updateTaskHandler(client, args);
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('update_artifact', {
         description: 'Edit an artifact you can access — its title, content, type, or format. Pass expected_revision from the ' +
@@ -9968,6 +9050,7 @@ runTodoIdSource = null) {
             'The change appears in the web UI. ' +
             FIREWALL_WRITING_RULE,
         inputSchema: {
+            workflow_tool_instance: z.string().uuid().optional().describe('The id of this tool mention in the active workflow stage. ' + WORKFLOW_TOOL_TEACHING),
             id: z.string(),
             expected_revision: z
                 .number()
@@ -9983,7 +9066,7 @@ runTodoIdSource = null) {
         },
     }, async (args) => {
         touchSession(connectionId);
-        return updateArtifactHandler(client, args, await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'update_artifact', args, async () => updateArtifactHandler(client, args, await runTodoIdOf()), undefined, await runTodoIdOf());
     });
     server.registerTool('archive_artifact', {
         description: 'Retire ONE artifact that is genuinely obsolete — superseded by a rewrite, or scrapped because the ' +
@@ -10043,11 +9126,14 @@ runTodoIdSource = null) {
         inputSchema: {
             task_id: z.string().describe('Task id'),
             body: z.string().min(1),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        // 18c Slice 6, gap 4: the session for ATTRIBUTION, which may have ended.
-        return addCommentHandler(client, userId, sessionForAttribution(connectionId), args, await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'add_comment', args, async () => {
+            touchSession(connectionId);
+            // 18c Slice 6, gap 4: the session for ATTRIBUTION, which may have ended.
+            return addCommentHandler(client, userId, sessionForAttribution(connectionId), args, await runTodoIdOf());
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('create_task', {
         // Feature 32: the calibration rule lives HERE (teach-in-the-description
@@ -10074,6 +9160,7 @@ runTodoIdSource = null) {
                 .optional()
                 .describe('Sprint to place the task into — a live sprint of this SAME project (create_sprint)'),
             ...DIRECTED_BY_SCHEMA,
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -10087,8 +9174,7 @@ runTodoIdSource = null) {
     });
     server.registerTool('reorder_backlog', {
         description: "Change the order of a project's backlog, WITH THE USER'S PERMISSION. Board order decides " +
-            'what gets picked up next, so this always asks first and shows them the resulting order: it ' +
-            'is never applied silently, even when they asked for it. Move ONE item at a time, before ' +
+            'what gets picked up next, so it asks first unless this workflow occurrence already permits it. Move ONE item at a time, before ' +
             'another item or to the bottom. Nothing is moved until they approve.',
         inputSchema: {
             project_id: z.string().describe('Project whose backlog is being reordered'),
@@ -10102,6 +9188,7 @@ runTodoIdSource = null) {
                 .min(1)
                 .describe('Why this order is better, in plain words for the user — they are approving a change to ' +
                 'what gets worked on next. e.g. "The session bug blocks the other two auth items."'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -10149,6 +9236,7 @@ runTodoIdSource = null) {
             description: z.string().optional().describe('What the epic is for and how the work under it is cut'),
             start_date: z.string().optional().describe('ISO date (YYYY-MM-DD) — only when the user gave one'),
             target_date: z.string().optional().describe('ISO date (YYYY-MM-DD) — a hope, not an estimate; only when the user gave one'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -10159,9 +9247,7 @@ runTodoIdSource = null) {
            that need it, NOT a change to every tool — there is no shared dispatch
            to hook, each registerTool passes its own closure. */
         const epicArgs = args;
-        return runGated(client, userId, openSessions.get(connectionId) ?? null, 'create_epic', epicArgs, `Create the epic “${epicArgs.name}”`, () => createEpicHandler(client, epicArgs), 
-        // 18k Slice 10b — the run this call belongs to, so approving it resumes the work.
-        await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'create_epic', epicArgs, () => createEpicHandler(client, epicArgs), async () => runGated(client, userId, openSessions.get(connectionId) ?? null, 'create_epic', epicArgs, `Create the epic “${epicArgs.name}”`, () => createEpicHandler(client, epicArgs), await runTodoIdOf()), await runTodoIdOf());
     });
     server.registerTool('create_sprint', {
         description: 'Create a Sprint in a project. For agent-executed work a sprint is an ORDERED BATCH, not a ' +
@@ -10179,6 +9265,7 @@ runTodoIdSource = null) {
             name: z.string().min(1).describe('The batch name — refused if a live sprint already carries it'),
             start_date: z.string().optional().describe('ISO date (YYYY-MM-DD) — only for a real calendar constraint'),
             end_date: z.string().optional().describe('ISO date (YYYY-MM-DD) — only for a real calendar constraint'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -10188,9 +9275,7 @@ runTodoIdSource = null) {
            ruling. `create_task` deliberately does NOT: it is the ordinary class,
            and 4a gives it `directed_by` instead. */
         const sprintArgs = args;
-        return runGated(client, userId, openSessions.get(connectionId) ?? null, 'create_sprint', sprintArgs, `Create the sprint “${sprintArgs.name}”`, () => createSprintHandler(client, sprintArgs), 
-        // 18k Slice 10b — the run this call belongs to, so approving it resumes the work.
-        await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'create_sprint', sprintArgs, () => createSprintHandler(client, sprintArgs), async () => runGated(client, userId, openSessions.get(connectionId) ?? null, 'create_sprint', sprintArgs, `Create the sprint “${sprintArgs.name}”`, () => createSprintHandler(client, sprintArgs), await runTodoIdOf()), await runTodoIdOf());
     });
     /* ═══ !Cleanup PHASE 5 — READ AND MANAGE THE STRUCTURE (I13, I14) ═══ */
     server.registerTool('list_structure', {
@@ -10266,6 +9351,7 @@ runTodoIdSource = null) {
                 .string()
                 .optional()
                 .describe('Place it immediately before this item. Omit to send it to the end'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -10274,7 +9360,7 @@ runTodoIdSource = null) {
            `create_task`'s class, not the project-wide class the ruling names. The
            epic and sprint themselves are unchanged by this — only which one an
            item points at. */
-        return placeWorkItemHandler(client, args);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'place_work_item', args, () => placeWorkItemHandler(client, args), undefined, await runTodoIdOf());
     });
     server.registerTool('begin_work', {
         description: 'Open a work session so the outputs you create afterward are attributed to this run. ' +
@@ -10752,6 +9838,7 @@ runTodoIdSource = null) {
             'best guesses — do not pad the list to cover every possibility, and do not narrow the question just to ' +
             'make your options exhaustive.',
         inputSchema: {
+            workflow_tool_instance: z.string().uuid().optional().describe('The Ask Question mention id. Asking never requires permission.'),
             category: z.string().min(1),
             context: z.string().min(1),
             question: z
@@ -10849,10 +9936,13 @@ runTodoIdSource = null) {
                 .optional()
                 .describe('2..11 competing diagrams, each with a short distinct label (exactly one of html / options; ' +
                 "the labels 'approve' and 'request changes' are reserved)"),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return presentWireframesHandler(client, userId, openSessions.get(connectionId) ?? null, args, await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'present_wireframes', args, async () => {
+            touchSession(connectionId);
+            return presentWireframesHandler(client, userId, openSessions.get(connectionId) ?? null, args, await runTodoIdOf());
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('present_mocks', {
         description: 'Present WORKING, INTERACTIVE HTML mocks to the user for fullscreen review in the web work item — ' +
@@ -10914,10 +10004,13 @@ runTodoIdSource = null) {
                 .optional()
                 .describe('2..11 competing mocks, each self-contained and interactive, with a short distinct label ' +
                 "(exactly one of html / options; the labels 'approve' and 'request changes' are reserved)"),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return presentMocksHandler(client, userId, openSessions.get(connectionId) ?? null, args, await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'present_mocks', args, async () => {
+            touchSession(connectionId);
+            return presentMocksHandler(client, userId, openSessions.get(connectionId) ?? null, args, await runTodoIdOf());
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('resolve_feedback', {
         description: 'Mark feedback rounds resolved after you revised the presented artifact: pass the ids of the rounds the ' +
@@ -10935,10 +10028,13 @@ runTodoIdSource = null) {
                 .int()
                 .positive()
                 .describe('The artifact revision that addressed these rounds (from the update_artifact result)'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return resolveFeedbackHandler(client, openSessions.get(connectionId) ?? null, args);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'resolve_feedback', args, async () => {
+            touchSession(connectionId);
+            return resolveFeedbackHandler(client, openSessions.get(connectionId) ?? null, args);
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('record_user_input', {
         description: "Record the user's answer to an open decision on your work item (e.g. an answer they gave you directly). " +
@@ -10973,10 +10069,13 @@ runTodoIdSource = null) {
             FIREWALL_WRITING_RULE,
         inputSchema: {
             content: z.string().min(1),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return recordContextExplorationHandler(client, userId, openSessions.get(connectionId) ?? null, args, await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'record_context_exploration', args, async () => {
+            touchSession(connectionId);
+            return recordContextExplorationHandler(client, userId, openSessions.get(connectionId) ?? null, args, await runTodoIdOf());
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('reserve_work_paths', {
         /* 18c SLICE 9: THE DESCRIPTION SAYS *BEFORE*, AND SAYS WHERE IT SHOWS.
@@ -11164,6 +10263,7 @@ runTodoIdSource = null) {
                 .array(z.enum(PROJECT_DOCUMENT_TYPES))
                 .optional()
                 .describe('Only these document types; omitted returns every type'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -11180,6 +10280,7 @@ runTodoIdSource = null) {
                 .string()
                 .min(1)
                 .describe('Document id, as the web app’s “Copy for agent” button pastes it'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
         touchSession(connectionId);
@@ -11228,10 +10329,13 @@ runTodoIdSource = null) {
             }))
                 .describe('The proposals from this scan — send `[]` if the repo holds no standing context, which clears ' +
                 'anything an earlier scan left waiting'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return proposeProjectContextHandler(client, openSessions.get(connectionId) ?? null, args);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'propose_project_context', args, async () => {
+            touchSession(connectionId);
+            return proposeProjectContextHandler(client, openSessions.get(connectionId) ?? null, args);
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('list_clients', {
         description: 'List the clients you can see in CTRL+SPC, each with its attached projects. THE ENTRY POINT ' +
@@ -11378,10 +10482,13 @@ runTodoIdSource = null) {
             classification: z.enum(SCOPE_CLASSIFICATIONS),
             evidence: z.string().min(1).describe('The scope.md text you judged this against, quoted'),
             measured_against_version: z.number().int().describe('The approved scope version you read, e.g. 1'),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return proposeScopeChangeHandler(client, args);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'propose_scope_change', args, async () => {
+            touchSession(connectionId);
+            return proposeScopeChangeHandler(client, args);
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('create_stage', {
         description: 'Create a stage, a container in a WORK ITEM\'s step spine ("Implement", ' +
@@ -11450,10 +10557,13 @@ runTodoIdSource = null) {
             source_label: z.string().min(1),
             source_ref: z.string().optional(),
             status: z.enum(STEP_STATUSES).optional().describe("Defaults to 'pending'"),
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
         },
     }, async (args) => {
-        touchSession(connectionId);
-        return createStepHandler(client, args, await runTodoIdOf());
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'create_step', args, async () => {
+            touchSession(connectionId);
+            return createStepHandler(client, args, await runTodoIdOf());
+        }, undefined, await runTodoIdOf());
     });
     server.registerTool('update_step', {
         description: 'THIS IS HOW YOU RECORD PROGRESS ON A STEP. Update the step as things become true — when ' +