archgen-mcp 0.0.6 → 0.0.7

package/src/core/ui-channel.mjs

@@ -21,7 +21,7 @@
 // EVERY UI ACTION IS BEST-EFFORT: with no extension running the tool returns
 // `{available:false}` and the agent's work continues. UI control never
 // blocks a task.
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { writeFileAtomic } from './fs-safety.mjs';
@@ -121,7 +121,8 @@ export async function sendUiCommand(projectRoot, toolAction, args = {}, opts = {
     expiresAt: new Date(Date.now() + CMD_TTL_MS).toISOString(),
   };
 
-  writeFileAtomic(cmdPath, JSON.stringify(command, null, 2) + '\n');
+  writeFileAtomic(cmdPath, JSON.stringify(command, null, 2) + '\n', { root: projectRoot });
+  pruneQueue(runtime);
 
   const timeoutMs = Math.min(opts.timeoutMs ?? DEFAULT_ACK_TIMEOUT_MS, MAX_ACK_TIMEOUT_MS);
   const deadline = Date.now() + timeoutMs;
@@ -153,12 +154,62 @@ export async function sendUiCommand(projectRoot, toolAction, args = {}, opts = {
   };
 }
 
+/**
+ * Prune the command and acknowledgement queues.
+ *
+ * The queues are a channel, not an archive. Every command the server writes
+ * is eventually acknowledged (or expires), and the extension leaves the file
+ * in place — so without a prune the directory grows for the life of the
+ * project, and every status call reads the whole directory.
+ *
+ * Entries are removed by AGE (anything older than the command TTL is dead
+ * either way) and the newest N are kept, so the queue is bounded by
+ * construction rather than by hope.
+ *
+ * @param {string} runtime the `.archgen/.runtime` directory
+ */
+export function pruneQueue(runtime, { maxEntries = 200, maxAgeMs = CMD_TTL_MS * 4 } = {}) {
+  const cmdDir = join(runtime, 'cmd');
+  const ackDir = join(runtime, 'ack');
+  const now = Date.now();
+  for (const dir of [cmdDir, ackDir]) {
+    if (!existsSync(dir)) continue;
+    let names;
+    try {
+      names = readdirSync(dir).filter((n) => n.endsWith('.json'));
+    } catch {
+      continue;
+    }
+    const kept = [];
+    for (const name of names) {
+      const abs = join(dir, name);
+      try {
+        const age = now - statSync(abs).mtimeMs;
+        if (age > maxAgeMs) {
+          unlinkSync(abs);
+          continue;
+        }
+        kept.push({ abs, mtime: statSync(abs).mtimeMs });
+      } catch {
+        /* vanished between the listing and the stat */
+      }
+    }
+    kept.sort((a, b) => b.mtime - a.mtime);
+    for (const { abs } of kept.slice(maxEntries)) {
+      try {
+        unlinkSync(abs);
+      } catch {
+        /* another process pruned it first */
+      }
+    }
+  }
+}
+
 /**
  * List pending (unacknowledged) commands — diagnostics.
  * @param {string} projectRoot
  */
-export function pendingUiCommands(projectRoot) {
-  const dir = join(projectRoot, RUNTIME_DIR, 'cmd');
+export function pendingUiCommands(projectRoot) {  const dir = join(projectRoot, RUNTIME_DIR, 'cmd');
   if (!existsSync(dir)) return [];
   const out = [];
   for (const name of readdirSync(dir)) {

package/src/core/validator.mjs

@@ -12,7 +12,7 @@ import { readFileSync } from 'node:fs';
 import { parseYaml } from './yaml.mjs';
 import { buildGraph, findCycle, GraphError } from './graph.mjs';
 import { checkPlanCoverage } from './plan-coverage.mjs';
-import { invalidInput } from './errors.mjs';
+import { invalidInput, ArchgenError } from './errors.mjs';
 
 export const STATUSES = ['pending', 'ready', 'running', 'blocked', 'done', 'failed'];
 export const REQUIRED = ['id', 'title', 'file_ownership'];
@@ -37,7 +37,20 @@ export function validateTasksYaml(file, opts = {}) {
   const errors = [];
   const warnings = [];
 
-  const raw = readFileSync(file, 'utf8');
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (e) {
+    // A missing or unreadable file is NOT an internal error. The agent is
+    // told to branch on the code, and "the file is not there" is a fact it
+    // can act on — an INTERNAL tells it nothing and hides which path failed.
+    const code = e?.code === 'ENOENT' ? 'NOT_FOUND' : 'INVALID_INPUT';
+    throw new ArchgenError(
+      code,
+      `${code === 'NOT_FOUND' ? 'tasks file not found' : `cannot read tasks file`}: ${file}`,
+      { file },
+    );
+  }
   let data;
   try {
     ({ data } = parseYaml(raw, { filename: file }));
@@ -96,7 +109,7 @@ export function validateTasksYaml(file, opts = {}) {
 
   if (planDir) {
     // Delegate plan<->task coverage checks to the single shared implementation.
-    for (const f of checkPlanCoverage(planDir, tasks)) errors.push(f);
+    for (const f of checkPlanCoverage(planDir, tasks).findings) errors.push(f);
   }
 
   return {

package/src/core/verifier.mjs

@@ -61,7 +61,7 @@ export function verifyPlan(file, planDir) {
         }
       }
 
-      issues.push(...checkPlanCoverage(planDir, tasks));
+      issues.push(...checkPlanCoverage(planDir, tasks).findings);
     } catch (e) {
       if (e instanceof GraphError) issues.push(e.message);
       else issues.push(`internal check failure: ${e?.message ?? String(e)}`);
@@ -86,20 +86,14 @@ export function planCoverage(file, planDir) {
     return { covered: [], uncovered: [], findings: [`unparseable tasks.yaml: ${e.message}`] };
   }
   const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
-  const findings = checkPlanCoverage(planDir, tasks);
+  const { findings, referenced, mentionedInTasks } = checkPlanCoverage(planDir, tasks);
   const covered = [];
   const uncovered = [];
   for (const t of tasks) {
     const id = String(t?.id ?? '');
     if (!id) continue;
-    const mentioned = findings.some((f) => f.includes(id)) || tasks.some((x) => x?.id !== id && mentions(x, id));
+    const mentioned = referenced.has(id) || mentionedInTasks.has(id);
     (mentioned ? covered : uncovered).push(id);
   }
   return { covered, uncovered, findings };
 }
-
-/** Does any task reference `id` in its artifacts / acceptance text? */
-function mentions(task, id) {
-  const hay = JSON.stringify([task?.artifacts ?? [], task?.acceptance ?? [], task?.title ?? '']);
-  return hay.includes(id);
-}

package/src/core/worker-contract.mjs

@@ -13,7 +13,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseYaml } from './yaml.mjs';
-import { buildGraph } from './graph.mjs';
+import { buildGraph, GraphError } from './graph.mjs';
 import { invalidInput, notFound } from './errors.mjs';
 
 /**
@@ -50,7 +50,21 @@ export function buildWorkerContract(opts) {
 
   // The dependency neighbourhood — what must exist BEFORE this task, and what
   // waits on it. Derived from depends_on, never hand-labelled.
-  const { byId, prerequisites, dependents } = buildGraph(tasks);
+  //
+  // A broken graph (a duplicate id, a dangling depends_on) is a PLAN defect,
+  // not an internal error. The agent branches on the code, so it is mapped
+  // to the same typed codes the other plan tools use.
+  let byId;
+  let prerequisites;
+  let dependents;
+  try {
+    ({ byId, prerequisites, dependents } = buildGraph(tasks));
+  } catch (e) {
+    if (e instanceof GraphError) {
+      throw invalidInput(`${tasksYaml}: ${e.message}`, { file: tasksYaml });
+    }
+    throw e;
+  }
   const upstream = (prerequisites.get(taskId) ?? []).map((id) => ({ id, title: byId.get(id)?.title ?? null }));
   const downstream = (dependents.get(taskId) ?? []).map((id) => ({ id, title: byId.get(id)?.title ?? null }));
 

package/src/core/yaml.mjs

@@ -105,7 +105,7 @@ function peekContent(lines, pos, indent) {
     if (c.type === 'blank') { i++; continue; }
     if (c.type === 'comment') { i++; continue; } // handled by caller via pendingComments
     if (c.indent < indent) return null;
-    if (c.indent > indent) fail({ filename: 'internal' }, i + 1, `unexpected deeper indentation (got ${c.indent}, expected ${indent})`);
+    if (c.indent > indent) fail(ctx, i + 1, `unexpected deeper indentation (got ${c.indent}, expected ${indent})`);
     return { idx: i, line: c };
   }
   return null;
@@ -432,6 +432,31 @@ function samePath(a, b) {
   return true;
 }
 
+/**
+ * Encode a mapping key.
+ *
+ * Keys are written the way VALUES are written: quoted whenever a plain key
+ * would be misread. A key containing ": ", starting with a YAML indicator,
+ * or looking like a number or a keyword is quoted, so the file the emitter
+ * writes always parses back to the key it was given.
+ *
+ * Without this, a key like `odd: key` was emitted verbatim and produced a
+ * file that no longer parsed — and a single `set_status` could destroy the
+ * plan it was updating.
+ */
+function encodeKey(k) {
+  const s = String(k);
+  if (s === '') return '""';
+  if (
+    /^[A-Za-z_][A-Za-z0-9_-]*$/.test(s) &&
+    !/^(true|false|null|yes|no|on|off)$/i.test(s) &&
+    !/^-?\d+(\.\d+)?$/.test(s)
+  ) {
+    return s;
+  }
+  return JSON.stringify(s);
+}
+
 function emitValue(out, v, indent, comments, used, path) {
   const pad = ' '.repeat(indent);
   if (Array.isArray(v)) {
@@ -450,7 +475,7 @@ function emitValue(out, v, indent, comments, used, path) {
         const [k0, v0] = entries[0];
         const k0path = [...itemPath, k0];
         preComments(out, comments, used, k0path);
-        out.push(pad + '- ' + k0 + ': ' + encodeScalar(v0));
+        out.push(pad + '- ' + encodeKey(k0) + ': ' + encodeScalar(v0));
         inlineCommentFor(out, comments, used, k0path);
         emitEntries(out, entries.slice(1), indent + INDENT_UNIT, comments, used, itemPath);
       } else {
@@ -473,13 +498,13 @@ function emitEntries(out, entries, indent, comments, used, basePath) {
     const kpath = [...basePath, k];
     preComments(out, comments, used, kpath);
     if (val !== null && typeof val === 'object') {
-      if (Object.keys(val).length === 0 && !Array.isArray(val)) { out.push(pad + k + ': {}'); inlineCommentFor(out, comments, used, kpath); continue; }
-      if (Array.isArray(val) && val.length === 0) { out.push(pad + k + ': []'); inlineCommentFor(out, comments, used, kpath); continue; }
-      out.push(pad + k + ':');
+      if (Object.keys(val).length === 0 && !Array.isArray(val)) { out.push(pad + encodeKey(k) + ': {}'); inlineCommentFor(out, comments, used, kpath); continue; }
+      if (Array.isArray(val) && val.length === 0) { out.push(pad + encodeKey(k) + ': []'); inlineCommentFor(out, comments, used, kpath); continue; }
+      out.push(pad + encodeKey(k) + ':');
       inlineCommentFor(out, comments, used, kpath);
       emitValue(out, val, indent + INDENT_UNIT, comments, used, kpath);
     } else {
-      out.push(pad + k + ': ' + encodeScalar(val));
+      out.push(pad + encodeKey(k) + ': ' + encodeScalar(val));
       inlineCommentFor(out, comments, used, kpath);
     }
   }

package/src/tools/_register.mjs

@@ -82,14 +82,15 @@ export function registerTool(server, name, spec) {
       },
     },
     async (args, extra) => {
-      // A tool may target a project other than the server's cwd (a monorepo
-      // package, a worktree). The projectRoot argument wins; otherwise the
-      // server-level context applies.
+      // A tool may target a directory inside the project (a monorepo package,
+      // a worktree under it). The projectRoot argument SELECTS one; it does
+      // not define the boundary. The server's anchor does, and a selection
+      // outside it is refused with PERMISSION_DENIED.
       const base = extra?.archgenContext ?? serverContext();
       const requested = args?.projectRoot;
       const ctx =
         typeof requested === 'string' && requested.trim() !== ''
-          ? new Context({ projectRoot: requested, env: base.env, home: base.home })
+          ? base.withProjectRoot(requested)
           : base;
       const envelope = await guard(spec.handler, ctx, args ?? {});
       return toToolResult(envelope);

package/src/tools/codegraph.mjs

@@ -16,7 +16,6 @@ const schema = z.object({
   location: z.enum(['project', 'global', 'both']).optional().describe('Which scope to wire. Defaults to both.'),
   approve: z.boolean().optional().describe('Required to write any MCP config. Without it you get the plan and nothing is written.'),
   telemetry: z.enum(['keep', 'off', 'on']).optional().describe('Telemetry preference. Defaults to keep (leave as-is).'),
-  noUpgrade: z.boolean().optional().describe('Do not upgrade an existing CodeGraph CLI.'),
   noInstall: z.boolean().optional().describe('Do not install the CLI; use the npx fallback in configs.'),
   projectRoot: projectRootArg,
 });
@@ -45,7 +44,6 @@ export function registerCodegraphTools(server) {
         location,
         approved: args.approve === true,
         telemetry: args.telemetry ?? 'keep',
-        noUpgrade: args.noUpgrade === true,
         noInstall: args.noInstall === true,
         home: ctx.home,
         env: ctx.env,

package/src/tools/docs.mjs

@@ -37,20 +37,20 @@ export function registerDocTools(server) {
       const slugDir = resolveSlugDir(ctx, args.slugDir);
       switch (args.action) {
         case 'index':
-          return docIndex(slugDir, { mode: 'overview', file: args.file ?? null });
+          return docIndex(slugDir, { mode: 'overview', file: args.file ?? null, projectRoot: ctx.projectRoot });
         case 'digest':
-          return docIndex(slugDir, { mode: 'digest', file: args.file ?? null });
+          return docIndex(slugDir, { mode: 'digest', file: args.file ?? null, projectRoot: ctx.projectRoot });
         case 'validate':
-          return docIndex(slugDir, { mode: 'validate', file: args.file ?? null });
+          return docIndex(slugDir, { mode: 'validate', file: args.file ?? null, projectRoot: ctx.projectRoot });
         case 'refs':
           if (!args.token) throw invalidInput('refs requires a token', { action: args.action });
-          return docIndex(slugDir, { mode: 'refs', token: args.token, file: args.file ?? null });
+          return docIndex(slugDir, { mode: 'refs', token: args.token, file: args.file ?? null, projectRoot: ctx.projectRoot });
         case 'map':
           if (!args.token) throw invalidInput('map requires a token', { action: args.action });
-          return docIndex(slugDir, { mode: 'map', token: args.token, file: args.file ?? null });
+          return docIndex(slugDir, { mode: 'map', token: args.token, file: args.file ?? null, projectRoot: ctx.projectRoot });
         case 'section':
           if (!args.section) throw invalidInput('section requires a section path', { action: args.action });
-          return docIndex(slugDir, { mode: 'section', section: args.section, file: args.file ?? null });
+          return docIndex(slugDir, { mode: 'section', section: args.section, file: args.file ?? null, projectRoot: ctx.projectRoot });
         default:
           throw invalidInput(`unknown action '${args.action}'`, { action: args.action });
       }

package/src/tools/help.mjs

@@ -134,7 +134,7 @@ Installs, wires and indexes CodeGraph — the source-symbol index — and its ow
 **Actions**
 | action | what it does | required args |
 |---|---|---|
-| \`ensure\` | install/upgrade the CLI + wire the MCP + build the index | projectRoot?, approve? |
+| \`ensure\` | install the CLI if missing + wire the MCP + build the index | projectRoot?, approve? |
 | \`status\` | what is installed / wired / indexed (read-only) | projectRoot? |
 | \`wire\` | wire the MCP into detected harnesses only | projectRoot?, approve? |
 

package/src/tools/plan.mjs

@@ -6,9 +6,9 @@
 // "which one do I call?" confusion the whole MCP exercise exists to fix.
 import { z } from 'zod/v4';
 import { registerTool, projectRootArg } from './_register.mjs';
-import { loadAsset, BRIEFS_DIR, TEMPLATES_DIR } from '../context.mjs';
+import { loadAsset, BRIEFS_DIR, TEMPLATES_DIR, serverVersion } from '../context.mjs';
 import { buildScaffold } from '../core/scaffold.mjs';
-import { loadBrief, BRIEF_KINDS } from '../core/briefs.mjs';
+import { loadBrief, remainingPlaceholders, BRIEF_KINDS } from '../core/briefs.mjs';
 import { validateTasksYaml } from '../core/validator.mjs';
 import { verifyPlan, planCoverage } from '../core/verifier.mjs';
 import { planGraph } from '../core/plan-grapher.mjs';
@@ -33,8 +33,14 @@ const schema = z.object({
   status: z.boolean().optional().describe('Include status styling (graph, mermaid only).'),
   module: z.string().optional().describe('Restrict the graph to one module (graph).'),
   scope: z.enum(['SMALL', 'MEDIUM', 'LARGE']).optional().describe('Scope class (scaffold).'),
-  slug: z.string().optional().describe('Project slug (scaffold).'),
+  slug: z.string().optional().describe('Project slug (scaffold, brief).'),
   kind: z.enum(BRIEF_KINDS).optional().describe('Which dispatch brief (brief).'),
+  featureRequest: z
+    .string()
+    .optional()
+    .describe('The feature being requested, in one line (brief). Defaults to the slug.'),
+  topic: z.string().optional().describe('Investigation topic (brief).'),
+  round: z.number().int().positive().optional().describe('Investigation round number (brief).'),
   projectRoot: projectRootArg,
 });
 
@@ -78,14 +84,44 @@ export function registerPlanTools(server) {
           return buildScaffold(loadAsset('depth-ladder.json'), args.scope, {
             slug: args.slug ?? null,
             templatesDir: TEMPLATES_DIR,
+            // The generator token carries the RUNNING server's version. The
+            // server knows it exactly, so the artifact records the truth
+            // instead of the agent having to guess, copy or type a version —
+            // and no release ever has to update a version written by hand.
+            generator: `archgen v${serverVersion()}`,
           });
         }
         case 'brief': {
           if (!args.kind) throw invalidInput('brief requires kind', { action });
-          return loadBrief(BRIEFS_DIR, args.kind, {
-            'feature request': args.slug ?? '<feature request>',
-            'slug dir': args.slug ?? '.archgen/<slug>',
-          });
+          // Every placeholder the chosen brief uses is filled in, derived
+          // from ONE source (the slug) so the paths in a brief agree with
+          // each other. Previously only two of the seven were substituted,
+          // and the 'slug dir' one was given the bare slug — so a worker
+          // was told to read `checkout` and to write into `.archgen/<slug>/`
+          // with the placeholder still in it.
+          const slug = args.slug ?? null;
+          const vars = {};
+          if (slug) {
+            vars['slug'] = slug;
+            vars['slug dir'] = `.archgen/${slug}`;
+            vars['plans dir'] = `.archgen/${slug}/plans`;
+            vars['tasks.yaml'] = args.tasksYaml ?? `.archgen/${slug}/tasks.yaml`;
+          }
+          if (args.featureRequest) vars['feature request'] = args.featureRequest;
+          else if (slug) vars['feature request'] = slug;
+          if (args.topic) vars['topic'] = args.topic;
+          if (args.round !== undefined) vars['round'] = String(args.round);
+          const { kind, brief } = loadBrief(BRIEFS_DIR, args.kind, vars);
+          // A brief with a placeholder still in it is a brief that would
+          // send a worker looking for a directory named "<slug dir>".
+          const missing = remainingPlaceholders(brief);
+          if (missing.length) {
+            throw invalidInput(
+              `brief '${kind}' needs ${missing.join(', ')} — pass slug${missing.includes('topic') ? ', topic' : ''}${missing.includes('round') ? ', round' : ''}`,
+              { action, kind, missing },
+            );
+          }
+          return { kind, brief };
         }
         case 'graph': {
           const input = args.tasksYaml ?? args.planDir;
@@ -102,6 +138,7 @@ export function registerPlanTools(server) {
             mermaid: format === 'mermaid',
             status: args.status === true,
             module: args.module ?? null,
+            projectRoot: ctx.projectRoot,
           });
         }
         default:

package/src/tools/setup.mjs

@@ -2,12 +2,11 @@
 import { z } from 'zod/v4';
 import { registerTool, projectRootArg } from './_register.mjs';
 import { loadAsset } from '../context.mjs';
-import { wireArchgenMcp, archgenMcpStatus, resolveMcpBinary } from '../core/mcp-server-manager.mjs';
+import { wireArchgenMcp, archgenMcpStatus, resolveMcpBinary, uninstallArchgenMcp } from '../core/mcp-server-manager.mjs';
 import { manageCodegraph, assertLocation, findCodegraph } from '../core/codegraph-manager.mjs';
 import { detectHarnesses } from '../core/harness-wiring.mjs';
 import { platformCapabilities, detectHarness } from '../core/platform-caps.mjs';
 import { checkCapability } from '../core/compat.mjs';
- '../core/errors.mjs';
 
 const ACTION_DESC =
   'doctor | bootstrap | install_mcp | uninstall_mcp | harnesses | harness_info — see archgen_help.';
@@ -127,7 +126,12 @@ export function registerSetupTools(server) {
         if (!approved) {
           return { written: false, planned: true, detail: 'uninstall_mcp needs approve: true — nothing was removed' };
         }
-        return { written: true, ...uninstallArchgenMcp(ctx.projectRoot, ctx.home) };
+        // The scope is honoured: removing only the global wiring leaves the
+        // project's wiring in place, and vice versa.
+        return {
+          written: true,
+          ...uninstallArchgenMcp(ctx.projectRoot, ctx.home, location),
+        };
       }
 
       if (args.action === 'install_mcp') {

package/src/tools/tasks.mjs

@@ -11,8 +11,30 @@ import { loadAsset } from '../context.mjs';
 import { setTaskStatus, STATUSES } from '../core/status-mutator.mjs';
 import { writeResumeSnapshot } from '../core/resume-snapshot.mjs';
 import { invalidInput } from '../core/errors.mjs';
+import { resolveSlugInput, ScopeError } from '../core/scope.mjs';
 import { dirname, join } from 'node:path';
 
+/**
+ * The `.archgen/<slug>/` directory a tasks file belongs to.
+ *
+ * A tasks.yaml outside the artifact space has no slug directory, so there is
+ * nowhere the snapshot may be written — and the worker contract says the
+ * snapshot is NEVER created outside `.archgen/`.
+ */
+function slugDirFor(tasksFile, action) {
+  try {
+    return resolveSlugInput(tasksFile).root;
+  } catch (e) {
+    if (e instanceof ScopeError) {
+      throw invalidInput(
+        `tasks.yaml must live in .archgen/<slug>/ — ${tasksFile} does not`,
+        { action, file: tasksFile },
+      );
+    }
+    throw e;
+  }
+}
+
 const ACTION_DESC = 'next | set_status | list | snapshot | contract — see archgen_help.';
 
 const schema = z.object({
@@ -60,7 +82,11 @@ export function registerTaskTools(server) {
         case 'snapshot': {
           if (!args.tasksYaml) throw invalidInput('tasksYaml is required for snapshot', { action });
           const tasksFile = ctx.contain(args.tasksYaml);
-          const slugDir = dirname(tasksFile);
+          // The snapshot belongs to the artifact space: `<slug>/.agent/`.
+          // Deriving it from the tasks file's PARENT wrote it wherever that
+          // file happened to be — `<project>/plans/.agent/resume.md`, outside
+          // `.archgen/`, which is exactly what the worker contract forbids.
+          const slugDir = slugDirFor(tasksFile, action);
           const waves = resolveWaves(tasksFile).waves;
           return writeResumeSnapshot(slugDir, waves);
         }
@@ -101,7 +127,7 @@ export function registerTaskTools(server) {
           // the whole plan.
           let docSections = [];
           try {
-            const map = docIndex(slugDir, { mode: 'map', token: args.taskId });
+            const map = docIndex(slugDir, { mode: 'map', token: args.taskId, projectRoot: ctx.projectRoot });
             docSections = (map.data.sections ?? []).slice(0, 2).map((s) => ({
               file: s.file,
               section: s.section,
@@ -116,9 +142,16 @@ export function registerTaskTools(server) {
           // The code-standards reference: resolved from the INSTALLED skill when
           // the caller does not name it. The worker needs a real path, and the
           // agent should not have to guess where the skill lives.
-          const codeStandardsPath =
-            args.codeStandardsPath ??
-            (ctx.skill ? join(ctx.skill.path, 'references', 'code-standards.md') : null);
+          //
+          // A caller-supplied path is CONTAINED, exactly like every other
+          // path argument: it ends up verbatim in a prompt a worker reads,
+          // so an uncontained one would point the worker anywhere on the
+          // machine.
+          const codeStandardsPath = args.codeStandardsPath
+            ? ctx.contain(args.codeStandardsPath)
+            : ctx.skill
+              ? join(ctx.skill.path, 'references', 'code-standards.md')
+              : null;
 
           const contract = buildWorkerContract({
             tasksYaml: tasksFile,