@ctrl-spc/cs 0.7.6 → 0.7.8

package/dist/product-tools.js

@@ -0,0 +1,442 @@
+/** Product data operations shared by the terminal and panel. Session lifecycle,
+ * permission questions and agent routing stay with their respective harnesses. */
+import { createHash } from 'node:crypto';
+import { readableWriteError } from './firewall.js';
+import { hostedRemoteIdentity } from './git-remote.js';
+import { ABSOLUTE_PATH_RE } from './local-paths.js';
+export async function must(query) {
+    const { data, error } = await query;
+    if (error)
+        throw new Error(readableWriteError(error.message));
+    return data;
+}
+export const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+export function textResult(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+export function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+export const TASK_PLACEMENT = 'epic:epics(id,name), sprint:sprints(id,name)';
+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)}`);
+    }
+}
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+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}`);
+    }
+}
+export const PROJECT_DOCUMENT_TYPES = ['instructions', 'architecture', 'design', 'conventions', 'other'];
+export const noProjectContextError = (tool) => `${tool} needs to know which project. Call begin_work first, or pass task_id.`;
+export const countCharacters = (text) => /[\uD800-\uDFFF]/.test(text) ? [...text].length : text.length;
+export 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 } };
+}
+export 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 } };
+}
+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)}`);
+    }
+}
+export function shapeDocument(row) {
+    return {
+        title: row.title,
+        ...(row.type ? { type: row.type } : {}),
+        scope: row.codebase_id === null ? 'project' : 'codebase',
+        content: row.content,
+    };
+}
+export const PROPOSAL_SCOPES = ['project', 'codebase'];
+export const MAX_PROPOSAL_TITLE_CHARS = 100;
+export const MAX_PROPOSALS = 50;
+export const MAX_PROPOSAL_BATCH_CHARS = 400_000;
+export const ESCAPING_PATH_RE = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
+export const REVIEW_LOCATION = 'Project settings → Project context';
+export 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,
+        },
+    };
+}
+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)}`);
+    }
+}
+/** 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');
+}

package/dist/workflow-tool-mentions.js

@@ -0,0 +1,93 @@
+/** Shared by the stage editor and both tool servers. The stage body remains
+ * the record: each Markdown link names one invocation, never a tool-wide grant. */
+export const WORKFLOW_TOOLS = [
+    { id: 'create_artifact', name: 'Create Artifact', detail: 'Write a user story, plan, spec, diagram, or interactive mock.', alwaysAllowed: false, advanced: false },
+    { id: 'update_artifact', name: 'Edit Artifact', detail: 'Revise an existing artifact.', alwaysAllowed: false, advanced: false },
+    { id: 'ask_question', name: 'Ask Question', detail: 'Ask for feedback, a decision, or approval. Always available.', alwaysAllowed: true, advanced: false },
+    { id: 'attach_screenshot', name: 'Screenshot', detail: 'Capture a web page and attach the image as an artifact.', alwaysAllowed: false, advanced: false },
+    { id: 'get_task', name: 'Read Work Item', detail: 'Read its description, artifacts, decisions, and feedback.', alwaysAllowed: true, advanced: false },
+    { id: 'get_project_context', name: 'Read Project Context', detail: 'Read project instructions, architecture, design, and conventions.', alwaysAllowed: true, advanced: false },
+    { id: 'get_document', name: 'Read Document', detail: 'Read a project context document or instruction in full.', alwaysAllowed: true, advanced: false },
+    { id: 'present_mocks', name: 'Present Mock', detail: 'Create interactive HTML options and open their design review.', alwaysAllowed: false, advanced: false },
+    { id: 'present_wireframes', name: 'Present Wireframe', detail: 'Create wireframes or diagrams and open their design review.', alwaysAllowed: false, advanced: false },
+    { id: 'create_task', name: 'Create Work Item', detail: 'Turn approved plans into work or capture a follow-up.', alwaysAllowed: false, advanced: false },
+    { id: 'update_task', name: 'Edit Work Item', detail: 'Update the description, name, status, or due date.', alwaysAllowed: false, advanced: false },
+    { id: 'add_comment', name: 'Add Comment', detail: 'Leave a lasting note or handover on a work item.', alwaysAllowed: false, advanced: false },
+    { id: 'record_context_exploration', name: 'Record Findings', detail: 'Save explored context and research on the work item.', alwaysAllowed: false, advanced: false },
+    { id: 'resolve_feedback', name: 'Resolve Feedback', detail: 'Mark feedback addressed after revising the artifact.', alwaysAllowed: false, advanced: false },
+    { id: 'propose_scope_change', name: 'Propose Scope Change', detail: 'Submit a change to approved scope for the user to decide.', alwaysAllowed: false, advanced: false },
+    { id: 'create_product_idea', name: 'Create Product Idea', detail: 'Capture future work without starting implementation.', alwaysAllowed: false, advanced: false },
+    { id: 'create_epic', name: 'Create Epic', detail: 'Group related work items in a project.', alwaysAllowed: false, advanced: true },
+    { id: 'create_sprint', name: 'Create Sprint', detail: 'Create an ordered batch of work.', alwaysAllowed: false, advanced: true },
+    { id: 'place_work_item', name: 'Move Work Item', detail: 'Place work in an epic or sprint, or remove that placement.', alwaysAllowed: false, advanced: true },
+    { id: 'reorder_backlog', name: 'Reorder Backlog', detail: 'Change the order in which backlog work is picked up.', alwaysAllowed: false, advanced: true },
+    { id: 'propose_project_context', name: 'Propose Project Context', detail: 'Submit project guidance for review in Project settings.', alwaysAllowed: false, advanced: true },
+    { id: 'create_step', name: 'Create Execution Step', detail: 'Record a trackable step inside the current workflow stage.', alwaysAllowed: false, advanced: true },
+];
+export function workflowToolAlwaysAllowed(tool) {
+    return WORKFLOW_TOOLS.some(entry => entry.id === tool && entry.alwaysAllowed);
+}
+/** Names differ between harnesses; saved mentions use the same product action. */
+export function workflowToolForName(name) {
+    const canonical = { get_work_item: 'get_task', create_work_item: 'create_task',
+        update_work_item: 'update_task', attach_image_artifact: 'attach_screenshot' }[name] ?? name;
+    return WORKFLOW_TOOLS.find(tool => tool.id === canonical)?.id;
+}
+export function toolMentionText(tool, id, approval = 'required') {
+    const entry = WORKFLOW_TOOLS.find(entry => entry.id === tool);
+    return `[@${entry.name}](ctrl-spc://tool/${tool}/${id}?approval=${workflowToolAlwaysAllowed(tool) ? 'not-required' : approval})`;
+}
+export function toolMentions(body) {
+    const mentions = [];
+    const pattern = /\[@[^\]\n]+\]\(ctrl-spc:\/\/tool\/([a-z_]+)\/([0-9a-f-]{36})\?approval=(required|not-required)\)/g;
+    for (const match of body.matchAll(pattern)) {
+        if (!WORKFLOW_TOOLS.some(entry => entry.id === match[1]))
+            continue;
+        mentions.push({
+            id: match[2], tool: match[1],
+            approval: workflowToolAlwaysAllowed(match[1]) ? 'not-required' : match[3],
+            from: match.index, to: match.index + match[0].length,
+        });
+    }
+    return mentions;
+}
+export function validateToolMentions(body) {
+    const mentions = toolMentions(body);
+    if ((body.match(/ctrl-spc:\/\/tool\//g) ?? []).length !== mentions.length) {
+        throw new Error('A tool mention is incomplete or unsupported. Remove it and insert the tool again with @.');
+    }
+    if (new Set(mentions.map(mention => mention.id)).size !== mentions.length) {
+        throw new Error('Two tool mentions share an identity. Reinsert the copied mention with @ so each use has its own setting.');
+    }
+}
+export function displayToolMentions(body) {
+    let display = body;
+    for (const mention of toolMentions(body).reverse()) {
+        const name = WORKFLOW_TOOLS.find(tool => tool.id === mention.tool).name;
+        const permission = workflowToolAlwaysAllowed(mention.tool) ? 'always allowed'
+            : mention.approval === 'required' ? 'approval required' : 'no approval needed';
+        display = display.slice(0, mention.from) + `**@${name}** (${permission})` + display.slice(mention.to);
+    }
+    return display;
+}
+export const WORKFLOW_TOOL_TEACHING = 'Tool mentions in workflow stage documents are instructions for individual uses. ' +
+    'Pass workflow_tool_instance with the id in that mention when calling the named tool. ' +
+    'Follow the surrounding instruction and stage order; never borrow another mention to bypass approval. ' +
+    'approval=not-required means the user already permits THAT use: perform it without asking again. ' +
+    'approval=required means CALL THE NAMED TOOL with its complete intended arguments and instance id: ' +
+    'the tool itself opens the permission question before writing anything. Do not open a separate ask_question for permission to use that tool. ' +
+    'When the user approves that tool question, retry the same call with exactly the same arguments. Read tools and Ask Question never need permission. Permission does not grant access to another project or change your agent level. If an action is only available to your coordinator, escalate that action with its mention id. ' +
+    'Approval to use a tool is separate from approval of its output: still ask every review question written in the stage. Present Mock and Present Wireframe open their own output review; do not ask a duplicate review question. Proposing a scope or context change never accepts it. ' +
+    'If your level cannot ask the user, escalate the review to the conversation owner and stop.';
+/** Agents may preserve existing settings, but cannot author their own grants. */
+export function assertAgentToolMentions(body, previous = '') {
+    validateToolMentions(body);
+    const before = toolMentions(previous);
+    for (const mention of toolMentions(body)) {
+        if (workflowToolAlwaysAllowed(mention.tool) || mention.approval === 'required')
+            continue;
+        if (!before.some(old => old.id === mention.id && old.tool === mention.tool && old.approval === mention.approval)) {
+            throw new Error('Only the user can turn off approval for a workflow tool mention. Keep approval required and let them change it in Workflows.');
+        }
+    }
+}