@yycholla/pi-dynamic-workflows 3.3.0

package/skills/workflow-patterns/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: workflow-patterns
+description: Argument shapes for the 5 built-in workflow patterns — deep-research, adversarial-review, code-review, multi-perspective, codebase-audit — runnable via the `workflow` tool's `name` input, without slash-command syntax. Use for requests like "research X", "fact-check/adversarially review this", "review this diff/PR", "analyze from multiple perspectives", or "audit the codebase for Y". Not for authoring a new workflow script — see workflow-authoring.
+metadata:
+  version: "3.3.0"
+---
+
+# Built-in workflow patterns
+
+pi-dynamic-workflows ships 5 curated, tested workflow patterns. Each is also a
+slash command (`/deep-research`, `/adversarial-review`, `/code-review`,
+`/multi-perspective`, `/codebase-audit`), but they are equally reachable from
+the `workflow` tool directly: call it with `name` set to the pattern name
+below and `args` matching its shape, instead of writing an equivalent script
+from scratch. Prefer this over authoring a new script whenever the request
+fits one of these shapes — the curated version is already reviewed and tested.
+
+A project or user saved workflow of the same name always takes precedence
+over a built-in of that name — on the slash command, too.
+
+These 5 names are reachable only at the `workflow` tool's top-level `name`
+input, not via the in-script `await workflow(savedName, childArgs)` helper —
+that helper resolves saved workflows only. Calling `workflow('deep-research')`
+from inside a script fails as an unknown saved workflow; use the top-level
+`name` input instead.
+
+## Patterns
+
+| `name` | When to reach for it | `args` |
+| --- | --- | --- |
+| `deep-research` | Research a question across the web with cross-checked sources | `{ question: string, angles?: number, minSupport?: number }` — `angles` (default 4) is the number of distinct search queries; `minSupport` (default 2) is the minimum distinct sources required for a claim to survive cross-checking |
+| `adversarial-review` | Investigate a task/claim, then cross-check each finding with skeptical reviewers | `{ task: string, reviewers?: number, threshold?: number }` |
+| `code-review` | Multi-angle review of a diff (correctness, reuse, simplification, efficiency, altitude) | `{ diff: string, diffSource?: string }` — get `diff` yourself first (e.g. `git diff`, `gh pr diff <n>`); this path does not fetch it for you |
+| `multi-perspective` | Analyze a topic from several independent perspectives in parallel, then synthesize | `{ topic: string, perspectives?: string[] }` — omit or give fewer than 2 to use the default set (technical, product, security, user experience, maintainability) |
+| `codebase-audit` | Run parallel checks against a codebase scope, then cross-validate and report | `{ scope: string, checks: string[] }` |
+
+## Example
+
+```json
+{ "name": "deep-research", "args": { "question": "What are the tradeoffs of X vs Y?" } }
+```
+
+This is a `workflow` tool call, not a script — omit `script` entirely. The run
+starts in the background exactly like the slash-command form; `background`,
+`maxAgents`, `concurrency`, `agentRetries`, `agentTimeoutMs`, and `tokenBudget`
+all still apply.
+
+## Writing a new workflow instead
+
+If the request doesn't fit one of these 5 shapes, author a script with
+`script` as usual — see the workflow-authoring skill.

package/src/accept-workflow-guidance.ts

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { WORKFLOW_AUTHORING_FROZEN_FILES } from "./workflow-authoring-coverage.js";
+
+const COVERAGE_MANIFEST_PATH = "src/workflow-authoring-coverage.ts";
+
+/** A reviewed frozen-guidance hash transition recorded in the coverage manifest. */
+export interface WorkflowGuidanceAcceptance {
+  path: string;
+  previousSha256: string;
+  sha256: string;
+  changed: boolean;
+}
+
+function sha256(source: string): string {
+  return createHash("sha256").update(source).digest("hex");
+}
+
+function manifestEntry(path: string, hash: string): string {
+  return `    path: ${JSON.stringify(path)},\n    sha256: ${JSON.stringify(hash)},`;
+}
+
+/**
+ * Accepts reviewed changes to explicitly named frozen workflow-authoring files.
+ *
+ * Throws before writing when no path is supplied, a path is not frozen, a file
+ * is missing, or the coverage manifest no longer contains the expected entry.
+ */
+export function acceptWorkflowGuidance(root: string, requestedPaths: readonly string[]): WorkflowGuidanceAcceptance[] {
+  if (requestedPaths.length === 0) {
+    throw new Error("Pass at least one frozen workflow-authoring path to accept.");
+  }
+
+  const frozenByPath: ReadonlyMap<string, (typeof WORKFLOW_AUTHORING_FROZEN_FILES)[number]> = new Map(
+    WORKFLOW_AUTHORING_FROZEN_FILES.map((entry) => [entry.path, entry]),
+  );
+  const paths = [...new Set(requestedPaths.map((path) => path.replace(/^\.\//, "")))];
+  const entries = paths.map((path) => {
+    const frozen = frozenByPath.get(path);
+    if (frozen === undefined) {
+      throw new Error(`${path} is not a frozen workflow-authoring guidance file.`);
+    }
+    const absolute = join(root, path);
+    if (!existsSync(absolute)) {
+      throw new Error(`Frozen workflow-authoring guidance file is missing: ${path}.`);
+    }
+    return {
+      path,
+      previousSha256: frozen.sha256,
+      sha256: sha256(readFileSync(absolute, "utf8")),
+    };
+  });
+
+  const manifestPath = join(root, COVERAGE_MANIFEST_PATH);
+  const originalManifest = readFileSync(manifestPath, "utf8");
+  let nextManifest = originalManifest;
+  for (const entry of entries) {
+    const previous = manifestEntry(entry.path, entry.previousSha256);
+    if (!nextManifest.includes(previous)) {
+      throw new Error(`Coverage manifest does not contain the expected frozen entry for ${entry.path}.`);
+    }
+    nextManifest = nextManifest.replace(previous, manifestEntry(entry.path, entry.sha256));
+  }
+
+  if (nextManifest !== originalManifest) {
+    writeFileSync(manifestPath, nextManifest);
+  }
+
+  return entries.map((entry) => ({ ...entry, changed: entry.previousSha256 !== entry.sha256 }));
+}

package/src/adversarial-review.ts

@@ -0,0 +1,120 @@
+/**
+ * Adversarial review mode for workflows.
+ * Agents cross-check each other's findings for higher quality results.
+ */
+
+export interface AdversarialReviewConfig {
+  /** Number of independent reviewers per finding. */
+  reviewerCount: number;
+  /** Whether to filter out findings that don't survive cross-checking. */
+  filterContested: boolean;
+  /** Minimum agreement threshold (0-1). */
+  agreementThreshold: number;
+}
+
+/**
+ * Generate an adversarial-review workflow. The script is static and reads its
+ * inputs from `args` (task/reviewers/threshold) — no string interpolation.
+ *
+ * Each finding is judged independently by N reviewers who are told to REFUTE it;
+ * a finding survives only when the share of reviewers calling it real meets the
+ * agreement threshold.
+ */
+export function generateAdversarialReviewWorkflow(): string {
+  return `export const meta = {
+  name: 'adversarial_review',
+  description: 'Adversarial review: findings cross-checked by independent skeptics',
+  phases: [
+    { title: 'Investigate' },
+    { title: 'Refute' },
+    { title: 'Consensus' },
+  ],
+}
+
+const task = (args && args.task) || ''
+const reviewers = (args && args.reviewers) || 2
+const threshold = (args && args.threshold) || 0.5
+
+phase('Investigate')
+const investigation = await agent(
+  'Investigate the following and list concrete, individually-checkable findings:\\n' + task,
+  { label: 'investigate', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }
+)
+const findings = investigation.findings || []
+
+phase('Refute')
+const judged = await parallel(findings.map((f, i) => () =>
+  parallel(Array.from({ length: reviewers }, (_, r) => () =>
+    agent(
+      'You are a skeptical reviewer. Try to REFUTE this finding for the task below. ' +
+      'Default to real=false when uncertain. Investigate with the available tools if needed.\\n\\n' +
+      'TASK: ' + task + '\\nFINDING: ' + f,
+      { label: 'refute ' + (i + 1) + '.' + (r + 1), schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } }
+    )
+  )).then((votes) => {
+    const valid = votes.filter(Boolean)
+    const realCount = valid.filter((v) => v && v.real).length
+    const ratio = valid.length ? realCount / valid.length : 0
+    return { finding: f, realVotes: realCount, totalVotes: valid.length, survives: ratio >= threshold }
+  })
+))
+
+const survivors = judged.filter((j) => j && j.survives)
+
+phase('Consensus')
+const report = await agent(
+  'Write a final review report. Include ONLY the findings that survived adversarial review (listed below), ' +
+  'each with a short justification. Note how many were discarded.\\n\\n' +
+  'SURVIVING FINDINGS JSON:\\n' + JSON.stringify(survivors),
+  { label: 'consensus' }
+)
+
+return { total: findings.length, survivors, report }`;
+}
+
+/**
+ * Generate a multi-perspective analysis workflow.
+ *
+ * `topic` and each `perspectives` entry are user-supplied strings baked
+ * directly into the generated script's source, so every one is embedded via
+ * JSON.stringify — a proper JS string literal that can't be broken out of by
+ * a quote, backslash, or backtick in the value.
+ */
+export function generateMultiPerspectiveWorkflow(topic: string, perspectives: string[]): string {
+  const perspectiveAgents = perspectives
+    .map((p, i) => {
+      const label =
+        p
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, "-")
+          .replace(/^-+|-+$/g, "")
+          .slice(0, 20) || `perspective-${i + 1}`;
+      return `  () => agent(${JSON.stringify(`Analyze from ${p} perspective: `)} + topic, { label: ${JSON.stringify(label)} }),`;
+    })
+    .join("\n");
+
+  return `export const meta = {
+  name: 'multi_perspective_analysis',
+  description: ${JSON.stringify(`Analyze from ${perspectives.length} different perspectives`)},
+  phases: [
+    { title: 'Perspective Analysis' },
+    { title: 'Synthesis' },
+  ],
+};
+
+phase('Perspective Analysis');
+const topic = ${JSON.stringify(topic)};
+const analyses = await parallel([
+${perspectiveAgents}
+]);
+
+phase('Synthesis');
+const synthesis = await agent(
+  'Synthesize these different perspectives into a balanced analysis:\\n' +
+  'Analyses: ' + JSON.stringify(analyses) + '\\n' +
+  'Topic: ' + topic,
+  { label: 'synthesizer' }
+);
+
+return { analyses, synthesis };`;
+}

package/src/agent-history.ts

@@ -0,0 +1,157 @@
+export type AgentHistoryRole = "user" | "assistant" | "tool";
+
+export type AgentHistoryKind = "text" | "toolCall" | "toolResult" | "error";
+
+export interface AgentHistoryEntry {
+  role: AgentHistoryRole;
+  kind: AgentHistoryKind;
+  text: string;
+  toolName?: string;
+  /** Source path for file-oriented tool calls rendered specially by the pager. */
+  path?: string;
+  /** Pi's display-oriented edit diff, preserved from EditToolDetails. */
+  diff?: string;
+  isError?: boolean;
+  timestamp?: number;
+}
+
+export interface AgentHistoryOptions {
+  maxEntries?: number;
+  maxTextChars?: number;
+  maxTotalChars?: number;
+}
+
+const DEFAULT_MAX_ENTRIES = 40;
+const DEFAULT_MAX_TEXT_CHARS = 2000;
+const DEFAULT_MAX_TOTAL_CHARS = 20000;
+
+export function compactAgentHistory(messages: unknown[], options: AgentHistoryOptions = {}): AgentHistoryEntry[] {
+  const maxEntries = positiveInt(options.maxEntries, DEFAULT_MAX_ENTRIES);
+  const maxTextChars = positiveInt(options.maxTextChars, DEFAULT_MAX_TEXT_CHARS);
+  const maxTotalChars = positiveInt(options.maxTotalChars, DEFAULT_MAX_TOTAL_CHARS);
+  const entries: AgentHistoryEntry[] = [];
+
+  for (const raw of messages) {
+    const message = asRecord(raw);
+    if (!message) continue;
+    const role = message.role;
+    const timestamp = typeof message.timestamp === "number" ? message.timestamp : undefined;
+
+    if (role === "user") {
+      const text = textFromContent(message.content);
+      if (text.trim()) entries.push({ role: "user", kind: "text", text, timestamp });
+      continue;
+    }
+
+    if (role === "assistant") {
+      for (const part of Array.isArray(message.content) ? message.content : []) {
+        const block = asRecord(part);
+        if (!block || typeof block.type !== "string") continue;
+        if (block.type === "text" && typeof block.text === "string" && block.text.trim()) {
+          entries.push({ role: "assistant", kind: "text", text: block.text, timestamp });
+        } else if (block.type === "toolCall" && typeof block.name === "string") {
+          const args = asRecord(block.arguments);
+          const filePath =
+            (block.name === "write" || block.name === "edit") && typeof args?.path === "string" ? args.path : undefined;
+          const writeContent =
+            block.name === "write" && filePath && typeof args?.content === "string" ? args.content : undefined;
+          entries.push({
+            role: "assistant",
+            kind: "toolCall",
+            toolName: block.name,
+            // A write's JSON envelope is both noisy and likely to be truncated
+            // into invalid JSON. Preserve its source directly so the pager can
+            // render it as code. Edit calls retain their path so the pager can
+            // pair the compact call header with the result's native Pi diff.
+            text: writeContent ?? stringifyCompact(block.arguments ?? {}),
+            path: filePath,
+            timestamp,
+          });
+        }
+      }
+      if (typeof message.errorMessage === "string" && message.errorMessage.trim()) {
+        entries.push({ role: "assistant", kind: "error", text: message.errorMessage, isError: true, timestamp });
+      }
+      continue;
+    }
+
+    if (role === "toolResult") {
+      const toolName = typeof message.toolName === "string" ? message.toolName : undefined;
+      const text = textFromContent(message.content) || "(no text output)";
+      const details = asRecord(message.details);
+      const diff = toolName === "edit" && typeof details?.diff === "string" ? details.diff : undefined;
+      entries.push({
+        role: "tool",
+        kind: message.isError ? "error" : "toolResult",
+        toolName,
+        text,
+        diff,
+        isError: Boolean(message.isError),
+        timestamp,
+      });
+    }
+  }
+
+  return fitEntries(entries, maxEntries, maxTextChars, maxTotalChars);
+}
+
+function fitEntries(
+  entries: AgentHistoryEntry[],
+  maxEntries: number,
+  maxTextChars: number,
+  maxTotalChars: number,
+): AgentHistoryEntry[] {
+  const fitted: AgentHistoryEntry[] = [];
+  let total = 0;
+
+  for (const entry of entries.slice(-maxEntries).reverse()) {
+    const remaining = maxTotalChars - total;
+    if (remaining <= 0) break;
+
+    // Treat an edit diff as the entry's primary display payload. Keeping it
+    // within the same per-entry and total bounds prevents EditToolDetails from
+    // bypassing history compaction with a large changed file.
+    let entryBudget = Math.min(maxTextChars, remaining);
+    const diff = entry.diff ? truncateText(entry.diff, entryBudget) : undefined;
+    entryBudget -= diff?.length ?? 0;
+    const text = truncateText(entry.text, entryBudget);
+    fitted.unshift({ ...entry, text, diff });
+    total += text.length + (diff?.length ?? 0);
+  }
+
+  return fitted;
+}
+
+function textFromContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      const block = asRecord(part);
+      return block?.type === "text" && typeof block.text === "string" ? block.text : "";
+    })
+    .filter(Boolean)
+    .join("");
+}
+
+function stringifyCompact(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function truncateText(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  if (maxChars <= 20) return text.slice(0, maxChars);
+  return `${text.slice(0, maxChars - 20)}... [truncated]`;
+}
+
+function positiveInt(value: number | undefined, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
+}

package/src/agent-registry.ts

@@ -0,0 +1,221 @@
+/**
+ * Named workflow subagent definitions ("agentType" registry).
+ *
+ * A workflow script can route an agent() call to a reusable, named definition:
+ *
+ *   agent("audit this dir", { agentType: "security-auditor" })
+ *
+ * Definitions live as Markdown files under `.pi/agents/*.md` (project, cwd-relative)
+ * and `~/.pi/agent/agents/*.md` (user — `getAgentDir() + "agents"`, honoring the
+ * `PI_CODING_AGENT_DIR` override), matching pi-coding-agent's own built-in agent
+ * discovery convention. The legacy `~/.pi/agents/*.md` location is still scanned as
+ * a deprecated fallback (with a one-time warning) so users who followed this repo's
+ * earlier docs are not silently broken; the new location wins on a name collision.
+ * Frontmatter binds the subagent's tools, model, and a body prompt; project
+ * definitions win over both user-level locations on a name collision. This mirrors
+ * Claude Code's `.claude/agents` registry: agentType is a real binding of
+ * tools+model+system-prompt, not a prose hint.
+ *
+ * Bound today: `tools` (allowlist), `disallowedTools` (denylist), `model`,
+ * and the markdown body (`prompt`). Parsed-but-ignored for now (documented): `mcp`, `skills`, `background`.
+ * Wired: `isolation` ("worktree") → createWorktree() in workflow.ts.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { AGENTS_DIR } from "./config.js";
+
+export interface AgentDefinition {
+  /** Stable identity used as the `agentType` value. */
+  name: string;
+  /** One-line summary (for discoverability in the tool guideline). */
+  description?: string;
+  /** Allowlist of coding-tool names the subagent may use. Undefined = all. */
+  tools?: string[];
+  /** Denylist of coding-tool names, applied after the allowlist. */
+  disallowedTools?: string[];
+  /** Model spec (`provider/modelId` or bare id) for this subagent. */
+  model?: string;
+  /** Isolation mode. When "worktree", agents using this type run in a git worktree. */
+  isolation?: "worktree";
+  /** Markdown body, prepended to the subagent's task as role guidance. */
+  prompt: string;
+  /** Where the definition was loaded from (project wins over user). */
+  source: "project" | "user";
+}
+
+export type AgentRegistry = Map<string, AgentDefinition>;
+
+function toStringArray(value: unknown): string[] | undefined {
+  if (value == null) return undefined;
+  // YAML list form: ["read", "grep"]
+  if (Array.isArray(value)) {
+    const arr = value.filter((v): v is string => typeof v === "string" && v.trim().length > 0).map((v) => v.trim());
+    return arr.length ? arr : undefined;
+  }
+  // Comma-separated string form: "read, grep, find" — the form pi-coding-agent's
+  // parseFrontmatter returns and the form the official subagent example uses.
+  if (typeof value === "string" && value.trim().length > 0) {
+    const arr = value
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return arr.length ? arr : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Parse one agent-definition markdown file. Returns null only when there is no
+ * usable content (no name derivable and an empty body).
+ */
+export function parseAgentDefinition(
+  content: string,
+  source: "project" | "user",
+  fileName: string,
+): AgentDefinition | null {
+  let parsed: { frontmatter: Record<string, unknown>; body: string };
+  try {
+    parsed = parseFrontmatter(content);
+  } catch {
+    // Malformed frontmatter: treat the whole file as a body, name from filename.
+    parsed = { frontmatter: {}, body: content };
+  }
+  const fm = parsed.frontmatter;
+  const fmName = typeof fm.name === "string" ? fm.name.trim() : "";
+  const name = fmName || basename(fileName).replace(/\.md$/i, "").trim();
+  const prompt = parsed.body.trim();
+  if (!name && !prompt) return null;
+
+  return {
+    name,
+    description: typeof fm.description === "string" ? fm.description.trim() || undefined : undefined,
+    tools: toStringArray(fm.tools),
+    disallowedTools: toStringArray(fm.disallowedTools),
+    model: typeof fm.model === "string" ? fm.model.trim() || undefined : undefined,
+    isolation:
+      typeof fm.isolation === "string" && fm.isolation.toLowerCase().trim() === "worktree" ? "worktree" : undefined,
+    prompt,
+    source,
+  };
+}
+
+function readDefsFromDir(dir: string, source: "project" | "user"): AgentDefinition[] {
+  if (!existsSync(dir)) return [];
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.toLowerCase().endsWith(".md"));
+  } catch {
+    return [];
+  }
+  const defs: AgentDefinition[] = [];
+  for (const file of files.sort()) {
+    try {
+      const def = parseAgentDefinition(readFileSync(join(dir, file), "utf-8"), source, file);
+      if (def) defs.push(def);
+    } catch {
+      // Skip unreadable/invalid files; never let one bad file break the registry.
+    }
+  }
+  return defs;
+}
+
+/**
+ * Load the agent registry once for a run. Scans the project dir, then the
+ * user dir, then — as a deprecated fallback — the legacy user dir; the FIRST
+ * definition for a name wins (project > user > legacy user, then filename
+ * order), so a name collision is resolved deterministically and silently.
+ *
+ * When a definition is only found at the legacy location (not shadowed by
+ * the new user dir), a single deprecation warning is logged for this call
+ * telling the user to move their files — not one warning per legacy file.
+ *
+ * `opts` overrides the scanned directories (used by tests).
+ */
+export function loadAgentRegistry(
+  cwd: string,
+  opts?: { projectDir?: string; userDir?: string; legacyUserDir?: string },
+): AgentRegistry {
+  const projectDir = opts?.projectDir ?? join(cwd, AGENTS_DIR);
+  // User-level definitions live under the agent dir (e.g. ~/.pi/agent/agents/),
+  // matching the convention used by pi-coding-agent's built-in agent discovery
+  // and the official subagent extension example. Reading getAgentDir() also
+  // honors the PI_CODING_AGENT_DIR env override.
+  const userDir = opts?.userDir ?? join(getAgentDir(), "agents");
+  // Deprecated: this repo's docs used to point users at ~/.pi/agents/ before
+  // pi-coding-agent's convention (~/.pi/agent/agents/) was known. Keep scanning
+  // it as a fallback so those files don't silently stop resolving.
+  const legacyUserDir = opts?.legacyUserDir ?? join(homedir(), AGENTS_DIR);
+
+  const registry: AgentRegistry = new Map();
+  for (const def of readDefsFromDir(projectDir, "project")) {
+    if (def.name && !registry.has(def.name)) registry.set(def.name, def);
+  }
+  if (userDir !== projectDir) {
+    for (const def of readDefsFromDir(userDir, "user")) {
+      if (def.name && !registry.has(def.name)) registry.set(def.name, def);
+    }
+  }
+  if (legacyUserDir !== projectDir && legacyUserDir !== userDir) {
+    let warnedLegacy = false;
+    for (const def of readDefsFromDir(legacyUserDir, "user")) {
+      if (def.name && !registry.has(def.name)) {
+        registry.set(def.name, def);
+        if (!warnedLegacy) {
+          console.warn(
+            `[agent-registry] Loaded agent definition(s) from the deprecated location "${legacyUserDir}". ` +
+              `Move them to "${userDir}" — the old location may stop being read in a future release.`,
+          );
+          warnedLegacy = true;
+        }
+      }
+    }
+  }
+  return registry;
+}
+
+/** Resolve an agentType name to its definition, or undefined if not registered. */
+export function resolveAgentType(name: string | undefined, registry: AgentRegistry): AgentDefinition | undefined {
+  if (!name) return undefined;
+  return registry.get(name);
+}
+
+/**
+ * Apply a definition's tool policy to a tool list: keep only allowlisted names
+ * (when an allowlist is given), then drop any denylisted names. Generic over any
+ * object with a `name` so it is unit-testable without real ToolDefinitions.
+ */
+export function applyToolPolicy<T extends { name: string }>(tools: T[], allow?: string[], deny?: string[]): T[] {
+  let out = tools;
+  if (allow?.length) {
+    const allowSet = new Set(allow);
+    out = out.filter((t) => allowSet.has(t.name));
+  }
+  if (deny?.length) {
+    const denySet = new Set(deny);
+    out = out.filter((t) => !denySet.has(t.name));
+  }
+  return out;
+}
+
+/**
+ * A stable identity string for a resolved definition, folded into the resume
+ * call-hash so editing an agent `.md` invalidates that call's cached result.
+ */
+export function agentDefinitionKey(def: AgentDefinition | undefined): string | null {
+  if (!def) return null;
+  return JSON.stringify({
+    tools: def.tools ?? null,
+    disallowedTools: def.disallowedTools ?? null,
+    model: def.model ?? null,
+    isolation: def.isolation ?? null,
+    prompt: def.prompt,
+  });
+}
+
+/** List registered agent types for discoverability in the tool guideline. */
+export function listAgentTypes(registry: AgentRegistry): Array<{ name: string; description?: string }> {
+  return [...registry.values()].map((d) => ({ name: d.name, description: d.description }));
+}