@ctrl-spc/cs 0.7.10 → 0.7.12

package/dist/panel3/tools.js

@@ -1,3 +1,5 @@
+import { createEpicHandler, createSprintHandler, listStructureHandler, updateStructureHandler, listStructureArtifactsHandler, getStructureArtifactHandler, searchAgentCardsHandler, createStructureArtifactHandler, updateStructureArtifactHandler } from '../product-tools.js';
+import { listArtifactFoldersHandler, setArtifactFolderHandler, workItemDependencyHandler } from '../product-tools.js';
 /**
  * ═══ AGENT PANEL v3: the tools server, and the per-level allowlist. ═══
  *
@@ -125,11 +127,12 @@ import { returned } from './client.js';
 import { readableWriteError, FIREWALL_WRITING_RULE } from '../firewall.js';
 import { rememberSecret, redactArgs } from './secrets.js';
 import { workBrief } from './prompt.js';
+import { listCodexModels } from './codex-models.js';
 /* The harness this daemon spawns with, which is the process this server runs
    in. It is what `panel3_runs.harness` is written from at spawn, so reading it
    here is the same fact without a second round trip. */
 import { harness } from './spawn.js';
-import { listCodebases } from '../codebases.js';
+import { listCodebases, listWorkItemCodebaseTargets, editWorkItemCodebaseTarget } from '../codebases.js';
 import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage, workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING, WORKFLOW_AUTHORING_TEACHING } from '../workflows.js';
 /* ═══ 38-panel3-steps: THE FIFTH NEUTRAL MODULE, AND A DECISION LIKE THE OTHERS.
    ═══ Stages and steps are the work item's own record, shared by both
@@ -298,10 +301,9 @@ async function asked(caller, args, askPerson) {
         p_question: question,
         p_category: category,
         p_context: context,
-        /* Undefined, not a default: the defaults live in the function signature,
-           so there is one place that says what an unshaped question is. */
-        p_answer_mode: answer_mode,
-        p_options: options,
+        // Token-aware RPC overloads require these arguments, even for a free-text question.
+        p_answer_mode: answer_mode ?? 'free_text',
+        p_options: options ?? [],
         p_question_id: question_id ?? null,
         p_ask_person: askPerson,
         /* ═══ ONLY `ask_question` OFFERS THIS, AND THE DATABASE REFUSES IT ON AN
@@ -789,6 +791,36 @@ const TOOLS = [
             return `Created Product Idea ${a.title}, id ${id}. No work has started. Only a human can promote it.`;
         },
     },
+    {
+        name: 'list_artifact_folders', levels: ALL,
+        description: 'Read existing artifact folder names and counts before choosing a folder.',
+        input: { work_item_id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await listArtifactFoldersHandler(caller.client, args.work_item_id)),
+    },
+    {
+        name: 'set_artifact_folder', levels: ALL,
+        description: 'Move an artifact into one folder, replacing its previous folder. Null clears it to Unfiled. Content and approval stay unchanged.',
+        input: { artifact_id: z.string().uuid(), folder_name: z.string().max(80).nullable() },
+        handler: async (caller, args) => productResult(await setArtifactFolderHandler(caller.client, args.artifact_id, args.folder_name)),
+    },
+    {
+        name: 'list_work_item_dependencies', levels: ALL,
+        description: 'Read blockers, dependents, and whether this work item is waiting.',
+        input: { work_item_id: z.string().uuid(), },
+        handler: async (caller, args) => productResult(await workItemDependencyHandler(caller.client, 'list', args)),
+    },
+    {
+        name: 'add_work_item_dependency', levels: [1, 2],
+        description: 'Make work_item_id wait for depends_on_work_item_id to reach Done. Same-project work items only; self-links and cycles are refused.',
+        input: { work_item_id: z.string().uuid(), depends_on_work_item_id: z.string().uuid(), },
+        handler: async (caller, args) => productResult(await workItemDependencyHandler(caller.client, 'add', args)),
+    },
+    {
+        name: 'remove_work_item_dependency', levels: [1, 2],
+        description: 'Remove exactly this dependency edge without changing either work item status.',
+        input: { work_item_id: z.string().uuid(), depends_on_work_item_id: z.string().uuid(), },
+        handler: async (caller, args) => productResult(await workItemDependencyHandler(caller.client, 'remove', args)),
+    },
     {
         name: 'place_work_item', levels: [1],
         description: 'Move a work item into an epic or sprint in its project. Null removes placement. Its status stays the same.',
@@ -797,13 +829,14 @@ const TOOLS = [
         handler: async (caller, args) => productResult(await placeWorkItemHandler(caller.client, args)),
     },
     {
-        name: 'reorder_backlog', levels: [1],
+        name: 'reorder_backlog', levels: [1, 2],
         description: 'Move one backlog work item before another, or to the bottom. Read the current order first and explain the reason.',
         input: { project_id: z.string().uuid(), task_id: z.string().uuid(), before_task_id: z.string().uuid().optional(), reason: z.string().min(1) },
         handler: async (caller, args) => {
             const a = args;
             const items = await rows(caller.client.from('tasks').select('id, revision')
-                .eq('project_id', a.project_id).eq('status', 'backlog').is('archived_at', null).eq('is_idea', false).order('position').order('created_at').order('id'), 'read', 'the backlog');
+                .eq('project_id', a.project_id).eq('status', 'backlog').is('archived_at', null).eq('is_idea', false)
+                .in('id', a.before_task_id ? [a.task_id, a.before_task_id] : [a.task_id]), 'read', 'the backlog');
             const moving = items.find(item => item.id === a.task_id);
             if (!moving || (a.before_task_id && !items.some(item => item.id === a.before_task_id)))
                 throw new Error('Both items must be live backlog work in this project. Nothing was moved.');
@@ -931,32 +964,44 @@ const TOOLS = [
     {
         name: 'list_work_items',
         levels: ALL,
-        description: 'The work items (tasks) on the board, newest first. Optionally filtered to one project and one '
-            + 'status. Archived items and product ideas are not work items and are not listed.',
+        description: 'Live work items in saved manual board order, top to bottom within each project and status, '
+            + 'not creation order or a temporary UI sort. For backlog priority, pass project_id and status backlog. '
+            + 'Read all pages using next_offset until it is null before reporting the full order. Re-read after a reorder or a human change.',
         input: {
             project_id: z.string().optional().describe('Only items in this project.'),
             status: z.enum(['backlog', 'in_progress', 'done']).optional().describe('Only items in this status.'),
+            offset: z.number().int().min(0).default(0).describe('Use next_offset from the previous page; start at zero.'),
         },
         handler: async ({ client }, args) => {
-            const { project_id, status } = args;
+            const { project_id, status, offset = 0 } = args;
             let query = client
                 .from('tasks')
-                .select('id, name, status, project_id, epic_id, sprint_id, due_date, created_at')
+                .select('id, name, status, project_id, epic_id, sprint_id, due_date, position, created_at', { count: 'exact' })
                 .eq('is_idea', false)
                 .is('archived_at', null)
-                .order('created_at', { ascending: false });
+                .order('project_id').order('status').order('position').order('created_at').order('id');
             if (project_id)
                 query = query.eq('project_id', project_id);
             if (status)
                 query = query.eq('status', status);
-            const items = await rows(query, 'read', 'work items');
-            return listed(items.map((t) => line(t.id, t.status.padEnd(11), t.name, t.due_date ? `due ${t.due_date}` : null)), 'There are no work items matching that.');
+            const result = await query.range(offset, offset + 99);
+            const items = await rows(Promise.resolve(result), 'read', 'work items');
+            if (result.count === null)
+                throw new Error('Could not read the work-item total; the full order is unavailable.');
+            if (items.length === 0 && offset < result.count)
+                throw new Error('Work items changed while reading this page. Restart from offset zero.');
+            return JSON.stringify({
+                order: 'Saved manual board order, top to bottom within each project and status',
+                total: result.count,
+                next_offset: offset + items.length < result.count ? offset + items.length : null,
+                items,
+            });
         },
     },
     {
         name: 'get_work_item',
         levels: ALL,
-        description: 'One work item in full: its description, status, placement, and the artifacts on it.',
+        description: 'One work item in full: description, status, placement, saved codebase targets, available project codebases, and artifacts. Saved targets belong to the work item, not just this conversation.',
         input: { work_item_id: z.string() },
         handler: async ({ client }, args) => {
             const { work_item_id } = args;
@@ -964,11 +1009,15 @@ const TOOLS = [
                 .from('tasks')
                 .select('id, name, description, status, due_date, project_id, created_at, epics(name), sprints(name)')
                 .eq('id', work_item_id), 'read', `work item ${work_item_id}`);
-            const artifacts = await rows(client.from('artifacts').select('id, type, title, created_at').eq('task_id', work_item_id)
+            const artifacts = await rows(client.from('artifacts').select('id, type, title, created_at, folder_name').eq('task_id', work_item_id)
                 .is('deleted_at', null).order('created_at'), 'read', `the artifacts on work item ${work_item_id}`);
             const feedback = await rows(client.from('artifact_feedback').select('*').eq('task_id', work_item_id).order('created_at'), 'read', 'the artifact feedback');
             const decisions = await rows(client.from('decisions').select('id, category, question, state, selected_options, answer_note, related_artifact_id').eq('task_id', work_item_id).order('asked_at'), 'read', 'the work item decisions');
             const comments = await rows(client.from('comments').select('id, body, created_at').eq('task_id', work_item_id).order('created_at'), 'read', 'the work item comments');
+            const codebases = (await listCodebases(client, item.project_id))
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map(({ id, name, gitRemoteUrl }) => ({ id, name, git_remote_url: gitRemoteUrl }));
+            const targets = await listWorkItemCodebaseTargets(client, work_item_id);
             return [
                 `${item.name}`,
                 `id        ${item.id}`,
@@ -977,13 +1026,15 @@ const TOOLS = [
                 `epic      ${item.epics?.name ?? 'none'}`,
                 `sprint    ${item.sprints?.name ?? 'none'}`,
                 `due       ${item.due_date ?? 'no date'}`,
+                'PROJECT CODEBASES', JSON.stringify(codebases),
+                'SAVED CODEBASE TARGETS', JSON.stringify(targets),
                 '',
                 'DESCRIPTION',
                 item.description.trim() === '' ? '(empty)' : item.description,
                 '',
                 'DECISIONS', JSON.stringify(decisions), 'FEEDBACK', JSON.stringify(feedback), 'COMMENTS', JSON.stringify(comments),
                 `ARTIFACTS  ${artifacts.length}`,
-                listed(artifacts.map((a) => line(a.id, a.type, a.title ?? '(untitled)')), 'none'),
+                listed(artifacts.map((a) => line(a.id, a.type, a.title ?? '(untitled)', `folder: ${a.folder_name ?? 'Unfiled'}`)), 'none'),
             ].join('\n');
         },
     },
@@ -1133,10 +1184,15 @@ const TOOLS = [
                 `id        ${workflow.id}`,
                 `about     ${workflow.description.trim() === '' ? 'no description' : workflow.description}`,
                 '',
+                `ending    ${workflow.ending}`,
+                `BRANCH CONDITIONS  ${workflow.branches.length}`,
+                ...workflow.branches.map(branch => `if ${branch.when}, run workflow ${branch.runsWorkflowId}, then resume this workflow`),
+                '',
                 `STAGES  ${workflow.stages.length}`,
                 ...workflow.stages.flatMap((stage, i) => [
                     '',
                     line(`${i + 1}. ${stage.name}`, stage.description.trim() === '' ? null : stage.description),
+                    `stage_id  ${stage.id} (use stage number ${i + 1} for reword_stage and keep)`,
                     '',
                     /* THE WHOLE BODY. The body IS the stage document, so truncating it is
                        truncating the process. An empty one is a stage nobody has written
@@ -1159,8 +1215,9 @@ const TOOLS = [
                         '',
                     ]
                     : []),
-                'This is a WORKFLOW: the process to FOLLOW for this work, stage by stage in the order '
-                    + 'above. It is not a document to summarise, quote back or file away.',
+                'When assigned execution, follow this workflow stage by stage. When assigned authoring '
+                    + 'or review only, edit or inspect it without starting work. Stage IDs above identify '
+                    + 'library stages; IDs inside Markdown tool links identify tool occurrences, not stages.',
             ].join('\n');
         },
     },
@@ -1178,7 +1235,9 @@ const TOOLS = [
             + 'is earlier than N or the same stage; a forward jump is refused and nothing is written. '
             + 'Takes no organisation or project: the workflow goes into the organisation this '
             + "conversation's project belongs to. It appears on /workflows at once. Never put an "
-            + 'absolute local path in any field.',
+            + 'absolute local path in any field. '
+            + 'branches are global conditions: when a condition holds, run runs_workflow_id in the same organisation and resume. '
+            + 'ending is end or next-in-backlog. Omitted settings are preserved on edit; branches: [] clears branches.',
         input: {
             name: z.string(),
             description: z.string().optional(),
@@ -1192,9 +1251,14 @@ const TOOLS = [
                 to_stage: z.number().int(),
                 condition: z.string(),
             })).optional(),
+            branches: z.array(z.object({
+                when: z.string().trim().min(1),
+                runs_workflow_id: z.string().uuid(),
+            })).optional().describe('the whole new branch list; omitted preserves current branches, [] clears them'),
+            ending: z.enum(['end', 'next-in-backlog']).optional(),
         },
         handler: async (caller, args) => {
-            const { name, description, stages, exits } = args;
+            const { name, description, stages, exits, branches, ending } = args;
             /* ═══ CHECKED HERE IN THE NUMBERING THE AGENT SENT. ═══
                `cliv2_build_workflow` enforces every one of these itself, and its
                messages count stages from 0, a numbering this tool never showed the
@@ -1237,6 +1301,8 @@ const TOOLS = [
                     body: stage.body,
                 })),
                 exits: wanted,
+                branches: branches?.map(branch => ({ when: branch.when, runsWorkflowId: branch.runs_workflow_id })),
+                ending,
                 fromAgent: harness(),
             });
             await receipt(caller, 'workflow', id, workflowName);
@@ -1332,8 +1398,12 @@ const TOOLS = [
             + 'must be earlier than from_stage or the same, and exits off one stage are tried in the order '
             + 'sent. name and description left out are left as they are; an empty description clears it. '
             + 'To change the wording of an '
-            + 'existing stage use reword_stage. Refused, with nothing written, while any work item is '
-            + 'running the workflow. Never put an absolute local path in any field.',
+            + 'existing stage use reword_stage first, then keep its stage number here. Read the current '
+            + 'workflow before editing. Never replace a retained stage with a new name/body entry just '
+            + 'to rename it, copy its wording, or bypass a protected-body refusal. Refused, with nothing written, while any work item is '
+            + 'running the workflow. Never put an absolute local path in any field. '
+            + 'branches are global conditions: when a condition holds, run runs_workflow_id in the same organisation and resume. '
+            + 'ending is end or next-in-backlog. Omitted settings are preserved on edit; branches: [] clears branches.',
         input: {
             workflow_id: z.string(),
             name: z.string().optional(),
@@ -1351,9 +1421,14 @@ const TOOLS = [
                 to_stage: z.number().int(),
                 condition: z.string(),
             })).optional().describe('the whole new list of conditional ways back; send [] for none'),
+            branches: z.array(z.object({
+                when: z.string().trim().min(1),
+                runs_workflow_id: z.string().uuid(),
+            })).optional().describe('the whole new branch list; omitted preserves current branches, [] clears them'),
+            ending: z.enum(['end', 'next-in-backlog']).optional(),
         },
         handler: async (caller, args) => {
-            const { workflow_id, name, description, stages, exits } = args;
+            const { workflow_id, name, description, stages, exits, branches, ending } = args;
             const workflowName = name?.trim();
             if (workflowName === '')
                 throw new Error('a workflow needs a name. Nothing was written.');
@@ -1404,10 +1479,8 @@ const TOOLS = [
                 description: description?.trim() ?? null,
                 stages: entries,
                 exits: zeroBasedExits(exits, entries.length),
-                /* THE BRANCHES GO BACK AS THEY CAME. The RPC rewrites them from what it
-                   is sent and nothing in v3 sets one, so sending anything else would
-                   delete what a person set on `/workflows`. */
-                branches: workflow.branches,
+                branches: branches?.map(branch => ({ when: branch.when, runsWorkflowId: branch.runs_workflow_id })) ?? workflow.branches,
+                ending,
                 fromAgent: harness(),
             });
             /* THE LABEL IS THE NAME THAT SURVIVED THE EDIT, which is the reply's own:
@@ -1681,9 +1754,9 @@ const TOOLS = [
         input: { work_item_id: z.string() },
         handler: async ({ client }, args) => {
             const { work_item_id } = args;
-            const artifacts = await rows(client.from('artifacts').select('id, type, format, title, created_at').eq('task_id', work_item_id)
+            const artifacts = await rows(client.from('artifacts').select('id, type, format, title, created_at, folder_name').eq('task_id', work_item_id)
                 .is('deleted_at', null).order('created_at'), 'read', `the artifacts on work item ${work_item_id}`);
-            return listed(artifacts.map((a) => line(a.id, a.type, a.format, a.title ?? '(untitled)')), 'That work item has no artifacts.');
+            return listed(artifacts.map((a) => line(a.id, a.type, a.format, a.title ?? '(untitled)', `folder: ${a.folder_name ?? 'Unfiled'}`)), 'That work item has no artifacts.');
         },
     },
     {
@@ -1694,7 +1767,7 @@ const TOOLS = [
         handler: async ({ client }, args) => {
             const { artifact_id } = args;
             const artifact = await only(client.from('artifacts')
-                .select('id, task_id, type, format, title, content, storage_path, revision, created_at')
+                .select('id, task_id, type, format, title, content, storage_path, revision, created_at, folder_name')
                 .eq('id', artifact_id), 'read', `artifact ${artifact_id}`);
             return [
                 `${artifact.title ?? '(untitled)'}`,
@@ -1702,6 +1775,7 @@ const TOOLS = [
                 `work item    ${artifact.task_id}`,
                 `type         ${artifact.type} (${artifact.format})`,
                 `revision     ${artifact.revision}`,
+                `folder       ${artifact.folder_name ?? 'Unfiled'}`,
                 '',
                 /* A stored file and an empty body are different facts and are said
                    differently. Returning '' for a PNG would read as an artifact with
@@ -1977,7 +2051,8 @@ const TOOLS = [
         levels: [2],
         description: 'Offer the person the ending for this card: put the finished work onto the main branch, or '
             + 'leave it on its branch. Call this when the card\'s work is DONE and the codebase lands on '
-            + 'the main branch. You do not write the question or the answers and you never merge anything: '
+            + 'the main branch. First record verified completion with write_report(work_complete=true). '
+            + 'Use say for progress; this tool cannot announce work you intend to do. You do not write the question or the answers and you never merge anything: '
             + 'the product composes both, and it performs the merge itself if they choose to put the work '
             + 'back. Say in one sentence what was done, in their words. After this call, stop immediately: '
             + 'you are started again with what the product did with their answer.',
@@ -1997,8 +2072,13 @@ const TOOLS = [
                     + 'sentence saying what changed.');
             }
             const run = await only(client.from('panel3_runs')
-                .select('codebase_id, branch, base, card:panel3_cards!panel3_runs_card_id_fkey(project_id)')
+                .select('codebase_id, branch, base, completion_requested_token, card:panel3_cards!panel3_runs_card_id_fkey(project_id)')
                 .eq('id', runId), 'read', 'which branch this card\'s work is on');
+            if (run.completion_requested_token !== processToken) {
+                throw new Error('NOTHING WAS WRITTEN and nobody was asked. The assignment has not been declared complete in this turn. '
+                    + 'Finish and verify every requested codebase first, then call write_report with work_complete=true before offer_ending. '
+                    + 'Use say for a progress update, not offer_ending.');
+            }
             if (!run.codebase_id || !run.branch || !run.base || !run.card?.project_id) {
                 throw new Error('NOTHING WAS WRITTEN. This card has no codebase, branch and base recorded, so there is no '
                     + 'ending to offer. Say what you did and finish the card.');
@@ -2048,34 +2128,65 @@ const TOOLS = [
         },
     },
     {
-        name: 'create_epic',
-        levels: [1],
-        description: 'Create an epic in a project. An epic groups work items that belong to one body of work.',
-        input: { project_id: z.string(), name: z.string().min(1) },
+        name: 'create_epic', levels: [1, 2],
+        description: 'Create an epic with optional description and dates. Read list_structure first to avoid duplicates.',
+        input: { project_id: z.string().uuid(), name: z.string().min(1), description: z.string().optional(), start_date: z.string().optional(), target_date: z.string().optional() },
         handler: async (caller, args) => {
-            const { project_id, name } = args;
-            const epic = await only(caller.client.from('epics').insert({ project_id, name }).select('id, name'), 'create', `an epic called ${name}`);
-            await receipt(caller, 'epic', epic.id, epic.name);
-            return `Created epic ${epic.name}, id ${epic.id}.`;
+            const text = productResult(await createEpicHandler(caller.client, args));
+            const row = JSON.parse(text).epic;
+            await receipt(caller, 'epic', row.id, row.name);
+            return text;
         },
     },
     {
-        name: 'create_sprint',
-        levels: [1],
-        description: 'Create an ordered batch of work in a project. Dates are optional; use them only for a stated calendar constraint.',
-        input: {
-            project_id: z.string(),
-            name: z.string().min(1),
-            start_date: z.string().optional().describe('YYYY-MM-DD'),
-            end_date: z.string().optional().describe('YYYY-MM-DD'),
-        },
+        name: 'create_sprint', levels: [1, 2],
+        description: 'Create an sprint with optional description and dates. Read list_structure first to avoid duplicates.',
+        input: { project_id: z.string().uuid(), name: z.string().min(1), description: z.string().optional(), start_date: z.string().optional(), end_date: z.string().optional() },
         handler: async (caller, args) => {
-            const { project_id, name, start_date, end_date } = args;
-            const sprint = await only(caller.client.from('sprints').insert({ project_id, name, start_date, end_date }).select('id, name'), 'create', `a sprint called ${name}`);
-            await receipt(caller, 'sprint', sprint.id, sprint.name);
-            return `Created sprint ${sprint.name}, id ${sprint.id}.`;
+            const text = productResult(await createSprintHandler(caller.client, args));
+            const row = JSON.parse(text).sprint;
+            await receipt(caller, 'sprint', row.id, row.name);
+            return text;
         },
     },
+    {
+        name: 'list_structure', levels: ALL,
+        description: 'Read project epics and sprints with their descriptions and dates.',
+        input: { project_id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await listStructureHandler(caller.client, { project_id: args.project_id })),
+    },
+    {
+        name: 'update_structure', levels: [1, 2],
+        description: 'Edit an epic or sprint name, description, dates, or archive state. Null clears a date. Epics use target_date; sprints use end_date.',
+        input: { kind: z.enum(['epic', 'sprint']), id: z.string().uuid(), name: z.string().min(1).optional(), description: z.string().optional(), start_date: z.string().nullable().optional(), end_date: z.string().nullable().optional(), target_date: z.string().nullable().optional(), archived: z.boolean().optional() },
+        handler: async (caller, args) => productResult(await updateStructureHandler(caller.client, args)),
+    },
+    {
+        name: 'search_agent_cards', levels: ALL,
+        description: 'Find your agent conversations by literal title or message text, or by work item. Includes archived cards unless specified. Follow next_offset for remaining results. Read-only.',
+        input: { query: z.string().max(500).optional(), work_item_id: z.string().uuid().optional(), archived: z.boolean().optional(), limit: z.number().int().min(1).max(1000).optional(), offset: z.number().int().min(0).optional() },
+        handler: async (caller, args) => productResult(await searchAgentCardsHandler(caller.client, args)),
+    },
+    {
+        name: 'list_structure_artifacts', levels: ALL, description: 'Read active artifacts attached directly to an epic or sprint.',
+        input: { kind: z.enum(['epic', 'sprint']), structure_id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await listStructureArtifactsHandler(caller.client, args.kind, args.structure_id)),
+    },
+    {
+        name: 'get_structure_artifact', levels: ALL, description: 'Read a full epic or sprint artifact and its current revision.',
+        input: { artifact_id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await getStructureArtifactHandler(caller.client, args.artifact_id)),
+    },
+    {
+        name: 'create_structure_artifact', levels: ALL, description: 'Create a titled artifact on an epic or sprint. It appears on its management page.',
+        input: { kind: z.enum(['epic', 'sprint']), structure_id: z.string().uuid(), title: z.string().min(1).max(200), type: z.enum(['analysis', 'plan', 'spec', 'user_story', 'diagram', 'mock', 'wireframe']), format: z.enum(['md', 'html', 'json', 'svg']).optional(), content: z.string().min(1) },
+        handler: async (caller, args) => { const text = productResult(await createStructureArtifactHandler(caller.client, caller.userId, args)); const result = JSON.parse(text); await receipt(caller, result.kind, result.structure.id, result.structure.name); return text; },
+    },
+    {
+        name: 'update_structure_artifact', levels: ALL, description: 'Update an epic or sprint artifact using the revision you read. Concurrent edits refuse without overwriting. archived=true removes it; false restores it.',
+        input: { artifact_id: z.string().uuid(), expected_revision: z.number().int().positive(), title: z.string().min(1).max(200).optional(), type: z.enum(['analysis', 'plan', 'spec', 'user_story', 'diagram', 'mock', 'wireframe']).optional(), format: z.enum(['md', 'html', 'json', 'svg']).optional(), content: z.string().optional(), archived: z.boolean().optional() },
+        handler: async (caller, args) => productResult(await updateStructureArtifactHandler(caller.client, args)),
+    },
     {
         name: 'create_work_item',
         levels: [1],
@@ -2110,6 +2221,20 @@ const TOOLS = [
             return `Created work item ${item.name}, id ${item.id}.`;
         },
     },
+    {
+        name: 'edit_work_item_codebase',
+        levels: [1, 2],
+        description: 'Add or remove one SAVED work-item codebase target, preserving all other targets and attributes. Read get_work_item first for current targets and project codebase IDs. To select multiple codebases, add each; to replace a target, add its replacement before removing it. Duplicate additions are harmless. Re-read after edits or human changes. This edits the work item itself and provides an Open work item receipt; it does not attach to the conversation or execute files.',
+        input: { work_item_id: z.string().uuid(), codebase_id: z.string().uuid(), action: z.enum(['add', 'remove']) },
+        handler: async (caller, args) => {
+            const a = args;
+            const item = await only(caller.client.from('tasks')
+                .select('id, name, project_id').eq('id', a.work_item_id), 'read', 'the work item');
+            const targets = await editWorkItemCodebaseTarget(caller.client, item.id, item.project_id, a.codebase_id, a.action === 'add');
+            await receiptOnce(caller, 'work_item', item.id, item.name);
+            return JSON.stringify({ work_item_id: item.id, saved_codebase_targets: targets });
+        },
+    },
     // ── Do the work, and produce objects ─────────────────────────────────────
     //
     // ═══ EVERY LEVEL, AND THAT IS ux.md's FOURTH RULE. ═══ "Producing an object
@@ -2178,6 +2303,7 @@ const TOOLS = [
             + FIREWALL_WRITING_RULE,
         input: {
             work_item_id: z.string(),
+            folder_name: z.string().max(80).nullable().optional().describe('Read list_artifact_folders first to reuse a folder.'),
             title: z.string().min(1),
             content: z.string().min(1),
             type: z.enum(['plan', 'spec', 'analysis', 'diagram', 'mock', 'wireframe', 'user_story']).optional(),
@@ -2187,6 +2313,7 @@ const TOOLS = [
             const a = args;
             const artifact = await only(caller.client.from('artifacts').insert({
                 task_id: a.work_item_id,
+                folder_name: a.folder_name ?? null,
                 title: a.title,
                 content: a.content,
                 type: a.type ?? 'plan',
@@ -2697,7 +2824,7 @@ const TOOLS = [
                 await whileRunning(client.rpc('panel3_request_completion', {
                     p_run_id: runId, p_process_token: processToken, p_summary: report,
                 }), runId, 'declare completion of');
-                return 'Completion recorded. Give your final answer and exit. Done waits until all processes have exited.';
+                return 'Completion recorded. If the finished work needs an ending choice, call offer_ending; otherwise give your final answer and exit. Done waits until all processes have exited.';
             }
             await whileRunning(processToken === undefined
                 ? client.from('panel3_runs').update({ report }).eq('id', runId)
@@ -2863,6 +2990,13 @@ const TOOLS = [
         },
     },
     // ── Dispatch and stop ────────────────────────────────────────────────────
+    {
+        name: 'list_codex_models',
+        levels: [1, 2],
+        description: 'Read the models and reasoning efforts currently offered by the installed Codex harness on this machine. Call before choosing a Codex child model yourself. This is discovery, not an allowlist for explicit user model IDs or aliases. If discovery fails, omit autonomous model/effort choices to use the installed defaults; never guess an identifier.',
+        input: {},
+        handler: async () => JSON.stringify(await listCodexModels()),
+    },
     {
         name: 'dispatch',
         /* ═══ ABSENT AT LEVEL 3, WHICH IS HOW "DEPTH STOPS AT THREE" IS ENFORCED.
@@ -2896,7 +3030,7 @@ const TOOLS = [
                 + 'context: what to find out or change, and in which part of the codebase.'),
             boundary: z.string().min(1).describe('What it must not touch, and where its work stops.'),
             work_item_id: z.string().optional().describe('The work item it is working, if there is one.'),
-            model: z.string().min(1).optional().describe('Exact model for this child. Copy the user\'s applicable value verbatim, including aliases; never expand or normalize it. Otherwise choose for the task. Omit for the harness or machine default, never parent inheritance.'),
+            model: z.string().min(1).refine(value => !/^(?:codex|claude(?: code)?)(?:\s|$)/i.test(value.trim()), 'Use only the model ID, without the Claude or Codex harness label. Omit model to use the installed default.').optional().describe('Exact model for this child. Copy the user\'s applicable value verbatim, including aliases; never expand or normalize it. Otherwise choose for the task: for Claude, prefer supported unversioned aliases such as sonnet or opus; do not invent version-suffixed aliases. For Codex, first call list_codex_models and choose from its result. If uncertain, omit for the harness or machine default, never parent inheritance.'),
             effort: z.string().min(1).optional().describe('Exact effort for this child. Honor the user\'s applicable wish; otherwise choose independently. Passed unchanged to the harness.'),
             work_name: z.string().optional().describe(`A few words, ${WORK_NAME_WORDS} at most, naming the WORK this conversation is doing, such `
                 + 'as "Fix the sign-out checklist bug". Pass it when the conversation has NO work item '
@@ -2926,6 +3060,9 @@ const TOOLS = [
                         + 'the work, do not describe it.');
                 }
             }
+            const attached = await loadAttachments(caller.client, caller.cardId);
+            const workItems = attached.filter(attachment => attachment.kind === 'work_item');
+            const scopedWorkItem = work_item_id ?? (workItems.length === 1 ? workItems[0].ref_id : undefined);
             let codebase = null;
             if (codebase_id) {
                 const projectId = await projectOfCard(caller);
@@ -2937,6 +3074,19 @@ const TOOLS = [
                 if (!codebase) {
                     throw new Error('That codebase is not registered on this project. Read the current project codebases and choose one of them.');
                 }
+                if (!scopedWorkItem && workItems.length > 1) {
+                    throw new Error('No agent was started. Identify the work item for this piece before choosing its codebase.');
+                }
+                if (scopedWorkItem) {
+                    await only(caller.client.from('tasks').select('id').eq('id', scopedWorkItem)
+                        .eq('project_id', projectId).is('archived_at', null).eq('is_idea', false), 'read', 'the live work item in this conversation\'s project');
+                    const targets = await listWorkItemCodebaseTargets(caller.client, scopedWorkItem);
+                    if (!targets.includes(codebase.gitRemoteUrl)) {
+                        throw new Error('No agent was started. This codebase is not a saved target of the work item. '
+                            + 'Read get_work_item for its current saved targets; if none are saved, ask the person to select one. '
+                            + 'Do not fall back to another project codebase or change targets to bypass this check.');
+                    }
+                }
             }
             /* ONE LEVEL DOWN, AND THE SAME ARITHMETIC THE DATABASE DOES. This decides
                the words in the brief; `panel3_dispatch` decides the level on the row,
@@ -2951,7 +3101,6 @@ const TOOLS = [
                three hops from level 1 still knows which item it is working, without
                asking. See `workBrief`'s own doc for why the two are different things
                carried the same way. */
-            const attached = await loadAttachments(caller.client, caller.cardId);
             /* ═══ THE CONVERSATION IS NAMED HERE OR IT IS NEVER NAMED. ═══ Sending
                somebody resolves the working copy, and resolving it cuts the branch
                from whatever the conversation is called at that moment and stamps it
@@ -2966,7 +3115,7 @@ const TOOLS = [
                     .select('id'), 'name', `card ${caller.cardId}`);
             }
             const attachments = attached.map(attachmentLine);
-            const { runId } = await caller.dispatch(caller.runId, workBrief(childLevel, responsibility, boundary, work_item_id, attachments, codebase === null ? undefined : {
+            const { runId } = await caller.dispatch(caller.runId, workBrief(childLevel, responsibility, boundary, scopedWorkItem, attachments, codebase === null ? undefined : {
                 id: codebase.id, name: codebase.name, identity: codebase.gitRemoteUrl,
             }), codebase, caller.processToken, { model, effort });
             /* ═══ WHERE ITS ANSWER GOES DEPENDS ON WHICH LEVEL THIS IS, AND THAT IS