surgent 0.7.0-alpha.0

package/src/agent/built-in/planner.md

@@ -0,0 +1,73 @@
+---
+description: Repository-grounded planner for work spanning multiple components or unclear sequencing and risks; use before complex implementation, not small obvious fixes
+---
+
+<role>
+You are planning agent. Turn user request into small, execution-ready plan for coding agent.
+</role>
+
+<mission>
+Produce plan grounded in current repository. Reduce handoff uncertainty without expanding scope.
+</mission>
+
+<rules>
+- Plan only. Never edit files, write artifacts, or propose code patches.
+- Treat latest user request as scope contract. Preserve explicit constraints and exclusions.
+- Inspect repository before conclusions. Never claim behavior from unopened code.
+- Prefer existing patterns, helpers, types, commands, and test setup. Do not invent architecture for hypothetical needs.
+- Ask one focused questionnaire question only when missing answer changes implementation, safety, or scope. State assumption when reasonable answer does not change plan materially.
+- Do not add cleanup, refactors, documentation, dependencies, or tests outside requested work unless correctness requires them.
+</rules>
+
+<evidence_workflow>
+1. Extract outcome, constraints, non-scope, and acceptance criteria from request.
+2. Locate likely entry points with narrow searches. Read affected code, related types, and side-effect boundaries.
+3. Identify established implementation and validation patterns. Trace callers only when needed to prove behavior.
+4. Form smallest viable design. Record files to change, dependency order, failure cases, and validation.
+5. Before final answer, remove speculative steps and verify every proposed target has evidence.
+</evidence_workflow>
+
+<planning_rules>
+- Name concrete file paths, symbols, and behavior changes.
+- Separate required work from optional follow-up. Omit optional follow-up unless user asked for it.
+- Prefer one shared root-cause change over repeated caller fixes.
+- Include validation that can fail when changed behavior regresses.
+- Flag migrations, data loss, security impact, and incompatible behavior before proposing execution.
+- For ambiguous repository behavior, say what was inspected, what remains unknown, and exact question needed.
+</planning_rules>
+
+<output_contract>
+Return Markdown with using this exact template:
+
+```markdown
+# Plan: [title]
+
+## Objective
+One paragraph covering outcome and reason.
+
+## Out of scope
+- Only explicit exclusions or tightly related non-goals.
+
+## Assumptions
+- Only assumptions that affect correctness.
+Omit when none.
+
+## Steps
+Use 3-10 ordered, atomic steps. Each step contains:
+- Goal
+- Changes
+- Targets: exact paths and symbols when known
+- Validation: command, test, or observable behavior
+- Done when
+
+## Risks & Mitigations
+- Include only real risks supported by request or repository evidence.
+
+## Handoff Packet
+- Hard constraints
+- Acceptance criteria
+
+## Open Questions
+- Only non-blocking questions. Omit when none.
+```
+</output_contract>

package/src/agent/built-in/scout.md

@@ -0,0 +1,97 @@
+---
+description: Read-only codebase researcher for broad or uncertain questions; returns bounded, evidence-backed synthesis at quick, standard, or deep depth and should not handle one known target
+---
+
+<role>
+Code research agent. Answer assigned question from repository evidence without exposing raw exploration to parent context.
+</role>
+
+<depth>
+Read `Depth: quick|standard|deep` from task. Use `standard` when omitted.
+
+- `quick`: Follow one primary path. Inspect only decisive symbols. Target at most 250 words and 5 evidence references. Report ambiguity instead of widening scope.
+- `standard`: Trace primary execution path, immediate callers and callees, relevant types, configuration, and tests. Target at most 700 words and 12 evidence references.
+- `deep`: Trace subsystem boundaries, alternate paths, shared abstractions, invariants, side effects, and verification surface. Target at most 1,400 words and 20 evidence references. Stop when assigned question is answered, not when repository is exhausted.
+
+Depth controls research breadth, not only answer length. Never silently escalate depth.
+</depth>
+
+<research>
+1. Start from concrete paths, symbols, snippets, errors, or commands in request.
+2. Use `ls`, `find`, and `grep` to discover relevant locations and terms.
+3. Use `code_map` to map narrow code areas and identify symbols, dependencies, and public boundaries.
+4. Use `inspect` for full symbol bodies needed to answer question.
+5. Use `read` only for relevant non-code files or code regions `inspect` cannot expose. For code, derive offset and limit from latest `code_map` result.
+6. Follow relationships only to depth required by selected level.
+7. Separate confirmed behavior from inference. Preserve unresolved gaps when they affect confidence.
+8. Synthesize findings. Never return tool calls, raw tool output, or selector JSON.
+</research>
+
+<output_contract>
+Return Markdown with exact template for matching selected depth. Replace bracketed guidance; never output brackets.
+
+`quick` template:
+
+```markdown
+## Answer
+[Direct answer and confidence.]
+
+## Evidence
+- `path:line` — `symbol`: [Finding and significance.]
+
+## Gaps
+[Material uncertainty or `None.`]
+```
+
+`standard` template:
+
+```markdown
+## Answer
+[Evidence-backed synthesis.]
+
+## Execution flow
+[Primary flow through relevant symbols.]
+
+## Relevant locations
+- `path:line` — `symbol`: [Role in behavior.]
+
+## Evidence
+- `path:line` — `symbol`: [Finding and significance.]
+
+## Gaps
+[Material uncertainty or `None.`]
+```
+
+`deep` template:
+
+```markdown
+## Answer
+[Detailed synthesis and confidence.]
+
+## Execution flow
+[Primary and alternate flows across boundaries.]
+
+## Relevant locations
+- `path:line` — `symbol`: [Role in subsystem.]
+
+## Change impact
+[Callers, invariants, side effects, and compatibility concerns.]
+
+## Verification
+[Existing checks and smallest checks needed to prove behavior.]
+
+## Evidence
+- `path:line` — `symbol`: [Finding and significance.]
+
+## Gaps
+[Material uncertainty or `None.`]
+```
+
+Rules:
+- Give every important claim a file path plus symbol or line range.
+- Format each evidence item as `- \`path:line\` — \`symbol\`: finding`. Use path plus symbol when line is unavailable.
+- Explain significance instead of repeating file contents.
+- Include no raw code except 1–3 decisive lines when required.
+- Write `None.` under `## Gaps` when no material gap remains.
+- Do not propose implementation unless task asks for change analysis.
+</output_contract>

package/src/agent/command.ts

@@ -0,0 +1,140 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Agent, AgentMeta } from "./types.js";
+import {
+  createAgentFile,
+  DEFAULT_AGENT,
+  deleteAgentFiles,
+  isBuiltIn,
+  loadAgents,
+  writeAgentMeta,
+} from "./storage.js";
+import { ExtendedSelectList } from "../ui/components/extended-select-list.js";
+import { ScopedInput } from "../ui/components/scoped-input.js";
+import { Form } from "../ui/components/form.js";
+import { getAgentConfigForm } from "./helpers.js";
+import { openInEditor } from "../utils.js";
+
+async function showAgentPicker(
+  ctx: ExtensionCommandContext,
+  agents: Agent[],
+): Promise<string | null> {
+  const items = agents
+    .filter((agent) => agent.name !== DEFAULT_AGENT)
+    .map((agent) => ({
+      value: agent.name,
+      label: isBuiltIn(agent.filePath) ? `${agent.name} (built-in)` : agent.name,
+      description: agent.meta.description,
+      data: agent,
+    }));
+
+  return ctx.ui.custom<string | null>((_tui, theme, _keybindings, done) => {
+    const selectList = new ExtendedSelectList(theme, {
+      title: "Agents",
+      addLabel: "Create new agent",
+      items,
+      maxVisibleRows: 12,
+      canDelete: (item) => item.data !== undefined && !isBuiltIn(item.data.filePath),
+    });
+
+    selectList.onAdd = () => done("__new__");
+    selectList.onSelect = (item) => done(String(item.value));
+    selectList.onCancel = () => done(null);
+    selectList.onDeleteBlocked = () => ctx.ui.notify("Built-in agent cannot be deleted", "error");
+    selectList.onDelete = (item) => {
+      const agentName = item.data?.name ?? String(item.value);
+      void deleteAgentFiles(agentName, ctx.cwd)
+        .then(() => ctx.ui.notify(`Agent "${agentName}" deleted`, "info"))
+        .catch(() => ctx.ui.notify(`Failed to delete agent "${agentName}"`, "error"));
+    };
+
+    return selectList;
+  });
+}
+
+async function openAgentConfigEditor(ctx: ExtensionCommandContext, agent: Agent) {
+  await ctx.ui.custom<void>((tui, theme, keybindings, done) => {
+    const editor = new Form<AgentMeta>(
+      tui,
+      keybindings,
+      theme,
+      getAgentConfigForm(agent.name, agent.meta, isBuiltIn(agent.filePath)),
+    );
+
+    editor.onCancel = () => done();
+    editor.onSave = async (updatedMeta) => {
+      await writeAgentMeta(agent, updatedMeta);
+      agent.meta = updatedMeta;
+      ctx.ui.notify(`Agent "${agent.name}" config updated`, "info");
+      done();
+    };
+    editor.onSaveError = (error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Failed to update agent config: ${message}`, "error");
+    };
+
+    return editor;
+  });
+}
+
+async function handleExistingAgent(ctx: ExtensionCommandContext, agent: Agent) {
+  while (true) {
+    const options = ["Start in new session", "Edit agent config"];
+    if (!isBuiltIn(agent.filePath)) {
+      options.push("Open in external editor");
+    }
+
+    const action = await ctx.ui.select(`Agent: ${agent.name}`, options);
+    if (!action) return false;
+
+    if (action === "Start in new session") {
+      const result = await ctx.newSession({
+        setup: async (sessionManager) => {
+          sessionManager.appendCustomEntry("agent", agent.name);
+        },
+      });
+      return !result.cancelled;
+    }
+    if (action === "Edit agent config") {
+      await openAgentConfigEditor(ctx, agent);
+      continue;
+    }
+    if (action === "Open in external editor") {
+      await openInEditor(ctx, agent.filePath);
+      return false;
+    }
+  }
+}
+
+async function handleNewAgent(ctx: ExtensionCommandContext) {
+  const result = await ctx.ui.custom<{ name: string; scope: string } | null>(
+    (_tui, theme, _kb, done) => {
+      const scopedInput = new ScopedInput(theme, "Agent name");
+      scopedInput.onSubmit = ({ scope, value: name }) => done({ name, scope });
+      scopedInput.onCancel = () => done(null);
+      return scopedInput;
+    },
+  );
+
+  if (!result) return;
+  const { name, scope } = result;
+  const filePath = await createAgentFile(scope === "project" ? ctx.cwd : scope, name);
+
+  ctx.ui.notify(`Agent created: ${filePath}`, "info");
+  await openInEditor(ctx, filePath);
+}
+
+export async function agentsCommandHandler(ctx: ExtensionCommandContext) {
+  while (true) {
+    const agents = await loadAgents(ctx.cwd);
+    const selected = await showAgentPicker(ctx, agents);
+    if (!selected) return;
+
+    if (selected === "__new__") {
+      await handleNewAgent(ctx);
+      return;
+    }
+
+    const agent = agents.find((candidate) => candidate.name === selected);
+    if (agent && (await handleExistingAgent(ctx, agent))) return;
+  }
+}

package/src/agent/helpers.ts

@@ -0,0 +1,95 @@
+import type { AgentMeta } from "./types.js";
+import type { FormConfig } from "../ui/components/form.js";
+import { META_KEYS } from "./storage.js";
+
+function parseConfigValues(values: Record<string, string>) {
+  const description = (values.description ?? "").trim();
+  if (!description) {
+    throw new Error("Description cannot be empty.");
+  }
+
+  const updated: AgentMeta = { description };
+  for (const field of META_KEYS) {
+    if (field === "description") continue;
+
+    const rawValue = values[field] ?? "";
+    if (field === "model") {
+      const modelValue = rawValue.trim();
+      if (modelValue) {
+        updated.model = modelValue;
+      }
+      continue;
+    }
+    if (field === "thinking_level") {
+      const thinkingLevel = rawValue.trim();
+      if (
+        thinkingLevel &&
+        !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(thinkingLevel)
+      ) {
+        throw new Error("Thinking level must be off, minimal, low, medium, high, xhigh, or max.");
+      }
+      if (thinkingLevel) {
+        updated.thinking_level = thinkingLevel as AgentMeta["thinking_level"];
+      }
+      continue;
+    }
+
+    const normalizedValue = rawValue.trim();
+    if (!normalizedValue) continue;
+
+    const entries =
+      normalizedValue === "[]"
+        ? []
+        : normalizedValue
+            .split(",")
+            .map((entry) => entry.trim().replace(/^['\"]|['\"]$/g, ""))
+            .filter(Boolean);
+    if (entries.length === 0 && normalizedValue !== "[]") continue;
+
+    updated[field] = entries;
+  }
+
+  return updated;
+}
+
+export function getAgentConfigForm(
+  agent: string,
+  meta: AgentMeta,
+  builtIn: boolean,
+): FormConfig<AgentMeta> {
+  return {
+    title: `Edit agent config: ${agent}`,
+    fields: META_KEYS.filter((field) => !builtIn || field !== "description").map((field) => {
+      const value = meta[field];
+      let placeholder: string;
+      if (field === "description") {
+        placeholder = "Describe what this agent does (not included in system prompt)";
+      } else if (field === "model") {
+        placeholder = "AI model to use for this agent (leave blank to inherit)";
+      } else if (field === "thinking_level") {
+        placeholder = "off, minimal, low, medium, high, xhigh, or max (leave blank to inherit)";
+      } else {
+        placeholder = `comma-separated allowed ${field}`;
+      }
+
+      return {
+        key: field,
+        label: field,
+        labelWidth: 32,
+        mode: {
+          type: "input",
+          placeholder,
+          text: Array.isArray(value)
+            ? value.length === 0
+              ? "[]"
+              : value.join(", ")
+            : (value ?? ""),
+        },
+      };
+    }),
+    emptyMessage: "No metadata fields available for editing.",
+    parseOnSave: builtIn
+      ? (values) => parseConfigValues({ description: meta.description, ...values })
+      : parseConfigValues,
+  };
+}

package/src/agent/index.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { agentsCommandHandler } from "./command.js";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("agent", {
+    description: "List, create, edit, and switch agents",
+    handler: (_args, ctx) => agentsCommandHandler(ctx),
+  });
+}

package/src/agent/storage.ts

@@ -0,0 +1,287 @@
+import { readdir, unlink, readFile, writeFile } from "node:fs/promises";
+import path, { dirname, join, resolve } from "node:path";
+import { isMissingFileError, readJson, writeJson } from "../utils.js";
+import { fileURLToPath } from "node:url";
+import { getPiPath } from "../utils.js";
+import type { AgentMeta, Agent, SettingsSchema } from "./types.js";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadMcpConfigSet } from "../mcp-client/storage.js";
+
+export const DEFAULT_AGENT = "general";
+export const META_KEYS: (keyof AgentMeta)[] = [
+  "description",
+  "tools",
+  "mcp_tools",
+  "skills",
+  "bash",
+  "files.read",
+  "files.write",
+  "model",
+  "thinking_level",
+];
+
+const FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const LINE_ENDING = /\r?\n/;
+const KEY_VALUE_PAIR = /^([\w.]+):\s*(.*)$/;
+const INLINE_ARRAY = /^\[(.*)\]$/;
+const QUOTED_STRING = /^["']|["']$/g;
+
+const ARRAY_KEYS = new Set<keyof AgentMeta>([
+  "tools",
+  "mcp_tools",
+  "skills",
+  "bash",
+  "files.read",
+  "files.write",
+]);
+const STRING_KEYS = new Set<keyof AgentMeta>(["description", "model", "thinking_level"]);
+const META_KEY_SET = new Set<string>(META_KEYS);
+const BUILT_IN_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "built-in");
+
+function parseAllowList(value: string): string[] | undefined {
+  const inlineArray = value.match(INLINE_ARRAY);
+  if (inlineArray) {
+    return inlineArray[1]!
+      .split(",")
+      .map((part) => part.trim().replace(QUOTED_STRING, ""))
+      .filter(Boolean);
+  }
+}
+
+function parseAgentConfig(content: string, filePath: string): Agent | null {
+  const match = content.match(FRONTMATTER_BLOCK);
+  if (!match) return null;
+
+  const frontmatter = match[1]!;
+  const body = match[2]!.trim();
+  const name = path.basename(filePath, path.extname(filePath));
+  const meta: Partial<AgentMeta> = {};
+
+  for (const line of frontmatter.split(LINE_ENDING)) {
+    const kv = line.match(KEY_VALUE_PAIR);
+    if (!kv) continue;
+    const key = kv[1]!;
+    const value = kv[2]!.trim();
+
+    if (ARRAY_KEYS.has(key as keyof AgentMeta)) {
+      const parsedAllowList = parseAllowList(value);
+      if (parsedAllowList !== undefined) {
+        (meta as Record<string, string[]>)[key] = parsedAllowList;
+      }
+    } else if (STRING_KEYS.has(key as keyof AgentMeta)) {
+      (meta as Record<string, string>)[key] = value.replace(QUOTED_STRING, "");
+    }
+  }
+
+  if (!meta.description) return null;
+  return { meta: meta as AgentMeta, body, filePath, name };
+}
+
+async function getAgentFiles(cwd: string, name?: string, skipBuiltIn?: boolean): Promise<string[]> {
+  const seen = new Set<string>();
+  const dirs = [getPiPath("agents", cwd), getPiPath("agents")];
+  const files: string[] = [];
+  if (!skipBuiltIn) dirs.push(BUILT_IN_DIR);
+
+  for (const dir of dirs) {
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      files.push(
+        ...entries
+          .filter((entry) => {
+            if (seen.has(entry.name)) return false;
+            seen.add(entry.name);
+            return (
+              entry.isFile() && entry.name.endsWith(".md") && (!name || entry.name === `${name}.md`)
+            );
+          })
+          .map((entry) => join(dir, entry.name)),
+      );
+    } catch {
+      continue;
+    }
+  }
+
+  return files;
+}
+
+async function appendToolDetails(activeTools: string[], lines: Record<string, string>) {
+  const appendContent: string[] = [];
+  if (
+    (activeTools.includes("call_mcp_tool") || activeTools.includes("list_mcp_tools")) &&
+    lines.mcp
+  ) {
+    appendContent.push(lines.mcp);
+  }
+  if (activeTools.includes("subagent") && lines.subagent) {
+    appendContent.push(lines.subagent);
+  }
+  if (appendContent.length > 0) {
+    await writeFile(getPiPath("system"), `${appendContent.join("\n")}\n`, "utf8");
+  }
+}
+
+export async function loadAgents(cwd: string, name?: string): Promise<[Agent, ...Agent[]]> {
+  const agents: Agent[] = [];
+  const files = await getAgentFiles(cwd, name);
+  const settings = await readJson<SettingsSchema>(getPiPath("settings"), {});
+
+  for (const file of files) {
+    try {
+      const content = await readFile(file, "utf8");
+      const parsed = parseAgentConfig(content, file);
+      if (!parsed || (!isBuiltIn(file) && parsed.name === DEFAULT_AGENT)) continue;
+      if (isBuiltIn(file)) {
+        parsed.meta = { ...parsed.meta, ...settings.agent?.meta?.[parsed.name] };
+      }
+      agents.push(parsed);
+    } catch {} // skip unreadable files
+  }
+
+  if (agents.length === 0) {
+    throw new Error("Invalid agent name or files unreachable. Please try again.");
+  }
+
+  return agents as [Agent, ...Agent[]];
+}
+
+function serializeMeta(meta: AgentMeta): string[] {
+  const lines: string[] = [];
+
+  for (const key of META_KEYS) {
+    const value = meta[key];
+    if (value === undefined) continue;
+
+    if (Array.isArray(value)) {
+      lines.push(`${key}: [${value.map((entry) => JSON.stringify(entry)).join(", ")}]`);
+      continue;
+    }
+
+    lines.push(`${key}: ${String(value)}`);
+  }
+
+  return lines;
+}
+
+export async function createAgentFile(base: string, name: string): Promise<string> {
+  const filePath = join(getPiPath("agents", base), `${name}.md`);
+  await writeFile(
+    filePath,
+    `---\ndescription: Describe what \`${name}\` agent does\n---\n\nWrite \`${name}\` agent's system prompt here`,
+    "utf8",
+  );
+  return filePath;
+}
+
+export async function writeAgentMeta(agent: Agent, meta: AgentMeta) {
+  if (isBuiltIn(agent.filePath)) {
+    const settingsPath = getPiPath("settings");
+    let settings: SettingsSchema;
+
+    try {
+      settings = JSON.parse(await readFile(settingsPath, "utf8")) as SettingsSchema;
+    } catch (error) {
+      if (!isMissingFileError(error)) throw error;
+      settings = {};
+    }
+
+    const { description, ...stored } = meta;
+    settings.agent = {
+      ...settings.agent,
+      meta: { ...settings.agent?.meta, [agent.name]: stored },
+    };
+    await writeJson(settingsPath, settings);
+    return;
+  }
+
+  const content = await readFile(agent.filePath, "utf8");
+  const match = content.match(FRONTMATTER_BLOCK);
+  if (!match) {
+    throw new Error(`Invalid agent file frontmatter: ${agent.filePath}`);
+  }
+
+  const existingFrontmatter = match[1] ?? "";
+  const preservedFrontmatterLines = existingFrontmatter
+    .split(LINE_ENDING)
+    .map((line) => line.trimEnd())
+    .filter((line) => {
+      const pair = line.match(KEY_VALUE_PAIR);
+      if (!pair) {
+        return line.trim().length > 0;
+      }
+      return !META_KEY_SET.has(pair[1]!);
+    });
+
+  const body = match[2] ?? "";
+  const metaLines = serializeMeta(meta);
+  const nextFrontmatterLines = [...preservedFrontmatterLines, ...metaLines];
+
+  const nextContent = `---\n${nextFrontmatterLines.join("\n")}\n---\n${body}`;
+  await writeFile(agent.filePath, nextContent, "utf8");
+}
+
+export async function deleteAgentFiles(name: string, cwd: string) {
+  const files = await getAgentFiles(cwd, name, true);
+  for (const file of files) {
+    try {
+      const content = await readFile(file, "utf8");
+      const parsed = parseAgentConfig(content, file);
+      if (parsed?.name === name) await unlink(file);
+    } catch {} // skip
+  }
+}
+
+export function isBuiltIn(filePath: string): boolean {
+  return filePath.startsWith(BUILT_IN_DIR);
+}
+
+export async function loadMainAgent(pi: ExtensionAPI, ctx: ExtensionContext) {
+  const selected = ctx.sessionManager
+    .getEntries()
+    .find((entry) => entry.type === "custom" && entry.customType === "agent");
+  const name = selected?.type === "custom" ? (selected.data as string) : DEFAULT_AGENT;
+
+  const allMcpConfigs = await loadMcpConfigSet(ctx.cwd);
+  const agents = await loadAgents(ctx.cwd);
+  const main = agents.find((agent) => agent.name === name);
+  if (!main) {
+    throw new Error("Invalid agent name.");
+  }
+
+  const { meta } = main;
+  const mcpConfigs = allMcpConfigs.filter(
+    (cfg) => cfg.enabled === true && (meta.mcp_tools ?? [cfg.name]).includes(cfg.name),
+  );
+
+  pi.setActiveTools(
+    pi
+      .getAllTools()
+      .map((tool) => tool.name)
+      .filter((name) => (meta.tools ?? [name]).includes(name)),
+  );
+
+  if (meta.model) {
+    const existing = ctx.modelRegistry.find(
+      meta.model.slice(0, meta.model.indexOf("/")),
+      meta.model.slice(meta.model.indexOf("/") + 1),
+    );
+
+    if (existing) {
+      const ok = await pi.setModel(existing);
+      if (!ok) ctx.ui.notify("Agent model unavailable", "warning");
+    } else {
+      ctx.ui.notify(`Unknown model "${meta.model}" in agent config`, "warning");
+    }
+  }
+  if (meta.thinking_level) {
+    pi.setThinkingLevel(meta.thinking_level);
+  }
+
+  await appendToolDetails(pi.getActiveTools(), {
+    mcp: `## Available MCP servers\n${mcpConfigs
+      .map((cfg) => (cfg.description ? `- ${cfg.name}: ${cfg.description}` : `- ${cfg.name}`))
+      .join("\n")}`,
+    subagent: `## Available agents for \`subagent\` tool\n${agents.map((profile) => `- ${profile.name}: ${profile.meta.description}`).join("\n")}`,
+  });
+  return main;
+}