@taicho-ai/framework 0.1.0

package/src/core/tools.ts

@@ -0,0 +1,1104 @@
+/** Per-agent toolset. Every tool carries an execute fn so the AI SDK includes tool RESULTS in
+ *  response.messages (the manual loop pushes those back). execute closes over the RunContext,
+ *  which is how create_agent awaits captain approval and delegate_task spawns child runs. */
+import { tool, type ToolSet } from "ai";
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+import type { AgentDef } from "@taicho-ai/contracts/agent";
+import { effectiveTools, type TeamTools } from "@taicho-ai/contracts/team";
+import type { PlanItemStatus } from "@taicho-ai/contracts/plan";
+import type { RunContext, RunResult } from "./run";
+import type { McpManager } from "./mcp/manager";
+import type { VerificationVerdict } from "@taicho-ai/contracts/trace";
+import { paths } from "../store/files";
+import { loadWorkflow, seatsOf, orchestrationSlice } from "../store/workflows";
+import { parseWorkflowDef } from "@taicho-ai/graph";
+import { readTaskState } from "../store/task-state";
+import { saveArtifact, readArtifact, readArtifactBody, listArtifacts } from "../store/artifacts";
+import { annotateArtifact, listAnnotations } from "../store/annotations";
+import { recordVerificationFailure } from "../coaching/patterns";
+import { artifactHandle, parseHandle } from "@taicho-ai/contracts/artifact";
+import { mergeDraft } from "./draft";
+import { scrapeUrl } from "./firecrawl";
+import { McpServerConfig } from "../store/config";
+import { addMcpServer, applyMcpEnv } from "../store/mcp-store";
+import { KbNode } from "@taicho-ai/contracts/knowledge";
+import { writeNode, mkKbId, nodeExists, forgetNodes, reindexKnowledge, reembedAll } from "../store/knowledge";
+import { putVector } from "../store/vectors";
+import { searchKnowledge } from "../knowledge/retrieval";
+import { getActiveSkills, mkSkillId, writeSkill } from "../store/skills";
+import { rankSkills } from "../skills/retrieval";
+import { Skill } from "@taicho-ai/contracts/skill";
+import { classifyCommand, runShell, runSandboxed, isInsideWorkspace } from "./command-guard";
+import { argsPreview, capJson } from "./instrument";
+import { trace as otelTrace, context as otelContext, SpanStatusCode, ioAttrs } from "@taicho-ai/telemetry";
+
+// read_artifact body cap: default returns metadata + summary only; a body read is capped so an
+// uncapped read can't funnel a large payload back into context (the pollution this plan exists to kill).
+const READ_ARTIFACT_CAP = 4000;
+const READ_ARTIFACT_HARD_MAX = 20000;
+
+/** Reduce a list of artifact handles to the LATEST version per logical id (highest @vN). save_artifact
+ *  pushes a NEW versioned handle on every save, so a child that saves the same id twice hands back
+ *  [out@v1, out@v2]. A verification verdict judged the child's FINAL output, so it must anchor to the
+ *  newest version ONLY — annotating out@v1 too would smear a FAIL onto a version the checker never saw. */
+function latestHandlePerId(handles: string[]): string[] {
+  const best = new Map<string, { handle: string; version: number }>();
+  for (const h of handles) {
+    const { id, version } = parseHandle(h);
+    const v = version ?? 0; // trace handles are always id@vN, but a bare id sorts below any concrete version
+    const cur = best.get(id);
+    if (!cur || v > cur.version) best.set(id, { handle: h, version: v });
+  }
+  return [...best.values()].map((b) => b.handle);
+}
+
+/** Apply the captain's card edits to a team proposal. ProposalCard returns only CHANGED, non-empty
+ *  fields as strings; members/grant are captured as comma-separated lists and split back to arrays. */
+function mergeTeamProposal(
+  base: { id: string; charter: string; lead?: string; members: string[]; grant: string[] },
+  edits: Record<string, string>,
+): { id: string; charter: string; lead?: string; members: string[]; grant: string[] } {
+  const list = (s: string) => s.split(",").map((x) => x.trim()).filter(Boolean);
+  return {
+    id: edits.id ? edits.id.trim() : base.id,
+    charter: edits.charter ?? base.charter,
+    lead: edits.lead !== undefined ? (edits.lead.trim() || undefined) : base.lead,
+    members: edits.members !== undefined ? list(edits.members) : base.members,
+    grant: edits.grant !== undefined ? list(edits.grant) : base.grant,
+  };
+}
+
+export function toolsForAgent(agent: AgentDef, ctx: RunContext, mcp?: McpManager, teamPolicy?: TeamTools): ToolSet {
+  const set: ToolSet = {};
+  // Plan 19: a team's tool policy layers over the member's own grant — `grant` ADDS, `deny` REMOVES and
+  // wins. Every gate below reads `has()` rather than agent.tools directly, so the policy applies
+  // uniformly (built-ins, KB tools, and the `mcp:<server>` refs resolved further down). The
+  // DEFAULT_WORKER_TOOLS floor is protected when the team file loads, not here.
+  const granted = new Set(effectiveTools(agent.tools, teamPolicy));
+  const has = (t: string) => granted.has(t);
+
+  // Legacy simple-markdown write, kept as a back-compat wrapper over the structured store (per the
+  // plan: save_artifact "replaces/wraps" it). Prefer save_artifact for provenance + hand-off.
+  if (has("write_artifact"))
+    set.write_artifact = tool({
+      description: "Write a simple markdown artifact and return its path. Prefer save_artifact for structured, versioned, provenance-tracked outputs you hand off by reference.",
+      inputSchema: z.object({
+        topicSlug: z.string().regex(/^[a-z0-9-]+$/, "lowercase, digits, hyphens only"),
+        markdown: z.string(),
+      }),
+      execute: async ({ topicSlug, markdown }) => {
+        const a = saveArtifact(ctx.ws, {
+          id: topicSlug, title: topicSlug, type: "document", role: "output",
+          producer: ctx.agentId, runId: ctx.runId, body: markdown,
+        });
+        const path = a.location.kind === "file" ? a.location.path : artifactHandle(a);
+        ctx.artifacts.push(artifactHandle(a)); // hand off by handle (id@vN) like save_artifact — an absolute path is un-resolvable to the parent
+        return { path };                       // model still gets the concrete path for back-compat
+      },
+    });
+
+  if (has("save_artifact"))
+    set.save_artifact = tool({
+      description: "Save a work product to the shared artifact store as a structured, versioned, addressable artifact — the way to hand work to other agents (and the human) BY REFERENCE instead of dumping it into the conversation. Your identity + this run are recorded as provenance automatically. Give a `body` (local content) OR an `external` locator (a URI/ref into a system an MCP server fronts). Reusing an existing `id` saves a NEW immutable version. Returns the handle (id@vN) — pass it in delegate_task's inputArtifacts to hand it off.",
+      inputSchema: z.object({
+        title: z.string(),
+        id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase, digits, hyphens").optional().describe("stable logical id/slug; omit to derive from the title; reuse an existing id to save a new version"),
+        type: z.string().default("document").describe("free-form tag (e.g. dossier, script, dataset, notion-page) — NOT an enforced taxonomy"),
+        role: z.enum(["output", "input", "resource"]).default("output").describe("output = you produced it; input/resource = human- or ingest-provided"),
+        summary: z.string().optional().describe("a short summary of what this artifact is; readers see it before they pull the body"),
+        body: z.string().optional().describe("the artifact's local content (stored as bytes on disk)"),
+        external: z.string().optional().describe("a locator (URI/ref) when the work product lives in an external system; use INSTEAD of body"),
+        ext: z.string().optional().describe("file extension for the body (default md)"),
+        parents: z.array(z.string()).default([]).describe("handles of artifacts this one derives from (lineage)"),
+      }),
+      execute: async ({ title, id, type, role, summary, body, external, ext, parents }) => {
+        if (body === undefined && !external) return { error: "provide a `body` (local content) or an `external` locator" };
+        try {
+          const a = saveArtifact(ctx.ws, { id, title, type, role, summary, body, external, ext, parents, producer: ctx.agentId, runId: ctx.runId });
+          const handle = artifactHandle(a);
+          ctx.artifacts.push(handle);
+          ctx.notes.push(`saved artifact ${handle}`);
+          return { id: a.id, version: a.version, handle, location: a.location };
+        } catch (e) {
+          return { error: e instanceof Error ? e.message : String(e) };
+        }
+      },
+    });
+
+  if (has("read_artifact"))
+    set.read_artifact = tool({
+      description: "Fetch an artifact by handle ('id' for the latest version, or 'id@vN'). Returns metadata + summary by DEFAULT (cheap — keeps context thin). Pass includeBody:true to pull the body, which is size-capped and truncated with a marker; never dump a whole large artifact into context.",
+      inputSchema: z.object({
+        id: z.string().describe("artifact handle: 'id' (latest) or 'id@vN'"),
+        includeBody: z.boolean().default(false).describe("pull the body too (size-capped) — off by default"),
+        maxChars: z.number().int().positive().max(READ_ARTIFACT_HARD_MAX).default(READ_ARTIFACT_CAP).describe(`body cap in characters (max ${READ_ARTIFACT_HARD_MAX})`),
+      }),
+      execute: async ({ id, includeBody, maxChars }) => {
+        const a = readArtifact(ctx.ws, id);
+        if (!a) return { error: `no artifact "${id}"` };
+        const meta = {
+          id: a.id, version: a.version, handle: artifactHandle(a), title: a.title,
+          type: a.type, role: a.role, producer: a.producer, runId: a.runId,
+          parents: a.parents, summary: a.summary ?? null, location: a.location,
+        };
+        if (!includeBody) return { ...meta, bodyOmitted: true };
+        if (a.location.kind === "external")
+          return { ...meta, external: a.location.uri, note: "external artifact — its body lives in the fronting system; use that system's tools to fetch it" };
+        const buf = readArtifactBody(ctx.ws, id);
+        if (!buf) return { ...meta, error: "body bytes missing" };
+        const cap = Math.min(maxChars, READ_ARTIFACT_HARD_MAX);
+        const text = buf.toString("utf8");
+        const truncated = text.length > cap;
+        return {
+          ...meta, bytes: buf.length, truncated,
+          body: truncated
+            ? text.slice(0, cap) + `\n…[truncated ${text.length - cap} of ${text.length} chars — raise maxChars up to ${READ_ARTIFACT_HARD_MAX} or read a narrower artifact]`
+            : text,
+        };
+      },
+    });
+
+  if (has("list_artifacts"))
+    set.list_artifacts = tool({
+      description: "Discover artifacts in the shared store (the latest version of each). Filter by producer (agent id), type (free-form tag), role (output|input|resource), or q (substring over id/title/summary). Returns handles + summaries — read one with read_artifact.",
+      inputSchema: z.object({
+        producer: z.string().optional(),
+        type: z.string().optional(),
+        role: z.enum(["output", "input", "resource"]).optional(),
+        q: z.string().optional().describe("substring over id/title/summary"),
+        k: z.number().int().positive().max(50).default(20),
+      }),
+      execute: async ({ producer, type, role, q, k }) => ({
+        artifacts: listArtifacts(ctx.ws, { producer, type, role, q }).slice(0, k).map((a) => ({
+          handle: artifactHandle(a), id: a.id, version: a.version, title: a.title,
+          type: a.type, role: a.role, producer: a.producer, summary: a.summary ?? null,
+        })),
+      }),
+    });
+
+  if (has("annotate_artifact"))
+    set.annotate_artifact = tool({
+      description: "Leave feedback ON an artifact version (by handle 'id' for the latest, or 'id@vN'). An OPEN annotation becomes the input to a REVISION run: when the artifact is later handed to an agent by reference, your feedback rides along, that agent reads the artifact, addresses your points, and saves a NEW version. Use this to request changes, flag a problem, or sign off (kind:'approval'). Your identity is recorded as the author. Pin your feedback to the exact version you reviewed.",
+      inputSchema: z.object({
+        id: z.string().describe("artifact handle: 'id' (latest) or 'id@vN'"),
+        body: z.string().describe("the feedback — what to fix / what's wrong / what to change (or, for an approval, why it's accepted)"),
+        kind: z.enum(["feedback", "approval"]).default("feedback").describe("feedback = a change request that drives a revision; approval = sign-off"),
+      }),
+      execute: async ({ id, body, kind }) => {
+        try {
+          const a = annotateArtifact(ctx.ws, { target: id, author: ctx.agentId, body, kind });
+          ctx.notes.push(`annotated ${a.target} (${a.id})`);
+          return { annotationId: a.id, target: a.target, kind: a.kind, status: a.status };
+        } catch (e) {
+          return { error: e instanceof Error ? e.message : String(e) };
+        }
+      },
+    });
+
+  if (has("list_annotations"))
+    set.list_annotations = tool({
+      description: "List the feedback/annotations on an artifact (by handle 'id' for all versions, or 'id@vN' for one). Call this BEFORE you revise an artifact so you address every open point. Returns each annotation's author, body, kind, verdict (if it's a verification), and status (open/addressed/dismissed).",
+      inputSchema: z.object({
+        id: z.string().describe("artifact handle: 'id' (all versions) or 'id@vN' (that version)"),
+        status: z.enum(["open", "addressed", "dismissed"]).optional().describe("filter by status (default: all)"),
+      }),
+      execute: async ({ id, status }) => ({
+        annotations: listAnnotations(ctx.ws, id, { status }).map((a) => ({
+          annotationId: a.id, target: a.target, author: a.author, kind: a.kind,
+          body: a.body, verdict: a.verdict ?? null, status: a.status, resolvedBy: a.resolvedBy ?? null,
+        })),
+      }),
+    });
+
+  if (has("create_agent"))
+    set.create_agent = tool({
+      description: "Propose a NEW worker agent for the captain to approve. Give it a clear id, a one-line role, and an identity that defines its point of view.",
+      inputSchema: z.object({
+        id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+        role: z.string(),
+        identity: z.string(),
+        // Lifecycle contract (Plan 14): the worker ALWAYS gets the artifact-tool baseline
+        // (save_artifact/read_artifact/list_artifacts/annotate_artifact/…) so it can produce and hand
+        // off work BY REFERENCE. This field only ADDS extra capabilities on top — e.g. "delegate_task",
+        // "run_command", "ask_human", or an "mcp:<server>" ref — it does NOT replace the baseline. Omit
+        // it (or pass []) for a plain worker; you never need to list the artifact tools yourself.
+        tools: z.array(z.string()).optional().describe("EXTRA capabilities to grant on top of the always-present artifact baseline (e.g. delegate_task, run_command, ask_human, mcp:<server>); omit for a plain worker — never list the artifact tools, they are always granted"),
+      }),
+      execute: async (draft) => {
+        const decision = await ctx.requestApproval({ kind: "create_agent", draft });
+        if (decision.type === "reject") return { rejected: true, reason: "reject" };
+        const finalDraft = decision.type === "edit" ? mergeDraft(draft, decision.draft) : draft;
+        try {
+          const created = await ctx.createAgent(finalDraft);
+          return { created: created.id, role: created.role };
+        } catch {
+          return { error: `agent "${finalDraft.id}" already exists or could not be created` };
+        }
+      },
+    });
+
+  // Plan 22: the on-the-fly team route. "take editor, reporter and fact-check — that's the news team" →
+  // this tool → ONE approval card (the same one create_agent uses). Captain-gated by construction, and
+  // the grant can name only tools the PROPOSER already holds, so a model can't escalate itself by minting
+  // a team. NOT in DEFAULT_WORKER_TOOLS — root holds it; a lead would be granted it deliberately.
+  if (has("create_team"))
+    set.create_team = tool({
+      description:
+        "Propose a NEW team for the captain to approve, and optionally staff it in one step. A team groups agents so you can address the group and let it route work to the right member. Give it a clear id, a one-line charter, the member agent ids, an optional lead (a member the team routes to first), and any EXTRA tools to grant every member. The captain approves before the team exists.",
+      inputSchema: z.object({
+        id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+        charter: z.string(),
+        members: z.array(z.string()).default([]).describe("agent ids to place on the team"),
+        lead: z.string().optional().describe("a member the team routes to first; omit for capability-based routing"),
+        grant: z.array(z.string()).default([]).describe("extra tools to grant every member — you may only grant tools YOU already hold"),
+      }),
+      execute: async (draft) => {
+        // Capability ceiling: you cannot grant a team more than you hold. This is what makes the tool safe
+        // to expose despite a team granting capability — escalation is impossible before the captain looks.
+        const overreach = draft.grant.filter((t) => !agent.tools.includes(t));
+        if (overreach.length) return { rejected: true, reason: `cannot grant tools you do not hold: ${overreach.join(", ")}` };
+        const proposal = { id: draft.id, charter: draft.charter, lead: draft.lead, members: draft.members, grant: draft.grant };
+        const decision = await ctx.requestApproval({ kind: "create_team", draft: proposal });
+        if (decision.type === "reject") return { rejected: true, reason: "reject" };
+        const final = decision.type === "edit" ? mergeTeamProposal(proposal, decision.draft) : proposal;
+        try {
+          const team = await ctx.createTeam(final);
+          return { created: team.id, lead: team.lead, members: final.members };
+        } catch (e) {
+          return { error: e instanceof Error ? e.message : `team "${final.id}" could not be created` };
+        }
+      },
+    });
+
+  // Plan 23: READ a team's workflow, so root can brief the captain on how a team works. Read-only — the
+  // model never authors or edits a workflow (those stay captain-authored, which is what keeps the process
+  // stable). Not approval-gated: reading isn't privileged. Root holds it; a lead could be granted it too.
+  if (has("read_workflow"))
+    set.read_workflow = tool({
+      description:
+        "Read a team's WORKFLOW — how work moves through it and what each seat (member) does — so you can brief the captain on it. Read-only: workflows are captain-authored and you cannot change one from here. Returns the raw workflow markdown plus the seats it covers, or a note when the team has none.",
+      inputSchema: z.object({ team: z.string().describe("the team id whose workflow to read") }),
+      execute: async ({ team }) => {
+        const wf = loadWorkflow(ctx.ws, team);
+        if (!wf) return { team, workflow: null, note: `team "${team}" has no workflow — it runs on the agentic brief` };
+        const text = await readFile(paths.teamWorkflowFile(ctx.ws, team), "utf8");
+        return { team, seats: seatsOf(wf), hasOrchestration: !!orchestrationSlice(wf), workflow: text };
+      },
+    });
+
+  // Plan 25: run a team's STRUCTURED workflow (the engine walks the steps; human gates ask the captain).
+  if (has("run_workflow"))
+    set.run_workflow = tool({
+      description:
+        "Run a team's WORKFLOW — the engine walks its steps in order (research → verify → draft → sign-off → …), stopping at any human gate to ask the captain. Use when the captain asks to run a team's process. The team must have a structured workflow (a `steps:` block in its workflow.md); otherwise this returns a note. Returns the per-step outcome and the handles it produced.",
+      inputSchema: z.object({ team: z.string().describe("the team id whose workflow to run") }),
+      execute: async ({ team }) => {
+        if (!ctx.runWorkflow) return { error: "workflows are not available in this run" };
+        const state = await ctx.runWorkflow(team);
+        if (!state) return { team, ran: false, note: `team "${team}" has no structured workflow — nothing to run` };
+        return {
+          team,
+          ran: true,
+          status: state.status,
+          steps: state.steps.map((s) => ({ id: s.id, status: s.status, produced: s.produced, choice: s.choice })),
+        };
+      },
+    });
+
+  // Plan 25: PROPOSE a structured workflow for a team. The model drafts; the captain approves; the ENGINE
+  // writes the file (the model never writes workflow canon — Plan 23's rule, preserved). Existing prose
+  // lanes are kept. This is the twin of create_team.
+  if (has("propose_workflow"))
+    set.propose_workflow = tool({
+      description:
+        "Propose a structured workflow for a team — the ordered steps its work should follow. The captain APPROVES before it is saved; you never write the file yourself. Each step is exactly ONE kind: an agent step (run: <agent-id>, optional consumes/produces/brief), a check (check: <criteria>, optional on_fail), or a human gate (human: <title>, choices, routes). Existing prose lanes are preserved. Use this when the captain asks how a team should organise, or to set up a repeatable team process.",
+      inputSchema: z.object({
+        team: z.string().describe("the team id this workflow is for"),
+        name: z.string().describe("a short workflow name, e.g. daily-brief"),
+        brief: z.string().optional().describe("a workflow-wide instruction every step sees"),
+        steps: z.array(z.record(z.string(), z.any())).min(1).describe("the ordered steps; each carries exactly one of run/check/human/branch/over"),
+      }),
+      execute: async ({ team, name, brief, steps }) => {
+        try { parseWorkflowDef({ id: name, team, version: 1, brief, steps }); }
+        catch (e) { return { proposed: false, error: `invalid workflow: ${(e as Error).message}` }; }
+        const d = await ctx.requestApproval({ kind: "propose_workflow", draft: { team, name, brief, steps } });
+        if (d.type !== "approve" && d.type !== "edit") return { proposed: false, note: "the captain declined the workflow" };
+        if (!ctx.proposeWorkflow) return { proposed: false, error: "workflow authoring is not available in this run" };
+        const final = d.type === "edit"
+          ? { team: d.draft.team ?? team, name: d.draft.name ?? name, brief: d.draft.brief ?? brief, steps }
+          : { team, name, brief, steps };
+        ctx.proposeWorkflow(final);
+        return { proposed: true, saved: `teams/${final.team}/workflow.md`, steps: steps.length };
+      },
+    });
+
+  // Plan 25 Ph6: answer a workflow run that PARKED at a human gate (an unattended run waiting on the captain).
+  if (has("resume_workflow"))
+    set.resume_workflow = tool({
+      description:
+        "Answer a workflow run that PARKED at a human gate — a scheduled/unattended run waiting on the captain. Give the team, the parked run id, and the chosen option; the engine drives the workflow on from the gate. Use when the captain tells you how to answer a waiting workflow (see the boot notice or /workflows).",
+      inputSchema: z.object({
+        team: z.string().describe("the team whose workflow parked"),
+        runId: z.string().describe("the parked run id, e.g. wr_brief_1"),
+        choice: z.string().describe("the gate option to take, e.g. approve or revise"),
+        note: z.string().optional().describe("an optional note that rides back into the workflow"),
+      }),
+      execute: async ({ team, runId, choice, note }) => {
+        if (!ctx.resumeWorkflow) return { error: "workflows are not available in this run" };
+        const state = await ctx.resumeWorkflow(team, runId, choice, note);
+        if (!state) return { team, resumed: false, note: `team "${team}" has no structured workflow` };
+        return { team, runId, resumed: true, status: state.status, steps: state.steps.map((s) => ({ id: s.id, status: s.status })) };
+      },
+    });
+
+  // ---- Plan 18: the agent's live plan -------------------------------------------------------------
+  // NOT in DEFAULT_WORKER_TOOLS. A plan is not needed to produce an artifact, so it stays an opt-in
+  // grant under Plan 08 least privilege. Root holds all three; a worker or team lead asks for them.
+
+  if (has("write_plan"))
+    set.write_plan = tool({
+      description:
+        "Write (or REVISE) your plan: the checklist you work from and the captain watches. Call this ONCE " +
+        "up front for any multi-step goal, then again only when you genuinely change your mind about the " +
+        "SHAPE of the work — an identical list mints nothing. Item ids are stable across revisions, so a " +
+        "ticked item stays ticked. Items you hand to another agent via delegate_task(itemId:…) are ticked " +
+        "by the ENGINE from the child's real outcome; do not tick those yourself.",
+      inputSchema: z.object({
+        goal: z.string().describe("one line: what finishing this plan means"),
+        items: z.array(z.object({
+          id: z.string().describe("stable, lowercase, e.g. it_survey — reuse the id to keep an item's state across a revision"),
+          text: z.string(),
+          assignee: z.string().optional().describe("the agent or team you intend to hand this to"),
+        })).min(1),
+      }),
+      execute: async ({ goal, items }) => {
+        if (!ctx.plan) return { error: "plans are not available in this context" };
+        try {
+          const { handle, minted } = ctx.plan.write({ goal, items });
+          ctx.notes.push(minted ? `wrote plan ${handle}` : `plan ${handle} unchanged`);
+          ctx.emit?.({ plan: ctx.plan.read() ?? undefined });
+          return { handle, minted, note: minted ? undefined : "identical to the current version — no new version minted" };
+        } catch (e) {
+          return { error: e instanceof Error ? e.message : String(e) };
+        }
+      },
+    });
+
+  if (has("update_plan_item"))
+    set.update_plan_item = tool({
+      description:
+        "Tick an item on your plan. Use it for work YOU did. An item bound to a delegated run is owned by " +
+        "the engine: it goes done/failed from the child's real outcome (and, if you set criteria, only when " +
+        "an independent check agrees), and an attempt to mark it yourself is refused and recorded. " +
+        "`dropped` means you decided not to do it and requires a note saying why.",
+      inputSchema: z.object({
+        itemId: z.string(),
+        status: z.enum(["pending", "in_progress", "done", "failed", "blocked", "dropped"]),
+        note: z.string().optional(),
+      }),
+      execute: async ({ itemId, status, note }) => {
+        if (!ctx.plan) return { error: "plans are not available in this context" };
+        const r = ctx.plan.tick({ itemId, status, note, by: "model" });
+        if (!r.ok) {
+          ctx.notes.push(`plan tick refused (${itemId}): ${r.rejected}`);
+          return { rejected: r.rejected, boundRunId: r.boundRunId };
+        }
+        ctx.emit?.({ plan: ctx.plan.read() ?? undefined });
+        return { ok: true, plan: ctx.plan.read()?.counts };
+      },
+    });
+
+  if (has("read_plan"))
+    set.read_plan = tool({
+      description:
+        "Read a plan's current state — yours by default, or another agent's by handle ('p_x' for the latest " +
+        "version, 'p_x@v2' for a specific one). Returns the goal, the items with their statuses, and the counts.",
+      inputSchema: z.object({
+        handle: z.string().optional().describe("omit for your own live plan"),
+      }),
+      execute: async ({ handle }) => {
+        if (!ctx.plan) return { error: "plans are not available in this context" };
+        const s = ctx.plan.read(handle);
+        if (!s) return { error: handle ? `no plan "${handle}"` : "you have no plan yet — call write_plan" };
+        return {
+          handle: s.handle, goal: s.plan.goal, counts: s.counts,
+          items: s.items.map((i) => ({ id: i.id, text: i.text, status: i.status, assignee: i.assignee, engineOwned: !!i.boundRunId, note: i.note })),
+        };
+      },
+    });
+
+  if (has("delegate_task"))
+    set.delegate_task = tool({
+      description:
+        "Delegate a goal to another agent by id, or to a TEAM by its id — a team routes the goal to its " +
+        "lead, or to whichever member best fits the goal. Prefer addressing the team when one covers the " +
+        "work; you are not expected to know who sits on it. Hand work over BY REFERENCE via `inputArtifacts` " +
+        "(artifact handles the child reads with read_artifact) rather than pasting content into `context`; " +
+        "you get back the child's output artifact handles + a short summary — not its full text. " +
+        "Optionally pass `criteria` — a plain-language contract for what 'done' means (e.g. \"a markdown " +
+        "dossier with ≥5 cited, dated sources\"). When you set criteria, the child's output is judged by an " +
+        "independent check before you get it; a failing check triggers one automatic retry with feedback, " +
+        "and a still-failing result comes back with its failed verdict attached so you can see the caveat. " +
+        "Set criteria whenever the output has concrete requirements you'd otherwise have to re-check by hand.",
+      inputSchema: z.object({
+        to: z.string().describe("an agent id, or a team id (ids share one namespace, so a bare name is unambiguous)"),
+        goal: z.string(),
+        context: z.string().optional(),
+        criteria: z.string().optional().describe("acceptance criteria the output must meet; enables an independent check + one retry"),
+        inputArtifacts: z.array(z.string()).optional().describe("artifact handles ('id' or 'id@vN') to hand to the child by reference"),
+        itemId: z.string().optional().describe("an item on your plan this delegation fulfils; the ENGINE then ticks it from the child's real outcome (and only when the criteria check passes)"),
+      }),
+      execute: async ({ to, goal, context, criteria, inputArtifacts, itemId }, options) => {
+        // The AI SDK's toolCallId is the SAME id the instrument() wrapper stamps on this call's
+        // tool_start/tool_end span (Plan 02), so threading it into runChild lets the LIVE waterfall nest
+        // each child under the EXACT delegate_task span that spawned it — deterministic for concurrent
+        // delegations in one turn, mirroring the post-hoc childRunId linkage.
+        const spawnCallId = options?.toolCallId;
+        const budgetMsg = () => `work item budget (${agent.budgets.maxWorkItemsPerRequest}) exhausted`;
+        // Each delegation (initial AND the verification retry) consumes one work item — config
+        // disposes, so the retry is no new runaway vector.
+        ctx.workItems.n += 1;
+        if (ctx.workItems.n > agent.budgets.maxWorkItemsPerRequest) {
+          ctx.notes.push(`delegate refused: ${budgetMsg()}`);
+          return { error: budgetMsg() };
+        }
+        // Plan 19: `to` may be a team. Resolve it to the agent that will actually run BEFORE any guard
+        // fires, so the cycle/depth checks apply to that agent rather than to a team id that is never
+        // in the ancestry chain. Everything downstream — runChild, the checker, the retry — sees a
+        // plain agent id and does not know a team was involved.
+        const guard = ctx.resolveDelegation(to, goal);
+        if (!guard.ok) { ctx.notes.push(`delegate refused: ${guard.error}`); return { error: guard.error }; }
+        const target = guard.agentId;
+        if (guard.note) {
+          // Never a silent pick: rankAgents is a keyword match and will sometimes choose badly.
+          ctx.notes.push(guard.note);
+          ctx.emit?.({ note: guard.note });
+        }
+
+        // Plan 18: bind the plan item to this delegation. From here the ENGINE owns its terminal status —
+        // the model may narrate, but it may not declare a delegated item done. Bind BEFORE the child runs
+        // so a crash mid-delegation leaves an `in_progress` item for reconcilePlans to mark interrupted.
+        const bind = (status: PlanItemStatus, note?: string, boundRunId?: string) => {
+          if (!itemId || !ctx.plan) return;
+          const r = ctx.plan.tick({ itemId, status, note, by: "engine", boundRunId });
+          if (!r.ok) ctx.notes.push(`plan bind failed (${itemId}): ${r.rejected}`);
+          else ctx.emit?.({ plan: ctx.plan.read() ?? undefined });
+        };
+        bind("in_progress", `delegated to ${target}`, `pending:${spawnCallId ?? target}`);
+
+        // resolve input handles; drop (and note) any that don't exist rather than passing a dead ref.
+        const resolved: string[] = [], dropped: string[] = [];
+        for (const h of inputArtifacts ?? []) (readArtifact(ctx.ws, h) ? resolved : dropped).push(h);
+        if (dropped.length) ctx.notes.push(`delegate: dropped unknown input artifact(s) ${dropped.join(", ")}`);
+
+        // Spawn one child run (initial OR the verification retry). Both get the SAME input handles BY
+        // REFERENCE, and each spawn folds its spend + produced handles into this run's aggregate/graph.
+        const spawn = async (childContext?: string) => {
+          const child = await ctx.runChild({ to: target, goal, context: childContext, criteria, inputArtifacts: resolved, callId: spawnCallId, viaTeam: guard.viaTeam });
+          ctx.delegatedOut.push(child.runId);
+          ctx.childTraces.push(child.trace);
+          ctx.outputArtifacts.push(...child.trace.artifacts); // hand-off graph: handles the child produced
+          const agg = child.trace.aggregate ?? { tokens: child.trace.tokens, costUsd: child.trace.costUsd };
+          ctx.childSpend.tokens += agg.tokens;
+          ctx.childSpend.costUsd += agg.costUsd ?? 0;
+          return child;
+        };
+
+        // What the checker actually judges. Workers hand off BY REFERENCE (Plan 14) — the child's chat
+        // reply is a hand-off sentence ("Saved the brief as brief@v2"), NOT the deliverable, so judging
+        // `child.text` against content criteria false-fails EVERY artifact-producing worker (the checker
+        // literally never sees the content). Resolve the child's PRODUCED artifact bodies (latest version
+        // per id) and judge those; fall back to the chat text only when the child produced no artifact
+        // (a genuinely text-only delegation, today's behavior).
+        const candidateOutput = (c: RunResult): string => {
+          const bodies: string[] = [];
+          for (const h of latestHandlePerId(c.trace.artifacts)) {
+            try {
+              const body = readArtifactBody(ctx.ws, h);
+              if (body && body.length) bodies.push(`ARTIFACT ${h}:\n${body.toString("utf8")}`);
+            } catch { /* unreadable handle → skip, fall through to chat text if none resolve */ }
+          }
+          if (!bodies.length) return c.text;
+          return c.text ? `${c.text}\n\n${bodies.join("\n\n")}` : bodies.join("\n\n");
+        };
+
+        try {
+          let child = await spawn(context);
+          ctx.inputArtifacts.push(...resolved); // hand-off graph: handles I sent down (same set for any retry)
+
+          // No criteria ⇒ no check ⇒ today's trust-everything behavior, zero extra cost.
+          // Parent context gets handles + a summary, NOT the child's full body (the pollution vector).
+          if (!criteria) {
+            // No criteria ⇒ the checkbox follows the child's OUTCOME, which is still the truth about
+            // whether the run finished, not the model's claim about it.
+            bind(child.trace.outcome === "completed" ? "done" : child.trace.outcome === "blocked" ? "blocked" : "failed",
+                 child.trace.outcome === "completed" ? undefined : `child run ${child.trace.outcome}`, child.runId);
+            return { to: target, team: guard.team, runId: child.runId, outputArtifacts: child.trace.artifacts, summary: child.text };
+          }
+          const criteriaText = criteria; // narrowed to string past the guard (kept for the surface closure)
+
+          // Plan 06 Phase 3 — surface a FAILED verdict two ways, then hand the caveat to the parent:
+          //  (1) as an ANNOTATION on the artifact version the hand-off involved (the child's output, else
+          //      the input it was revising) — the SAME object a human review produces, so a machine
+          //      verdict rides the identical annotation → revision path (Plan 01 Ph4);
+          //  (2) into COACHING — a REPEATED (agent, criteria) failure PROPOSES a policy note (captain-
+          //      gated, inert until approved), never an auto-applied policy.
+          // A passing verdict does neither; either way the parent still gets the verdict attached below.
+          const surface = (v: VerificationVerdict, c: RunResult) => {
+            if (!v.pass) {
+              // Anchor the FAIL to the exact bytes the checker judged, WITHOUT smearing onto stale or
+              // merely-referenced handles. annotateArtifact pins a handle to a concrete version, so:
+              //  - child produced output → its LATEST version PER id (a child that saved out@v1 then
+              //    out@v2 is judged on out@v2; v1 must NOT also collect the verdict);
+              //  - child produced nothing → the input(s) it was REVISING (they carry OPEN feedback), not
+              //    every reference it was handed (a spec/source it only read shouldn't collect a FAIL);
+              //    absent any open-feedback signal, fall back to the single most-recent input, never all.
+              let targets: string[];
+              if (c.trace.artifacts.length) {
+                targets = latestHandlePerId(c.trace.artifacts);
+              } else {
+                const revised = resolved.filter((h) => {
+                  try { return listAnnotations(ctx.ws, h, { status: "open" }).length > 0; } catch { return false; }
+                });
+                targets = revised.length ? latestHandlePerId(revised) : resolved.slice(-1);
+              }
+              for (const h of targets) {
+                try {
+                  const ann = annotateArtifact(ctx.ws, {
+                    target: h, author: "checker",
+                    body: v.reasons.length ? v.reasons.join("; ") : "output did not meet the acceptance criteria",
+                    verdict: v,
+                  });
+                  ctx.notes.push(`verification verdict annotated on ${ann.target} (${ann.id})`);
+                } catch (e) {
+                  ctx.notes.push(`verdict annotation skipped for ${h}: ${e instanceof Error ? e.message : String(e)}`);
+                }
+              }
+              try {
+                const { proposed } = recordVerificationFailure(ctx.ws, { targetAgent: target, criteria: criteriaText, runId: c.runId, reasons: v.reasons });
+                if (proposed) ctx.emit?.({ note: `⚑ ${target} keeps failing this check — proposed a coaching note (${proposed.id}) for your approval` });
+              } catch (e) {
+                ctx.notes.push(`coaching proposal skipped: ${e instanceof Error ? e.message : String(e)}`);
+              }
+            }
+            // Plan 18 × Plan 06: with criteria set, the box goes GREEN only when an INDEPENDENT model
+            // call agrees the child met them. The checkbox stops being a progress bar and becomes an
+            // assertion. A failed verdict carries its reasons onto the item.
+            bind(
+              v.pass ? "done" : c.trace.outcome === "blocked" ? "blocked" : "failed",
+              v.pass ? undefined : v.reasons.length ? v.reasons.join("; ") : "did not meet the acceptance criteria",
+              c.runId,
+            );
+            return { to: target, team: guard.team, runId: c.runId, outputArtifacts: c.trace.artifacts, summary: c.text, verification: v };
+          };
+
+          // Independent checker call, BEFORE the result reaches the parent's context. Its spend is
+          // real model spend this run caused → fold it into the aggregate (like child-run spend).
+          const first = await ctx.checkCriteria({ goal, criteria, output: candidateOutput(child) });
+          ctx.verifierSpend.tokens += first.tokens;
+          ctx.verifierSpend.costUsd += first.costUsd ?? 0; // null (subscription) folds as 0 in the sum; recorded value stays null
+          ctx.verifications.push({ criteria, verdict: first.verdict, runId: child.runId, retried: false, tokens: first.tokens, costUsd: first.costUsd, costNote: first.costNote, checkerError: first.checkerError });
+          // Plan 20: the judge never RAN — this verdict says nothing about the OUTPUT. Skip the retry
+          // (re-running the child is pointless when the checker is down and would burn a work item),
+          // skip annotation + coaching (they'd blame the artifact for an outage), settle the item from
+          // the child's REAL outcome like the no-criteria path, and surface the result UNVERIFIED.
+          if (first.checkerError) {
+            ctx.emit?.({ note: `⚠ verification checker unavailable — surfacing ${target} result UNVERIFIED (${first.verdict.reasons.join("; ")})` });
+            bind(child.trace.outcome === "completed" ? "done" : child.trace.outcome === "blocked" ? "blocked" : "failed",
+                 "verification checker unavailable — settled from run outcome", child.runId);
+            return { to: target, team: guard.team, runId: child.runId, outputArtifacts: child.trace.artifacts, summary: child.text, verification: first.verdict };
+          }
+          let verdict = first.verdict;
+
+          if (!verdict.pass) {
+            ctx.emit?.({ note: `↻ ${target} output failed verification: ${verdict.reasons.join("; ")} — retrying once` });
+            // Exactly ONE bounded retry — consumes a work item like any delegation.
+            ctx.workItems.n += 1;
+            const overBudget = ctx.workItems.n > agent.budgets.maxWorkItemsPerRequest;
+            // Re-guard against the RESOLVED agent, never the original `to`. Passing a team id here would
+            // re-run the ranker, and a leadless team could hand the retry — carrying feedback about the
+            // FIRST agent's mistakes — to a different member entirely.
+            const retryGuard = ctx.resolveDelegation(target, goal);
+            if (overBudget || !retryGuard.ok) {
+              const why = overBudget ? budgetMsg() : !retryGuard.ok ? retryGuard.error : "retry blocked";
+              ctx.notes.push(`verification retry refused: ${why}`);
+              ctx.emit?.({ note: `⚠ ${target} result surfaced WITHOUT a passing verification (retry blocked: ${why})` });
+              return surface(verdict, child);
+            }
+            const feedback = "Your previous attempt did NOT meet the acceptance criteria. Fix these before returning:\n" +
+              verdict.reasons.map((r) => `- ${r}`).join("\n");
+            // Retry-spawn ALSO threads inputArtifacts (via the closure's `resolved`) so the retried
+            // child still receives the same input handles by reference.
+            const retry = await spawn(context ? `${context}\n\n${feedback}` : feedback);
+            const second = await ctx.checkCriteria({ goal, criteria, output: candidateOutput(retry) });
+            ctx.verifierSpend.tokens += second.tokens;
+            ctx.verifierSpend.costUsd += second.costUsd ?? 0; // null (subscription) folds as 0 in the sum; recorded value stays null
+            ctx.verifications.push({ criteria, verdict: second.verdict, runId: retry.runId, retried: true, tokens: second.tokens, costUsd: second.costUsd, costNote: second.costNote, checkerError: second.checkerError });
+            // Plan 20: the checker went down BETWEEN the first (real) fail and the retry's check. The
+            // retry may well have fixed the output — an outage verdict must not annotate/coach it.
+            if (second.checkerError) {
+              ctx.emit?.({ note: `⚠ verification checker unavailable on the retry — surfacing ${target} result UNVERIFIED` });
+              bind(retry.trace.outcome === "completed" ? "done" : retry.trace.outcome === "blocked" ? "blocked" : "failed",
+                   "verification checker unavailable — settled from run outcome", retry.runId);
+              return { to: target, team: guard.team, runId: retry.runId, outputArtifacts: retry.trace.artifacts, summary: retry.text, verification: second.verdict };
+            }
+            child = retry;
+            verdict = second.verdict;
+            if (verdict.pass) ctx.emit?.({ note: `✓ ${target} passed verification after one retry` });
+            else ctx.emit?.({ note: `⚠ ${target} still failed verification after retry: ${verdict.reasons.join("; ")} — surfacing result with the failed verdict` });
+          }
+
+          // Criteria was set: always attach the verdict so the parent (and captain) sees the caveat.
+          // A failed verdict here ALSO lands the annotation + coaching side effects (via surface).
+          return surface(verdict, child);
+        } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e);
+          ctx.notes.push(`delegate failed: ${msg}`);
+          // The item was bound `in_progress` before the spawn. Settle it here rather than stranding it
+          // until the next boot's reconcilePlans finds it and calls it "interrupted" — it isn't; the
+          // delegation genuinely failed, and this run is still alive to say so.
+          bind("failed", `delegation threw: ${msg}`);
+          return { error: msg };
+        }
+      },
+    });
+
+  // Plan 04 — background delegation. dispatch_task fires-and-forgets (returns a taskId immediately);
+  // check_task / await_task follow up. Results come back BY REFERENCE (summary + handles), never the
+  // inlined payload. Requires a host scheduler (the REPL wires ctx.dispatchTask); when unwired the
+  // tool cleanly reports it (a headless/unit context has no background runner).
+  if (has("dispatch_task"))
+    set.dispatch_task = tool({
+      description:
+        "Kick a goal off to another agent in the BACKGROUND and keep working — fire-and-forget. Returns " +
+        "a taskId immediately; the task runs off-turn. Use this (instead of delegate_task, which BLOCKS " +
+        "until the child returns) when you don't need the result right now — e.g. long research you'll " +
+        "check on later. Follow up with check_task(taskId) for status or await_task(taskId) to block on " +
+        "it when you finally need it. Results come back BY REFERENCE (a summary + artifact handles), never " +
+        "inlined. Hand inputs over with `inputArtifacts`. Unlike delegate_task, `criteria` here rides " +
+        "into the worker's brief but is NOT independently verified at settle (no checker, no retry on " +
+        "the background path). `to` may be an agent id or a team id, resolved the same way delegate_task resolves it.",
+      inputSchema: z.object({
+        to: z.string().describe("an agent id, or a team id (ids share one namespace)"),
+        goal: z.string(),
+        context: z.string().optional(),
+        criteria: z.string().optional().describe("acceptance criteria, passed to the worker in its brief; NOT independently checked on the background path (unlike delegate_task)"),
+        inputArtifacts: z.array(z.string()).optional().describe("artifact handles ('id' or 'id@vN') to hand to the task by reference"),
+        itemId: z.string().optional().describe("an item on your plan this task fulfils; the ENGINE ticks it when the task settles, possibly turns later"),
+      }),
+      execute: async ({ to, goal, context, criteria, inputArtifacts, itemId }) => {
+        if (!ctx.dispatchTask) return { error: "background dispatch is not available in this context — use delegate_task instead" };
+        const budgetMsg = () => `work item budget (${agent.budgets.maxWorkItemsPerRequest}) exhausted`;
+        // A dispatch consumes a work item like a delegation — config disposes fan-out either way.
+        ctx.workItems.n += 1;
+        if (ctx.workItems.n > agent.budgets.maxWorkItemsPerRequest) {
+          ctx.notes.push(`dispatch refused: ${budgetMsg()}`);
+          return { error: budgetMsg() };
+        }
+        // Plan 19: a team is resolved to a concrete agent HERE, on the dispatching turn — not later when
+        // the background run starts. The task record then names the agent that actually ran, and a
+        // membership change between dispatch and settle cannot silently move the work.
+        const guard = ctx.resolveDelegation(to, goal);
+        if (!guard.ok) { ctx.notes.push(`dispatch refused: ${guard.error}`); return { error: guard.error }; }
+        const target = guard.agentId;
+        if (guard.note) { ctx.notes.push(guard.note); ctx.emit?.({ note: guard.note }); }
+        // Resolve input handles up front; drop (and note) dead refs rather than dispatch a broken brief.
+        const resolved: string[] = [], dropped: string[] = [];
+        for (const h of inputArtifacts ?? []) (readArtifact(ctx.ws, h) ? resolved : dropped).push(h);
+        if (dropped.length) ctx.notes.push(`dispatch: dropped unknown input artifact(s) ${dropped.join(", ")}`);
+        const r = await ctx.dispatchTask({ to: target, goal, context, criteria, inputArtifacts: resolved });
+        if ("error" in r) { ctx.notes.push(`dispatch failed: ${r.error}`); return r; }
+        ctx.notes.push(`dispatched ${r.taskId} → ${target}`);
+        // Plan 18: bind the item to the TASK id. The dispatch returns immediately and the task settles
+        // off-turn — possibly several conversation turns later — so the settle path (REPL) is what ticks
+        // this item, via findPlanItemByBoundRun. The binding is what lets it find the item at all.
+        if (itemId && ctx.plan) {
+          const tick = ctx.plan.tick({ itemId, status: "in_progress", note: `dispatched to ${target}`, by: "engine", boundRunId: r.taskId });
+          if (!tick.ok) ctx.notes.push(`plan bind failed (${itemId}): ${tick.rejected}`);
+          else ctx.emit?.({ plan: ctx.plan.read() ?? undefined });
+        }
+        return { taskId: r.taskId, status: "queued", to: target, team: guard.team, note: `running in background — check_task("${r.taskId}") for status, or await_task to block on it` };
+      },
+    });
+
+  if (has("check_task"))
+    set.check_task = tool({
+      description: "Check a background task (from dispatch_task) WITHOUT blocking: returns its status (queued/running/completed/failed/interrupted/cancelled) plus a short summary and result handle when done. Reference-only — never the full payload; pull artifacts with read_artifact.",
+      inputSchema: z.object({ taskId: z.string() }),
+      execute: async ({ taskId }) => {
+        const t = readTaskState(ctx.ws, taskId);
+        if (!t) return { error: `no task "${taskId}"` };
+        return { taskId, status: t.status, to: t.agent, summary: t.summary ?? null, resultRef: t.resultRef ?? null, runId: t.rootRunId || null };
+      },
+    });
+
+  if (has("await_task"))
+    set.await_task = tool({
+      description: "BLOCK until a background task settles (bounded by a timeout), then return its final status + summary + result handle. Use when you dispatched work earlier and now genuinely need it before continuing. Reference-only — never the inlined payload.",
+      inputSchema: z.object({
+        taskId: z.string(),
+        timeoutMs: z.number().int().positive().max(600000).optional().describe("give up waiting after this many ms (default 120000)"),
+      }),
+      execute: async ({ taskId, timeoutMs }) => {
+        if (!ctx.awaitTask) {
+          // No scheduler wired: fall back to reading the record (already-settled tasks still resolve).
+          const t = readTaskState(ctx.ws, taskId);
+          if (!t) return { error: `no task "${taskId}"` };
+          return { taskId, status: t.status, summary: t.summary ?? null, resultRef: t.resultRef ?? null };
+        }
+        return { taskId, ...(await ctx.awaitTask(taskId, timeoutMs)) };
+      },
+    });
+
+  if (has("find_agents"))
+    set.find_agents = tool({
+      description: "Search the squad for agents whose role matches a capability. Returns top matches.",
+      inputSchema: z.object({ query: z.string(), k: z.number().int().positive().max(20).default(8) }),
+      execute: async ({ query, k }) => ({ matches: ctx.findAgents(query, k) }),
+    });
+
+  if (has("read_url"))
+    set.read_url = tool({
+      description: "Fetch a web page (e.g. an MCP server's setup docs) and return it as clean markdown. Requires FIRECRAWL_API_KEY in the environment.",
+      inputSchema: z.object({ url: z.string().url() }),
+      execute: async ({ url }) => {
+        const r = await scrapeUrl(url);
+        return "markdown" in r ? { markdown: r.markdown } : { error: r.error };
+      },
+    });
+
+  if (mcp && has("add_mcp_server"))
+    set.add_mcp_server = tool({
+      description: "Connect a NEW MCP server for the captain to approve. Provide a `url` for a remote/hosted server (with auth:'oauth' or headers), or a `command`/`args` for a local stdio server. Put any secret (API key, token) in `env` as { VAR_NAME: 'the-secret' } and reference it as ${VAR_NAME} in the url/headers — it is saved WITH the server and loaded into the environment immediately AND on every future boot, so the server just works now and after a restart. Returns the connection status + tool count; on error, fix the config and call again.",
+      inputSchema: z.object({
+        name: z.string().regex(/^[a-z][a-z0-9-]*$/, "lowercase id: letters, digits, hyphens"),
+        url: z.string().url().optional(),
+        auth: z.literal("oauth").optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+        command: z.string().optional(),
+        args: z.array(z.string()).optional(),
+        env: z.record(z.string(), z.string()).optional(),
+      }),
+      execute: async ({ name, url, auth, headers, command, args, env }) => {
+        const raw = url
+          ? { url, ...(auth ? { auth } : {}), ...(headers ? { headers } : {}), ...(env ? { env } : {}) }
+          : command
+            ? { command, ...(args ? { args } : {}), ...(env ? { env } : {}) }
+            : null;
+        if (!raw) return { error: "provide a `url` (remote server) or a `command` (local stdio server)" };
+        const parsed = McpServerConfig.safeParse(raw);
+        if (!parsed.success) return { error: `invalid server config: ${parsed.error.issues[0]?.message ?? "unknown"}` };
+        const spec = parsed.data;
+        const decision = await ctx.requestApproval({ kind: "add_mcp", name, spec });
+        if (decision.type !== "approve") return { rejected: true };
+        addMcpServer(ctx.ws, name, spec);
+        applyMcpEnv(ctx.ws); // load the new server's env into process.env NOW, so ${VAR} resolves on this connect
+        const status = await mcp.addServer(name, spec);
+        return { name, status: status.status, toolCount: status.toolCount, error: status.error };
+      },
+    });
+
+  if (has("ask_human"))
+    set.ask_human = tool({
+      description: "Ask the human captain a clarifying question with 2-4 options when intent is ambiguous. The captain picks an option or types their own answer; you receive { answer } and continue.",
+      inputSchema: z.object({
+        question: z.string().describe("a single clear question"),
+        options: z.array(z.string()).min(2).max(4).describe("2-4 concrete choices"),
+      }),
+      execute: async ({ question, options }) => {
+        const d = await ctx.requestApproval({ kind: "ask_human", question, options });
+        return d.type === "answered" ? { answer: d.answer } : { cancelled: true };
+      },
+    });
+
+  if (has("remember"))
+    set.remember = tool({
+      description: "Save a durable fact / decision / entity to the squad's shared knowledgebase, optionally linking it to existing nodes with typed edges (rel e.g. relates_to, depends_on, contradicts). Returns the node id — recall first to get ids to link to.",
+      inputSchema: z.object({
+        title: z.string(),
+        content: z.string(),
+        kind: z.string().default("fact"),
+        summary: z.string().optional(),
+        edges: z.array(z.object({ to: z.string(), rel: z.string().default("relates_to") })).default([]),
+      }),
+      execute: async ({ title, content, kind, summary, edges }) => {
+        const requested = edges ?? [];
+        const valid = requested.filter((e) => nodeExists(ctx.db, e.to)); // drop dangling edge targets
+        const node = KbNode.parse({
+          id: mkKbId(), title, content, kind, summary, scope: "squad",
+          source: ctx.ingestSource ?? `${ctx.agentId}:${ctx.runId}`, edges: valid, created: new Date().toISOString(),
+        });
+        writeNode(ctx.ws, ctx.db, node);
+        if (ctx.embed) {
+          try { putVector(ctx.db, node.id, "kb", await ctx.embed(`${node.title}\n${node.summary ?? ""}\n${node.content}`)); }
+          catch { /* semantic index is best-effort; keyword+graph still works */ }
+        }
+        ctx.notes.push(`remembered ${node.id}`);
+        return { id: node.id, edgesAdded: valid.length, edgesDropped: requested.length - valid.length };
+      },
+    });
+
+  if (has("recall"))
+    set.recall = tool({
+      description: "Search the squad's shared knowledgebase and its typed-edge graph. Returns matching nodes plus their linked neighbors — by meaning (semantic when available) and by relationship.",
+      inputSchema: z.object({
+        query: z.string(),
+        k: z.number().int().positive().max(20).default(6),
+        hops: z.number().int().min(0).max(2).default(1),
+        rels: z.array(z.string()).optional(),
+      }),
+      execute: async ({ query, k, hops, rels }) => {
+        const r = await searchKnowledge({ db: ctx.db, query, embed: ctx.embed, k, hops, rels });
+        return { mode: r.mode, hits: r.hits.map((h) => ({ id: h.id, title: h.title, summary: h.summary, via: h.via, score: +h.score.toFixed(3) })) };
+      },
+    });
+
+  if (has("read_source"))
+    set.read_source = tool({
+      description: "Read an admin-authored source document from kb/sources/ so you can extract entities from it. `path` is like \"sources/architecture.md\" or \"architecture.md\".",
+      inputSchema: z.object({ path: z.string() }),
+      execute: async ({ path }) => {
+        const name = path.replace(/^sources\//, "");
+        const dir = paths.kbSourceDir(ctx.ws);
+        const full = resolve(dir, name);
+        if (full !== dir && !full.startsWith(dir + sep)) return { error: "path must be a file under kb/sources/" };
+        try { return { content: await readFile(full, "utf8") }; }
+        catch { return { error: `no such source: ${name}` }; }
+      },
+    });
+
+  if (has("forget"))
+    set.forget = tool({
+      description: "Prune the knowledgebase: cascade-delete nodes matching a filter, plus their edges and vectors. Filter by `kind` (e.g. decision), `sourcePrefix` (e.g. \"worker-x:\" for one assistant's memory, or \"sources/foo.md@\" for a doc), and/or explicit `ids`. At least one clause is required.",
+      inputSchema: z.object({
+        ids: z.array(z.string()).optional(),
+        kind: z.string().optional(),
+        sourcePrefix: z.string().optional(),
+      }),
+      execute: async ({ ids, kind, sourcePrefix }) => {
+        if (!ids?.length && !kind && !sourcePrefix) return { error: "provide at least one of ids, kind, or sourcePrefix" };
+        const r = forgetNodes(ctx.ws, ctx.db, { ids, kind, sourcePrefix });
+        ctx.notes.push(`forgot ${r.removedNodes} node(s)`);
+        return r;
+      },
+    });
+
+  if (has("reindex_knowledge"))
+    set.reindex_knowledge = tool({
+      description: "Rebuild the knowledge graph index from the canonical node files and refresh semantic vectors. Use after bulk hand-edits.",
+      inputSchema: z.object({}),
+      execute: async () => {
+        reindexKnowledge(ctx.ws, ctx.db);
+        const embedded = ctx.embed ? await reembedAll(ctx.db, ctx.embed) : 0;
+        return { reindexed: true, embedded };
+      },
+    });
+
+  if (has("propose_skill"))
+    set.propose_skill = tool({
+      description: "Propose a reusable skill (a reviewed step-by-step procedure for a repeatable operation) for the captain to approve. On approval it's saved and every agent can use it via use_skill.",
+      inputSchema: z.object({
+        name: z.string(),
+        description: z.string().describe("when to use this skill"),
+        body: z.string().describe("the step-by-step procedure"),
+        tags: z.array(z.string()).default([]),
+      }),
+      execute: async ({ name, description, body, tags }) => {
+        const draft = { name, description, body, tags: tags ?? [] };
+        const d = await ctx.requestApproval({ kind: "propose_skill", draft });
+        if (d.type !== "approve") return { rejected: true };
+        const skill = Skill.parse({ id: mkSkillId(), name, description, body, tags: draft.tags, status: "active", created: new Date().toISOString() });
+        writeSkill(ctx.ws, ctx.db, skill);
+        ctx.notes.push(`proposed skill ${skill.id}`);
+        return { id: skill.id };
+      },
+    });
+
+  if (has("run_command"))
+    set.run_command = tool({
+      description: "Run a shell command in the workspace. It runs in a restricted SANDBOX first (no network; writes confined to the workspace) — a command the sandbox completes returns straight away. The safety guard clears benign commands; anything it flags — OR any command proposed after UNTRUSTED content (a fetched web page or an MCP tool result) has entered this run — needs the captain's approval first. A command the sandbox can't complete escalates to a captain-approved unsandboxed run. Returns { exitCode, stdout, stderr, sandbox }.",
+      inputSchema: z.object({ command: z.string(), cwd: z.string().optional().describe("working directory (defaults to the workspace); a cwd outside the workspace can't be sandbox-confined, so it needs the captain's approval") }),
+      execute: async ({ command, cwd }) => {
+        const classify = ctx.classifyCommand ?? classifyCommand;
+        const sandboxed = ctx.runSandboxed ?? runSandboxed;
+        const run = ctx.runShell ?? runShell;
+        const workdir = cwd ?? ctx.ws;
+        const v = classify(command);
+        const tainted = ctx.untrusted?.entered === true;
+        // Sandbox-escape guard (Plan 08): the model can name its own `cwd`, but the sandbox's writable
+        // set is anchored to ctx.ws — never the model cwd. A cwd that resolves OUTSIDE realpath(ctx.ws)
+        // is therefore NOT auto-runnable: we route it to the captain (who sees WHERE it runs) rather
+        // than silently widening the writable set or letting an unconfined write slip through.
+        const escapesWs = cwd !== undefined && !isInsideWorkspace(ctx.ws, workdir);
+
+        // Explicit-review path — a dcg `block` verdict, the injection guard (untrusted content has
+        // already entered this run), OR a cwd that escapes the workspace routes the command to the
+        // captain's approval card. Critically, a dcg `allow` does NOT bypass the injection guard:
+        // ingest-untrusted-then-run-shell is the classic prompt-injection→execution chain, so once
+        // tainted the human MUST see the command. On approve it runs as the captain reviewed it (they
+        // inspected the exact command AND its cwd); on reject, nothing runs. No sandbox dance here — the
+        // human IS the gate for these.
+        if (v.decision !== "allow" || tainted || escapesWs) {
+          const parts: string[] = [];
+          if (tainted) parts.push(`untrusted content (${ctx.untrusted.sources.join(", ") || "external source"}) entered this run before this command — possible prompt-injection→execution`);
+          if (escapesWs) parts.push(`the working directory (${workdir}) is OUTSIDE the workspace (${ctx.ws}) — the sandbox can't confine writes there; approve to run it there UNSANDBOXED`);
+          if (v.decision !== "allow" && v.reason) parts.push(v.reason);
+          const reason = parts.join("; ") || "confirm to run";
+          const d = await ctx.requestApproval({ kind: "run_command", command, cwd: workdir, reason });
+          if (d.type !== "approve") return { rejected: true };
+          return { ...run(command, workdir), sandbox: "approved" as const };
+        }
+
+        // Auto-run path (dcg cleared it AND no untrusted content) — sandbox-then-escalate. Contain the
+        // command FIRST (least privilege: no network, writes confined to the workspace). A clean run —
+        // OR a benign non-zero exit the sandbox did NOT cause (e.g. `grep` no-match) — returns straight
+        // to the model with ZERO human friction. We ESCALATE (ask the captain to approve an unsandboxed
+        // run, never silently) only when either: the sandbox couldn't be enforced on this host, or it
+        // actively DENIED the command a privilege ("Operation not permitted" — a write-escape outside
+        // the workspace). NOTE (declared limitation): a network denial surfaces as an ordinary network
+        // error, indistinguishable from a real outage, so it is NOT auto-escalated — the model sees the
+        // failure and should reach the network via read_url / an MCP tool, not raw shell.
+        // Writable root is ctx.ws (NOT workdir) — the model's cwd never widens the confined write set.
+        const sb = sandboxed(command, workdir, ctx.ws);
+        const sandboxDenied = sb.enforced && sb.exitCode !== 0 && /operation not permitted|sandbox/i.test(sb.stderr);
+        if (sb.enforced && !sandboxDenied)
+          return { exitCode: sb.exitCode, stdout: sb.stdout, stderr: sb.stderr, sandbox: "enforced" as const };
+        const escalateReason = sb.enforced
+          ? `the sandbox DENIED this command an operation it needs (exit ${sb.exitCode}: "operation not permitted" — it tried to write outside the workspace). Approve to re-run WITHOUT the sandbox.`
+          : "no OS sandbox is enforced on this host — approve to run this command WITHOUT a sandbox.";
+        const d = await ctx.requestApproval({ kind: "run_command", command, cwd: workdir, reason: escalateReason });
+        if (d.type !== "approve")
+          return sb.enforced
+            ? { exitCode: sb.exitCode, stdout: sb.stdout, stderr: sb.stderr, sandbox: "enforced" as const, escalationDeclined: true }
+            : { rejected: true };
+        return { ...run(command, workdir), sandbox: "unsandboxed" as const };
+      },
+    });
+
+  // Skills are a universal agent capability (like the MCP-tools grant): every agent can discover and
+  // load reviewed procedures. Not gated by agent.tools; built-ins still win over MCP tools below.
+  set.find_skills = tool({
+    description: "Search the squad's reusable skills (reviewed procedures for repeatable operations) by what you're trying to do. Returns matching skill names + when to use them; call use_skill to load the full procedure.",
+    inputSchema: z.object({ query: z.string(), k: z.number().int().positive().max(20).default(6) }),
+    execute: async ({ query, k }) => ({ matches: rankSkills(getActiveSkills(ctx.db), query, k).map((h) => ({ id: h.id, name: h.name, description: h.description })) }),
+  });
+
+  set.use_skill = tool({
+    description: "Load the full step-by-step procedure for a skill by name, then follow it. Use this for repeatable operations so you do them the reviewed way with fewer mistakes.",
+    inputSchema: z.object({ name: z.string() }),
+    execute: async ({ name }) => {
+      const rows = getActiveSkills(ctx.db);
+      const s = rows.find((r) => r.name === name) ?? rows.find((r) => r.id === name);
+      return s ? { name: s.name, body: s.body } : { error: `no skill "${name}" — call find_skills to discover available skills` };
+    },
+  });
+
+  // Per-agent MCP allowlist (Plan 08 security hardening). An agent opts into MCP capability the same
+  // way it opts into a built-in: a `mcp:<server>` entry in agent.tools grants EVERY tool that server
+  // exposes; `mcp:<server>/<tool>` grants exactly one. Ungranted MCP tools are NEVER handed to this
+  // agent — previously every connected server's tools went to every agent ("gatekeeping can come
+  // later"); this IS that gate. Built-ins already in `set` win (first-wins), so an MCP tool still
+  // can't shadow a privileged built-in (e.g. a server tool namespacing to create_agent).
+  const mcpToolNames = new Set<string>();
+  if (mcp)
+    for (const ref of granted) {
+      if (!ref.startsWith("mcp:")) continue;
+      for (const [k, v] of Object.entries(mcp.toolsForRef(ref.slice("mcp:".length))))
+        if (!(k in set)) { set[k] = v; mcpToolNames.add(k); }
+    }
+
+  // Untrusted-content sources (Plan 08 injection guard): every channel that can carry
+  // attacker-influenceable text INTO this run. instrument() arms ctx.untrusted the moment one of these
+  // returns; run_command then forces the captain's approval (a dcg `allow` no longer auto-runs it).
+  //   - read_url .................. a fetched web page
+  //   - ANY granted MCP tool ...... arbitrary server-returned content
+  //   - read_artifact ............. artifacts are the PRIMARY cross-agent hand-off (fetch a page →
+  //                                 save_artifact → read it elsewhere), so a read carries prior taint
+  //   - recall / search_knowledge . the shared KB can hold ingested (hence tainted) content
+  //   - read_source ............... admin-authored source docs are still externally-authored text
+  //   - delegate/await/dispatch/check_task — a child's summary is content a child run may have ingested
+  // Deliberately conservative: touching ANY of these arms the guard, erring toward MORE approval, never
+  // less. Names not present in `set` (ungranted tools) simply never fire — the instrument seam only
+  // flips the guard for a tool that actually ran, so listing them all here is safe and future-proof.
+  const untrustedSources = new Set<string>(mcpToolNames);
+  for (const name of [
+    "read_url", "read_artifact", "recall", "read_source",
+    "delegate_task", "await_task", "dispatch_task", "check_task",
+    // list_annotations surfaces feedback bodies — an agent may have ingested a page then annotated, so
+    // annotation text is attacker-influenceable content entering this run (same reasoning as read_artifact).
+    "list_annotations",
+  ]) untrustedSources.add(name);
+
+  return instrument(set, ctx, untrustedSources);
+}
+
+/** Wrap every tool's `execute()` — the ONE seam Plan 02 (accurate span bars) and Plan 10 (live
+ *  "working: read_url …" status) share. Emits `tool_start`/`tool_end` (with a redacted, capped
+ *  argsPreview) into the run's `spanEvents` (→ transcript.jsonl → waterfall) and a live typed phase
+ *  via `ctx.emitStep`. Rebuilds each tool object (never mutates the shared MCP tool instances). A
+ *  `delegate_task` result's `runId` is captured on `tool_end` so the waterfall can nest the child
+ *  run under its delegating tool span.
+ *
+ *  Plan 08: this is also where the injection guard arms. When a tool in `untrustedSources` (read_url,
+ *  any granted MCP tool, read_artifact, recall/search_knowledge, read_source, or a delegation-result
+ *  tool — see the set built in toolsForAgent) RETURNS, we flip ctx.untrusted.entered — attacker-
+ *  influenceable content has now entered the run, so a later run_command must be human-confirmed.
+ *  Deliberately conservative: touching an untrusted source at all arms the guard (even an error return
+ *  means the run reacted to external I/O), which errs toward MORE approval, never less. */
+function instrument(set: ToolSet, ctx: RunContext, untrustedSources?: Set<string>): ToolSet {
+  let seq = 0;
+  const out: ToolSet = {};
+  for (const [name, t] of Object.entries(set)) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const orig = (t as any).execute;
+    if (typeof orig !== "function") { out[name] = t; continue; }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const execute = async (input: unknown, options: any) => {
+      const callId: string = options?.toolCallId ?? `${name}#${++seq}`;
+      const preview = argsPreview(name, input);
+      ctx.spanEvents?.push({ ts: new Date().toISOString(), kind: "tool_start", data: { tool: name, callId, argsPreview: preview, args: capJson(input) } });
+      ctx.emitStep?.({ phase: "tool_start", tool: name, argsPreview: preview, callId });
+      // Plan 16: taicho's own tool span — named `<tool> · <preview>` (e.g. "delegate_task · researcher:
+      // …", "write_artifact · findings") so the trace reads meaningfully, carrying args in / result out,
+      // and made ACTIVE so a delegated child run nests under this exact tool span.
+      const tel = ctx.telemetry;
+      const span = tel?.tracerFor(ctx.agentId).startSpan(preview ? `${name} · ${preview}` : name, {
+        attributes: { "taicho.tool": name, ...(tel.captureContent ? ioAttrs("input", capJson(input)) : {}) },
+      });
+      let result: unknown, err: string | undefined;
+      try {
+        result = await (span
+          ? otelContext.with(otelTrace.setSpan(otelContext.active(), span), () => orig(input, options))
+          : orig(input, options));
+        // Arm the injection guard once an untrusted source returns (see fn doc). Guarded on
+        // ctx.untrusted so partial unit-test contexts without the field don't crash.
+        if (ctx.untrusted && untrustedSources?.has(name)) {
+          ctx.untrusted.entered = true;
+          if (!ctx.untrusted.sources.includes(name)) ctx.untrusted.sources.push(name);
+        }
+        return result;
+      } catch (e) {
+        err = e instanceof Error ? e.message : String(e);
+        span?.setStatus({ code: SpanStatusCode.ERROR, message: err });
+        throw e;
+      } finally {
+        const childRunId =
+          result && typeof result === "object" && typeof (result as { runId?: unknown }).runId === "string"
+            ? (result as { runId: string }).runId
+            : undefined;
+        ctx.spanEvents?.push({ ts: new Date().toISOString(), kind: "tool_end", data: { tool: name, callId, ok: !err, error: err, childRunId, result: capJson(result) } });
+        ctx.emitStep?.({ phase: "tool_end", tool: name, ok: !err, callId });
+        if (span) {
+          if (tel!.captureContent && !err) span.setAttributes(ioAttrs("output", capJson(result)));
+          if (childRunId) span.setAttribute("taicho.child_run", childRunId);
+          span.end();
+        }
+      }
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    out[name] = { ...(t as any), execute } as any;
+  }
+  return out;
+}