@forwardimpact/libharness 1.3.0 → 1.4.0

package/src/commands/run.js

@@ -1,11 +1,23 @@
 import { Writable } from "node:stream";
 import { resolve } from "node:path";
 import { isoTimestamp } from "@forwardimpact/libutil";
+import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import { createAgentRunner } from "../agent-runner.js";
-import { composeProfilePrompt } from "../profile-prompt.js";
+import {
+  advisorGuidance,
+  createAdvisor,
+  createAdvisorBudget,
+} from "../advisor.js";
+import { advisorTool } from "../orchestration-toolkit.js";
+import {
+  composeProfilePrompt,
+  composeSystemPrompt,
+} from "../profile-prompt.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
+import { createTranscriptRecorder } from "../transcript-recorder.js";
 import { SequenceCounter } from "../sequence-counter.js";
+import { parseAdvisorOptions } from "./advisor-flags.js";
 import { resolveWorkTracker } from "./work-tracker.js";
 import { resolveTaskContent } from "./task-input.js";
 import { createServiceConfig } from "@forwardimpact/libconfig";
@@ -15,7 +27,7 @@ import { AGENT_MODEL } from "@forwardimpact/libutil/models";
  * Parse and validate run command options from parsed values.
  * @param {object} values - Parsed option values from cli.parse()
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
- * @returns {{ taskContent: string, cwd: string, model: string, maxTurns: number, outputPath: string|undefined, agentProfile: string|undefined, workTracker: string, allowedTools: string[] }}
+ * @returns {{ taskContent: string, taskAmend: string|undefined, cwd: string, agentModel: string, maxTurns: number, outputPath: string|undefined, agentProfile: string|undefined, workTracker: string, allowedTools: string[], mcpServer: string|undefined, advisorModel: string|undefined, advisorMaxUses: number }}
  */
 export function parseRunOptions(values, runtime) {
   const { task: taskContent, amend: taskAmend } = resolveTaskContent(
@@ -40,9 +52,148 @@ export function parseRunOptions(values, runtime) {
       "Bash,Read,Glob,Grep,Write,Edit,Agent,TodoWrite"
     ).split(","),
     mcpServer: values["mcp-server"] || undefined,
+    ...parseAdvisorOptions(values),
   };
 }
 
+const devNull = new Writable({
+  write(_chunk, _enc, cb) {
+    cb();
+  },
+});
+
+/**
+ * Wire the run-mode agent session: external MCP entry, `LIBHARNESS_*` env
+ * writes, system-prompt composition, and — when an advisor model is set —
+ * the advisor wiring (budget, recorder, advisor session, dedicated MCP
+ * server holding only the `Advisor` tool). Extracted from `runRunCommand`
+ * so tests can inject a fake `query`.
+ *
+ * Run mode has no stop path (the command simply awaits the runner), so the
+ * consult timeout is deliberately the advisor's only guard.
+ *
+ * @param {object} deps
+ * @param {ReturnType<typeof parseRunOptions>} deps.opts
+ * @param {import("../redaction.js").Redactor} deps.redactor
+ * @param {import("stream").Writable} deps.output - Envelope NDJSON sink.
+ * @param {SequenceCounter} deps.counter
+ * @param {function} deps.query - SDK query function.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime
+ * @returns {Promise<{runner: import("../agent-runner.js").AgentRunner, advisor: object|null}>}
+ */
+export async function wireRunSession({
+  opts,
+  redactor,
+  output,
+  counter,
+  query,
+  runtime,
+}) {
+  const emitEnvelope = (source, event) => {
+    output.write(
+      JSON.stringify(
+        redactor.redactValue({ source, seq: counter.next(), event }),
+      ) + "\n",
+    );
+  };
+  const onLine = (line) => emitEnvelope("agent", JSON.parse(line));
+
+  let mcpServers = null;
+  const allowedTools = opts.allowedTools;
+  if (opts.mcpServer) {
+    const mcpConfig = await createServiceConfig("mcp");
+    mcpServers = {
+      [opts.mcpServer]: {
+        type: "http",
+        url: mcpConfig.url,
+        headers: { Authorization: `Bearer ${mcpConfig.mcpToken()}` },
+      },
+    };
+    allowedTools.push(`mcp__${opts.mcpServer}__*`);
+  }
+
+  if (opts.agentProfile) {
+    runtime.proc.env.LIBHARNESS_AGENT_PROFILE = opts.agentProfile;
+  }
+  // Unconditional so the default "github" is observable to the agent's
+  // active-tracker resolution, mirroring --agent-profile's env write above.
+  runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
+
+  // With a profile, the consult guidance rides the profile composer's
+  // amendment parameter; with no profile, a preset-append prompt carries
+  // the guidance as its only session-protocol fragment. Advisor off and no
+  // profile means no system prompt — today's behavior, unchanged.
+  let systemPrompt;
+  if (opts.agentProfile) {
+    systemPrompt = composeProfilePrompt(opts.agentProfile, {
+      profilesDir: resolve(opts.cwd, ".claude/agents"),
+      runtime,
+      ...(opts.advisorModel && {
+        amend: advisorGuidance(opts.advisorMaxUses),
+      }),
+    });
+  } else if (opts.advisorModel) {
+    systemPrompt = composeSystemPrompt({
+      role: "agent",
+      trailer: advisorGuidance(opts.advisorMaxUses),
+      runtime,
+    });
+  }
+
+  let advisor = null;
+  let recorder = null;
+  if (opts.advisorModel) {
+    const budget = createAdvisorBudget(opts.advisorMaxUses);
+    recorder = createTranscriptRecorder({ systemPrompt, redactor });
+    advisor = createAdvisor({
+      model: opts.advisorModel,
+      cwd: opts.cwd,
+      query,
+      recorder,
+      redactor,
+      runtime,
+      onLine: (line) => emitEnvelope("advisor", JSON.parse(line)),
+    });
+    const advTool = advisorTool({
+      from: "agent",
+      consult: (q) => advisor.consult(q),
+      emit: (event) => emitEnvelope("orchestrator", event),
+      budget,
+      model: opts.advisorModel,
+    });
+    // No allowlist push: in-process SDK MCP servers work under
+    // bypassPermissions without allowlist entries (loop-mode precedent).
+    mcpServers = {
+      ...mcpServers,
+      advisor: createSdkMcpServer({ name: "advisor", tools: [advTool] }),
+    };
+  }
+
+  const runner = createAgentRunner({
+    cwd: opts.cwd,
+    query,
+    output: devNull,
+    model: opts.agentModel,
+    maxTurns: opts.maxTurns,
+    allowedTools,
+    onLine: recorder
+      ? (line) => {
+          onLine(line);
+          recorder.recordMessage(line);
+        }
+      : onLine,
+    ...(recorder && { onPrompt: (text) => recorder.recordPrompt(text) }),
+    settingSources: ["project"],
+    systemPrompt,
+    taskAmend: opts.taskAmend,
+    mcpServers,
+    redactor,
+    runtime,
+  });
+
+  return { runner, advisor };
+}
+
 /**
  * Run command — execute a single agent via the Claude Agent SDK.
  *
@@ -53,18 +204,7 @@ export function parseRunOptions(values, runtime) {
  */
 export async function runRunCommand(ctx) {
   const runtime = ctx.deps.runtime;
-  const {
-    taskContent,
-    taskAmend,
-    cwd,
-    agentModel,
-    maxTurns,
-    outputPath,
-    agentProfile,
-    workTracker,
-    allowedTools,
-    mcpServer,
-  } = parseRunOptions(ctx.options, runtime);
+  const opts = parseRunOptions(ctx.options, runtime);
 
   // Build the redactor as the first observable side-effect after option
   // parsing — the env snapshot must freeze BEFORE any in-process
@@ -73,8 +213,8 @@ export async function runRunCommand(ctx) {
 
   // When --output is specified, stream text to stdout while writing NDJSON to file.
   // Otherwise, write NDJSON directly to stdout (backwards-compatible).
-  const fileStream = outputPath
-    ? runtime.fs.createWriteStream(outputPath)
+  const fileStream = opts.outputPath
+    ? runtime.fs.createWriteStream(opts.outputPath)
     : null;
   const output = fileStream
     ? createTeeWriter({
@@ -86,62 +226,17 @@ export async function runRunCommand(ctx) {
     : runtime.proc.stdout;
 
   const counter = new SequenceCounter();
-  const devNull = new Writable({
-    write(_chunk, _enc, cb) {
-      cb();
-    },
-  });
-  const onLine = (line) => {
-    const event = JSON.parse(line);
-    const tagged = { source: "agent", seq: counter.next(), event };
-    output.write(JSON.stringify(redactor.redactValue(tagged)) + "\n");
-  };
-
-  let mcpServers = null;
-  if (mcpServer) {
-    const mcpConfig = await createServiceConfig("mcp");
-    mcpServers = {
-      [mcpServer]: {
-        type: "http",
-        url: mcpConfig.url,
-        headers: { Authorization: `Bearer ${mcpConfig.mcpToken()}` },
-      },
-    };
-    allowedTools.push(`mcp__${mcpServer}__*`);
-  }
-
-  if (agentProfile) {
-    runtime.proc.env.LIBHARNESS_AGENT_PROFILE = agentProfile;
-  }
-  // Unconditional so the default "github" is observable to the agent's
-  // active-tracker resolution, mirroring --agent-profile's env write above.
-  runtime.proc.env.LIBHARNESS_WORK_TRACKER = workTracker;
-
-  const systemPrompt = agentProfile
-    ? composeProfilePrompt(agentProfile, {
-        profilesDir: resolve(cwd, ".claude/agents"),
-        runtime,
-      })
-    : undefined;
-
   const { query } = await import("@anthropic-ai/claude-agent-sdk");
-  const runner = createAgentRunner({
-    cwd,
-    query,
-    output: devNull,
-    model: agentModel,
-    maxTurns,
-    allowedTools,
-    onLine,
-    settingSources: ["project"],
-    systemPrompt,
-    taskAmend,
-    mcpServers,
+  const { runner } = await wireRunSession({
+    opts,
     redactor,
+    output,
+    counter,
+    query,
     runtime,
   });
 
-  const result = await runner.run(taskContent);
+  const result = await runner.run(opts.taskContent);
 
   if (fileStream) {
     await new Promise((r) => output.end(r));

package/src/commands/supervise.js

@@ -3,6 +3,7 @@ import { isoTimestamp } from "@forwardimpact/libutil";
 import { createSupervisor } from "../supervisor.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
+import { parseAdvisorOptions } from "./advisor-flags.js";
 import { resolveTaskContent } from "./task-input.js";
 import { resolveWorkTracker } from "./work-tracker.js";
 import { createServiceConfig } from "@forwardimpact/libconfig";
@@ -52,6 +53,7 @@ export async function parseSuperviseOptions(values, runtime) {
       ? supervisorAllowedToolsRaw.split(",")
       : undefined,
     mcpServer: values["mcp-server"] || undefined,
+    ...parseAdvisorOptions(values),
   };
 }
 
@@ -125,6 +127,8 @@ export async function runSuperviseCommand(ctx) {
     agentMcpServers,
     redactor,
     runtime,
+    advisorModel: opts.advisorModel,
+    advisorMaxUses: opts.advisorMaxUses,
   });
 
   const result = await supervisor.run(opts.taskContent);

package/src/discuss-tools.js

@@ -107,7 +107,7 @@ const ACKNOWLEDGE_DESC =
   "Acknowledge an Ask before starting work. Posts a visible comment on the thread. Does not discharge the Ask — you still owe an Answer.";
 
 /** Discuss-mode agent tool server. */
-export function createDiscussAgentToolServer(ctx, { from }) {
+export function createDiscussAgentToolServer(ctx, { from, extraTools = [] }) {
   return orchestrationServer([
     ...baseTools(ctx, { from, defaultTo: "lead", broadcast: true }),
     requestForCommentTool(ctx),
@@ -133,6 +133,7 @@ export function createDiscussAgentToolServer(ctx, { from }) {
         return { content: [{ type: "text", text: "Acknowledged." }] };
       },
     ),
+    ...extraTools,
   ]);
 }
 

package/src/discusser.js

@@ -22,7 +22,16 @@ import { ReplyEmitter } from "./reply-emitter.js";
 import { composeSystemPrompt } from "./profile-prompt.js";
 import { SequenceCounter } from "./sequence-counter.js";
 import { createMessageBus } from "./message-bus.js";
-import { createOrchestrationContext } from "./orchestration-toolkit.js";
+import {
+  advisorTool,
+  createOrchestrationContext,
+} from "./orchestration-toolkit.js";
+import {
+  createAdvisor,
+  createAdvisorBudget,
+  withAdvisorGuidance,
+} from "./advisor.js";
+import { createTranscriptRecorder } from "./transcript-recorder.js";
 import {
   createDiscussLeadToolServer,
   createDiscussAgentToolServer,
@@ -206,6 +215,8 @@ export class Discusser {
  * @param {string|null} [deps.callbackUrl]
  * @param {string|null} [deps.inboxUrl]
  * @param {string|null} [deps.correlationId]
+ * @param {string} [deps.advisorModel] - Claude model for advisor consults; absent means no Advisor tool is offered.
+ * @param {number} [deps.advisorMaxUses] - Session-wide consult budget shared by all agent participants (default 3).
  * @returns {Discusser}
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: factory wires N runners + resume hydration paths
@@ -228,6 +239,8 @@ export function createDiscusser({
   inboxUrl,
   correlationId,
   runtime,
+  advisorModel,
+  advisorMaxUses,
 }) {
   if (!redactor) throw new Error("redactor is required");
   if (!runtime) throw new Error("runtime is required");
@@ -306,11 +319,54 @@ export function createDiscusser({
   let discusser;
   const leadServer = createDiscussLeadToolServer(ctx);
 
+  // One budget per session, shared by every agent's Advisor handler.
+  const budget = advisorModel ? createAdvisorBudget(advisorMaxUses ?? 3) : null;
+
   const agents = resolvedConfigs.map((config) => {
+    // Everything advisor-shaped is gated on advisorModel; with it unset the
+    // composed prompt and tool surface are byte-identical to today's.
+    const systemPrompt = composeSystemPrompt({
+      role: "agent",
+      profile: config.agentProfile,
+      profilesDir: resolvedProfilesDir,
+      trailer: DISCUSS_AGENT_SYSTEM_PROMPT,
+      amend: withAdvisorGuidance(config.systemPromptAmend, budget),
+      runtime,
+    });
+
+    let recorder = null;
+    let extraTools;
+    if (advisorModel) {
+      recorder = createTranscriptRecorder({ systemPrompt, redactor });
+      // Late-bound through the `let discusser` closure — the instance does
+      // not exist yet when the advisor and tool are built.
+      const advisor = createAdvisor({
+        model: advisorModel,
+        cwd: config.cwd ?? resolvedLeadCwd,
+        query,
+        recorder,
+        redactor,
+        runtime,
+        onLine: (line) => discusser.loop.emitLine("advisor", line),
+      });
+      abortController.signal.addEventListener("abort", () => advisor.abort());
+      extraTools = [
+        advisorTool({
+          from: config.name,
+          consult: (q) => advisor.consult(q),
+          emit: (e) => discusser.loop.emitOrchestratorEvent(e),
+          budget,
+          model: advisorModel,
+        }),
+      ];
+    }
+
     const agentServer = createDiscussAgentToolServer(ctx, {
       from: config.name,
+      ...(extraTools && { extraTools }),
     });
 
+    const emitAgentLine = (line) => discusser.loop.emitLine(config.name, line);
     const runner = createAgentRunner({
       cwd: config.cwd ?? resolvedLeadCwd,
       query,
@@ -318,17 +374,16 @@ export function createDiscusser({
       model: agentModel ?? AGENT_MODEL,
       maxTurns: config.maxTurns ?? 50,
       allowedTools: config.allowedTools,
-      onLine: (line) => discusser.loop.emitLine(config.name, line),
+      onLine: recorder
+        ? (line) => {
+            emitAgentLine(line);
+            recorder.recordMessage(line);
+          }
+        : emitAgentLine,
+      ...(recorder && { onPrompt: (text) => recorder.recordPrompt(text) }),
       mcpServers: { orchestration: agentServer },
       settingSources: ["project"],
-      systemPrompt: composeSystemPrompt({
-        role: "agent",
-        profile: config.agentProfile,
-        profilesDir: resolvedProfilesDir,
-        trailer: DISCUSS_AGENT_SYSTEM_PROMPT,
-        amend: config.systemPromptAmend,
-        runtime,
-      }),
+      systemPrompt,
       redactor,
     });
 

package/src/facilitator.js

@@ -12,11 +12,18 @@ import { createAgentRunner } from "./agent-runner.js";
 import { composeSystemPrompt } from "./profile-prompt.js";
 import { createMessageBus } from "./message-bus.js";
 import {
+  advisorTool,
   createOrchestrationContext,
   createFacilitatorToolServer,
   createFacilitatedAgentToolServer,
 } from "./orchestration-toolkit.js";
 import { OrchestrationLoop } from "./orchestration-loop.js";
+import {
+  createAdvisor,
+  createAdvisorBudget,
+  withAdvisorGuidance,
+} from "./advisor.js";
+import { createTranscriptRecorder } from "./transcript-recorder.js";
 
 /** System prompt for the facilitator lead. L0 mechanics only per COALIGNED. */
 export const FACILITATOR_SYSTEM_PROMPT =
@@ -92,6 +99,8 @@ const devNull = new Writable({
  * @param {string} [deps.facilitatorProfile]
  * @param {string} [deps.profilesDir]
  * @param {string} [deps.taskAmend]
+ * @param {string} [deps.advisorModel] - Claude model for advisor consults; absent means no Advisor tool is offered.
+ * @param {number} [deps.advisorMaxUses] - Session-wide consult budget shared by all agent participants (default 3).
  * @returns {Facilitator}
  */
 export function createFacilitator({
@@ -110,6 +119,8 @@ export function createFacilitator({
   taskAmend,
   redactor,
   runtime,
+  advisorModel,
+  advisorMaxUses,
 }) {
   if (!redactor) throw new Error("redactor is required");
   if (!runtime) throw new Error("runtime is required");
@@ -129,11 +140,55 @@ export function createFacilitator({
 
   const facilitatorServer = createFacilitatorToolServer(ctx);
 
+  const abortController = new AbortController();
+  // One budget per session, shared by every agent's Advisor handler.
+  const budget = advisorModel ? createAdvisorBudget(advisorMaxUses ?? 3) : null;
+
   const agents = agentConfigs.map((config) => {
+    // Everything advisor-shaped is gated on advisorModel; with it unset the
+    // composed prompt and tool surface are byte-identical to today's.
+    const systemPrompt = composeSystemPrompt({
+      role: "agent",
+      profile: config.agentProfile,
+      profilesDir: resolvedProfilesDir,
+      trailer: FACILITATED_AGENT_SYSTEM_PROMPT,
+      amend: withAdvisorGuidance(config.systemPromptAmend, budget),
+      runtime,
+    });
+
+    let recorder = null;
+    let extraTools;
+    if (advisorModel) {
+      recorder = createTranscriptRecorder({ systemPrompt, redactor });
+      // Late-bound through the `let facilitator` closure — the instance
+      // does not exist yet when the advisor and tool are built.
+      const advisor = createAdvisor({
+        model: advisorModel,
+        cwd: config.cwd ?? facilitatorCwd,
+        query,
+        recorder,
+        redactor,
+        runtime,
+        onLine: (line) => facilitator.emitLine("advisor", line),
+      });
+      abortController.signal.addEventListener("abort", () => advisor.abort());
+      extraTools = [
+        advisorTool({
+          from: config.name,
+          consult: (q) => advisor.consult(q),
+          emit: (e) => facilitator.emitOrchestratorEvent(e),
+          budget,
+          model: advisorModel,
+        }),
+      ];
+    }
+
     const agentServer = createFacilitatedAgentToolServer(ctx, {
       from: config.name,
+      ...(extraTools && { extraTools }),
     });
 
+    const emitAgentLine = (line) => facilitator.emitLine(config.name, line);
     const runner = createAgentRunner({
       cwd: config.cwd ?? facilitatorCwd,
       query,
@@ -141,17 +196,16 @@ export function createFacilitator({
       model: agentModel ?? model,
       maxTurns: config.maxTurns ?? 50,
       allowedTools: config.allowedTools,
-      onLine: (line) => facilitator.emitLine(config.name, line),
+      onLine: recorder
+        ? (line) => {
+            emitAgentLine(line);
+            recorder.recordMessage(line);
+          }
+        : emitAgentLine,
+      ...(recorder && { onPrompt: (text) => recorder.recordPrompt(text) }),
       mcpServers: { orchestration: agentServer },
       settingSources: ["project"],
-      systemPrompt: composeSystemPrompt({
-        role: "agent",
-        profile: config.agentProfile,
-        profilesDir: resolvedProfilesDir,
-        trailer: FACILITATED_AGENT_SYSTEM_PROMPT,
-        amend: config.systemPromptAmend,
-        runtime,
-      }),
+      systemPrompt,
       redactor,
     });
 
@@ -200,6 +254,7 @@ export function createFacilitator({
     ctx,
     taskAmend,
     redactor,
+    abortController,
   });
   return facilitator;
 }

package/src/index.js

@@ -26,6 +26,7 @@ export {
 export { TeeWriter, createTeeWriter } from "./tee-writer.js";
 export { SequenceCounter, createSequenceCounter } from "./sequence-counter.js";
 export {
+  advisorTool,
   createOrchestrationContext,
   createRequestForCommentHandler,
   createSupervisorToolServer,
@@ -34,6 +35,14 @@ export {
   createFacilitatedAgentToolServer,
   createJudgeToolServer,
 } from "./orchestration-toolkit.js";
+export {
+  ADVISOR_SYSTEM_PROMPT,
+  advisorGuidance,
+  createAdvisor,
+  createAdvisorBudget,
+  DEFAULT_CONSULT_TIMEOUT_MS,
+} from "./advisor.js";
+export { createTranscriptRecorder } from "./transcript-recorder.js";
 export { MessageBus, createMessageBus } from "./message-bus.js";
 export { OrchestrationLoop } from "./orchestration-loop.js";
 export {

package/src/orchestration-toolkit.js

@@ -337,6 +337,59 @@ function concludeTool(ctx) {
   );
 }
 
+const ADVISOR_DESC =
+  "Consult a stronger model on one focused question. Your full session context (system prompt, prompts, transcript so far) is forwarded automatically — you cannot restrict it. The advice returns in the tool result. The consult budget is shared session-wide across all participants.";
+
+/**
+ * Build the `Advisor` consult tool for one caller. Mode-agnostic: loop
+ * modes pass it into the agent tool-server factories via `extraTools`;
+ * run mode gives it a dedicated server. No orchestration-context
+ * dependency — the budget object and emit callback are injected.
+ *
+ * @param {object} deps
+ * @param {string} deps.from - Caller's canonical name (event attribution).
+ * @param {(question: string) => Promise<{advice?: string, unavailable?: boolean, reason?: string, durationMs: number}>} deps.consult
+ * @param {(event: object) => void} deps.emit - Orchestrator-event emitter for the `advisor_consult` event.
+ * @param {{maxUses: number, used: number}} deps.budget - Session-wide budget shared by every caller's handler.
+ * @param {string} deps.model - Advisor model id, carried on the consult event.
+ */
+export function advisorTool({ from, consult, emit, budget, model }) {
+  return tool(
+    "Advisor",
+    ADVISOR_DESC,
+    { question: z.string() },
+    async ({ question }) => {
+      if (budget.used >= budget.maxUses) {
+        return textResult(
+          `Consult limit reached (${budget.maxUses}/${budget.maxUses} used) — proceed with your best judgment.`,
+        );
+      }
+      // Increment before the first await so two concurrent callers cannot
+      // both pass a last-slot check.
+      budget.used++;
+      const r = await consult(question);
+      const remaining = budget.maxUses - budget.used;
+      emit({
+        type: "advisor_consult",
+        caller: from,
+        question,
+        model,
+        durationMs: r.durationMs,
+        remaining,
+      });
+      if (r.unavailable) {
+        // Not isError: fail-open, the caller continues normally.
+        return textResult(
+          `The advisor is unavailable (${r.reason}) — proceed with your best judgment.`,
+        );
+      }
+      return textResult(
+        `${r.advice}\n\n[advisor consults remaining: ${remaining}]`,
+      );
+    },
+  );
+}
+
 const orchestrationServer = (tools) =>
   createSdkMcpServer({ name: "orchestration", tools });
 
@@ -354,15 +407,16 @@ export function createSupervisorToolServer(ctx) {
   ]);
 }
 
-/** Supervised agent tools: Ask + Answer + Announce + RollCall. */
-export function createSupervisedAgentToolServer(ctx) {
-  return orchestrationServer(
-    baseTools(ctx, {
+/** Supervised agent tools: Ask + Answer + Announce + RollCall (+ extras). */
+export function createSupervisedAgentToolServer(ctx, { extraTools = [] } = {}) {
+  return orchestrationServer([
+    ...baseTools(ctx, {
       from: "agent",
       defaultTo: "supervisor",
       broadcast: false,
     }),
-  );
+    ...extraTools,
+  ]);
 }
 
 /** Facilitator tools: Ask + Answer + Announce + RollCall + Conclude. */
@@ -377,11 +431,15 @@ export function createFacilitatorToolServer(ctx) {
   ]);
 }
 
-/** Facilitated agent tools: Ask + Answer + Announce + RollCall + RequestForComment. */
-export function createFacilitatedAgentToolServer(ctx, { from }) {
+/** Facilitated agent tools: Ask + Answer + Announce + RollCall + RequestForComment (+ extras). */
+export function createFacilitatedAgentToolServer(
+  ctx,
+  { from, extraTools = [] },
+) {
   return orchestrationServer([
     ...baseTools(ctx, { from, defaultTo: "facilitator", broadcast: true }),
     requestForCommentTool(ctx),
+    ...extraTools,
   ]);
 }