@forwardimpact/libeval 0.1.48 → 0.1.50

package/README.md

@@ -176,11 +176,9 @@ downloadable through retention.
 ## fit-selfedit
 
 A narrow, audited bypass for sessions where `Edit`/`Write` (and bash
-writes) are blocked against paths the project's own allowlist permits —
-see [#1162](https://github.com/forwardimpact/monorepo/issues/1162) and
-[#441](https://github.com/forwardimpact/monorepo/issues/441) for the
-original episodes. Reads stdin, writes the target, exits 0 / 2
-(safeguard violation) / 1 (I/O error).
+writes) are blocked against paths the project's own allowlist permits.
+Reads stdin, writes the target, exits 0 / 2 (safeguard violation) / 1
+(I/O error).
 
 ```sh
 echo "<content>" | bunx fit-selfedit <path>

package/bin/fit-benchmark.js

@@ -134,7 +134,7 @@ export const definition = {
     "fit-benchmark run --family=./families/coding --runs=10 --agent-model=claude-sonnet-4-6",
     "fit-benchmark score --family=./families/coding --task=todo-api --workdir=./benchmark-runs/runs/todo-api/0",
     "fit-benchmark report --format=text",
-    "fit-benchmark report --input=./runs/2026-05-11 --k=1,3,5 --format=text",
+    "fit-benchmark report --input=./runs/today --k=1,3,5 --format=text",
   ],
   documentation: [
     {

package/bin/fit-eval.js

@@ -34,6 +34,29 @@ const LEAD_OPTIONS = {
   },
 };
 
+// Shared task-input flags: --task-file (path), --task-text (inline), and
+// --task-event (path to native GitHub event JSON composed into a task via
+// libeval/src/events/github.js). Exactly one of the three is required.
+const TASK_INPUT_OPTIONS = {
+  "task-file": {
+    type: "string",
+    description: "Path to a markdown task file",
+  },
+  "task-text": {
+    type: "string",
+    description: "Inline task text (alternative to --task-file)",
+  },
+  "task-event": {
+    type: "string",
+    description:
+      "Path to a native GitHub event payload JSON, composed into the task via libeval/src/events/github.js (reads $GITHUB_EVENT_NAME)",
+  },
+  "task-amend": {
+    type: "string",
+    description: "Additional text appended to the task",
+  },
+};
+
 const definition = {
   name: "fit-eval",
   version: VERSION,
@@ -45,18 +68,7 @@ const definition = {
       args: "",
       description: "Run a single agent autonomously on a defined task",
       options: {
-        "task-file": {
-          type: "string",
-          description: "Path to a markdown task file",
-        },
-        "task-text": {
-          type: "string",
-          description: "Inline task text (alternative to --task-file)",
-        },
-        "task-amend": {
-          type: "string",
-          description: "Additional text appended to the task",
-        },
+        ...TASK_INPUT_OPTIONS,
         "agent-model": {
           type: "string",
           description:
@@ -92,18 +104,7 @@ const definition = {
       description:
         "Run a supervisor–agent relay — typical shape for agent-as-judge evaluations",
       options: {
-        "task-file": {
-          type: "string",
-          description: "Path to a markdown task file",
-        },
-        "task-text": {
-          type: "string",
-          description: "Inline task text (alternative to --task-file)",
-        },
-        "task-amend": {
-          type: "string",
-          description: "Additional text appended to the task",
-        },
+        ...TASK_INPUT_OPTIONS,
         "agent-model": {
           type: "string",
           description:
@@ -146,18 +147,7 @@ const definition = {
       description:
         "Run a facilitator with N participants — typical shape for multi-agent collaboration",
       options: {
-        "task-file": {
-          type: "string",
-          description: "Path to a markdown task file",
-        },
-        "task-text": {
-          type: "string",
-          description: "Inline task text (alternative to --task-file)",
-        },
-        "task-amend": {
-          type: "string",
-          description: "Additional text appended to the task",
-        },
+        ...TASK_INPUT_OPTIONS,
         "agent-model": {
           type: "string",
           description: "Claude model for agents (default: claude-opus-4-7[1m])",
@@ -192,18 +182,7 @@ const definition = {
       description:
         "Run an async, suspendable discussion — Chair + N participants + bridge callback",
       options: {
-        "task-file": {
-          type: "string",
-          description: "Path to a markdown task file",
-        },
-        "task-text": {
-          type: "string",
-          description: "Inline task text (alternative to --task-file)",
-        },
-        "task-amend": {
-          type: "string",
-          description: "Additional text appended to the task",
-        },
+        ...TASK_INPUT_OPTIONS,
         "agent-model": {
           type: "string",
           description: "Claude model for agents (default: claude-opus-4-7[1m])",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libeval",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "description": "Agent evaluation framework — prove whether agent changes improved outcomes with reproducible evidence.",
   "keywords": [
     "eval",
@@ -62,7 +62,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@forwardimpact/libharness": "^0.1.14"
+    "@forwardimpact/libmock": "^0.1.0"
   },
   "engines": {
     "bun": ">=1.2.0",

package/src/agent-runner.js

@@ -62,7 +62,9 @@ export class AgentRunner {
     const abortController = new AbortController();
     this.currentAbortController = abortController;
     const effectiveTask = this.taskAmend
-      ? `${task}\n\n${this.taskAmend}`
+      ? task
+        ? `${task}\n\n${this.taskAmend}`
+        : this.taskAmend
       : task;
     try {
       const iterator = this.query({

package/src/benchmark/npm-installer.js

@@ -0,0 +1,87 @@
+/**
+ * NpmInstaller — runs `bun install` in the family root when a package.json
+ * is present, then copies the resulting `node_modules/` into the staging
+ * directory so WorkdirManager can seed each per-task CWD.
+ *
+ * Symmetric to ApmInstaller: constructor injection of `spawn` for testability,
+ * factory function, and a free-function shorthand.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+import { access, cp } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Run `bun install` in the family root and stage node_modules/ for per-task CWDs. */
+export class NpmInstaller {
+  /**
+   * @param {object} [deps]
+   * @param {typeof nodeSpawn} [deps.spawn] - Spawn seam (defaults to
+   *   `node:child_process` spawn). Tests inject a fake to avoid shelling out.
+   */
+  constructor({ spawn } = {}) {
+    this.spawn = spawn ?? nodeSpawn;
+  }
+
+  /**
+   * @param {import("./task-family.js").TaskFamily} family
+   * @param {string} stagingDir - The staging directory (created by ApmInstaller).
+   * @returns {Promise<void>}
+   */
+  async install(family, stagingDir) {
+    const pkgJson = join(family.rootPath, "package.json");
+    const hasPkg = await access(pkgJson)
+      .then(() => true)
+      .catch(() => false);
+    if (!hasPkg) return;
+
+    await this.#runBunInstall(family.rootPath);
+
+    const sourceModules = join(family.rootPath, "node_modules");
+    try {
+      await access(sourceModules);
+    } catch {
+      throw new Error(
+        `bun install did not produce node_modules/ at ${sourceModules}; check the family's package.json`,
+      );
+    }
+
+    await cp(sourceModules, join(stagingDir, "node_modules"), {
+      recursive: true,
+    });
+  }
+
+  #runBunInstall(cwd) {
+    return new Promise((res, rej) => {
+      const child = this.spawn("bun", ["install"], {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let stderr = "";
+      child.stdout.on("data", () => {});
+      child.stderr.on("data", (d) => {
+        stderr += d.toString();
+      });
+      child.on("error", (e) => {
+        rej(new Error(`failed to spawn bun: ${e.message}`));
+      });
+      child.on("close", (code) => {
+        if (code === 0) res();
+        else rej(new Error(`bun install exited ${code}: ${stderr}`));
+      });
+    });
+  }
+}
+
+/** Factory function — wires real dependencies. */
+export function createNpmInstaller(deps) {
+  return new NpmInstaller(deps);
+}
+
+/**
+ * Free-function shorthand for callers that don't need to inject a spawn seam.
+ * @param {import("./task-family.js").TaskFamily} family
+ * @param {string} stagingDir
+ */
+export function installNpm(family, stagingDir) {
+  return new NpmInstaller().install(family, stagingDir);
+}

package/src/benchmark/runner.js

@@ -22,6 +22,7 @@ import { join, resolve as resolvePath } from "node:path";
 import { DEFAULT_ENV_ALLOWLIST, createRedactor } from "../redaction.js";
 import { createSupervisor } from "../supervisor.js";
 import { installApm as defaultInstallApm } from "./apm-installer.js";
+import { installNpm as defaultInstallNpm } from "./npm-installer.js";
 import { runJudge } from "./judge.js";
 import { validateResultRecord } from "./result.js";
 import { runScoring } from "./scorer.js";
@@ -68,6 +69,8 @@ export class BenchmarkRunner {
    *   Same contract as `installApm(family, outputDir)`. Lets tests inject a
    *   fake `apm` spawn (or skip the install entirely) so the suite never
    *   shells out to a real `apm` binary. Internal testing only.
+   * @param {Function} [opts.installNpm] - Test seam: replaces `installNpm`.
+   *   Same contract as `installNpm(family, stagingDir)`. Internal testing only.
    */
   constructor({
     family,
@@ -86,6 +89,7 @@ export class BenchmarkRunner {
     runScoring: runScoringHook,
     runJudge: runJudgeHook,
     installApm: installApmHook,
+    installNpm: installNpmHook,
   }) {
     if (!family) throw new Error("family is required");
     if (!Number.isInteger(runs) || runs < 1)
@@ -111,6 +115,7 @@ export class BenchmarkRunner {
     this._runScoringHook = runScoringHook ?? runScoring;
     this._runJudgeHook = runJudgeHook ?? runJudge;
     this._installApmHook = installApmHook ?? defaultInstallApm;
+    this._installNpmHook = installNpmHook ?? defaultInstallNpm;
   }
 
   /**
@@ -126,6 +131,7 @@ export class BenchmarkRunner {
     await mkdir(this.output, { recursive: true });
     const { stagingDir, skillSetHash, judgeProfilesDir } =
       await this._installApmHook(family, this.output);
+    await this._installNpmHook(family, stagingDir);
 
     const tasks = family.tasks();
     if (this.profiles.judge) {

package/src/benchmark/workdir.js

@@ -70,6 +70,11 @@ export class WorkdirManager {
     await cp(join(this.stagingDir, ".claude"), join(cwd, ".claude"), {
       recursive: true,
     });
+    await cp(join(this.stagingDir, "node_modules"), join(cwd, "node_modules"), {
+      recursive: true,
+    }).catch((e) => {
+      if (e.code !== "ENOENT") throw e;
+    });
 
     const envDirs = [
       ...(this.familyRootPath ? [this.familyRootPath] : []),

package/src/commands/benchmark-run.js

@@ -17,6 +17,14 @@ export async function runBenchmarkRunCommand(values, _args) {
   const opts = parseRunOptions(values);
   const config = await createConfig("script", "benchmark");
   process.env.ANTHROPIC_API_KEY = await config.anthropicToken();
+
+  // The Claude Agent SDK spawns a `claude` subprocess that inherits
+  // process.env. NODE_EXTRA_CA_CERTS causes undici (the HTTP client
+  // inside that subprocess) to fail with UND_ERR_INVALID_ARG on
+  // Node 22+, aborting every API call after 10 retries. Strip it
+  // before the SDK loads so the subprocess gets a clean environment.
+  delete process.env.NODE_EXTRA_CA_CERTS;
+
   const { query } = await import("@anthropic-ai/claude-agent-sdk");
   const runner = createBenchmarkRunner({ ...opts, query });
 

package/src/commands/discuss.js

@@ -1,8 +1,9 @@
-import { readFileSync, createWriteStream } from "node:fs";
+import { createWriteStream } from "node:fs";
 import { resolve } from "node:path";
 import { createDiscusser } from "../discusser.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
+import { resolveTaskContent } from "./task-input.js";
 
 function parseAgentProfiles(raw, cwd, maxTurns) {
   if (!raw) return [];
@@ -18,17 +19,8 @@ function parseAgentProfiles(raw, cwd, maxTurns) {
  * @param {object} values - Parsed option values
  * @returns {object}
  */
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: CLI option validation
 export function parseDiscussOptions(values) {
-  const taskFile = values["task-file"];
-  const taskText = values["task-text"];
-  if (taskFile && taskText)
-    throw new Error("--task-file and --task-text are mutually exclusive");
-  if (!taskFile && !taskText)
-    throw new Error("--task-file or --task-text is required");
-
-  const taskAmend = values["task-amend"] ?? undefined;
-  const taskContent = taskFile ? readFileSync(taskFile, "utf8") : taskText;
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(values);
 
   const profilesRaw = values["agent-profiles"];
   const agentCwd = resolve(values["agent-cwd"] ?? ".");

package/src/commands/facilitate.js

@@ -1,8 +1,9 @@
-import { readFileSync, createWriteStream } from "node:fs";
+import { createWriteStream } from "node:fs";
 import { resolve } from "node:path";
 import { createFacilitator } from "../facilitator.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
+import { resolveTaskContent } from "./task-input.js";
 
 /**
  * Parse comma-separated agent profile names into structured configs.
@@ -25,15 +26,7 @@ function parseAgentProfiles(raw, cwd, maxTurns) {
  * @returns {object} Parsed options
  */
 export function parseFacilitateOptions(values) {
-  const taskFile = values["task-file"];
-  const taskText = values["task-text"];
-  if (taskFile && taskText)
-    throw new Error("--task-file and --task-text are mutually exclusive");
-  if (!taskFile && !taskText)
-    throw new Error("--task-file or --task-text is required");
-
-  const taskAmend = values["task-amend"] ?? undefined;
-  const taskContent = taskFile ? readFileSync(taskFile, "utf8") : taskText;
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(values);
 
   const profilesRaw = values["agent-profiles"];
   if (!profilesRaw) throw new Error("--agent-profiles is required");

package/src/commands/run.js

@@ -1,4 +1,4 @@
-import { readFileSync, createWriteStream } from "node:fs";
+import { createWriteStream } from "node:fs";
 import { Writable } from "node:stream";
 import { resolve } from "node:path";
 import { createAgentRunner } from "../agent-runner.js";
@@ -6,6 +6,7 @@ import { composeProfilePrompt } from "../profile-prompt.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
 import { SequenceCounter } from "../sequence-counter.js";
+import { resolveTaskContent } from "./task-input.js";
 import { createServiceConfig } from "@forwardimpact/libconfig";
 
 /**
@@ -14,16 +15,8 @@ import { createServiceConfig } from "@forwardimpact/libconfig";
  * @returns {{ taskContent: string, cwd: string, model: string, maxTurns: number, outputPath: string|undefined, agentProfile: string|undefined, allowedTools: string[] }}
  */
 function parseRunOptions(values) {
-  const taskFile = values["task-file"];
-  const taskText = values["task-text"];
-  if (taskFile && taskText)
-    throw new Error("--task-file and --task-text are mutually exclusive");
-  if (!taskFile && !taskText)
-    throw new Error("--task-file or --task-text is required");
-
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(values);
   const maxTurnsRaw = values["max-turns"] ?? "50";
-  const taskAmend = values["task-amend"] ?? undefined;
-  const taskContent = taskFile ? readFileSync(taskFile, "utf8") : taskText;
 
   return {
     taskContent,

package/src/commands/supervise.js

@@ -1,9 +1,10 @@
-import { readFileSync, createWriteStream, mkdtempSync } from "node:fs";
+import { createWriteStream, mkdtempSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { tmpdir } from "node:os";
 import { createSupervisor } from "../supervisor.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
+import { resolveTaskContent } from "./task-input.js";
 import { createServiceConfig } from "@forwardimpact/libconfig";
 
 /**
@@ -11,20 +12,10 @@ import { createServiceConfig } from "@forwardimpact/libconfig";
  * @param {object} values - Parsed option values from cli.parse()
  * @returns {object}
  */
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: CLI option validation
 export function parseSuperviseOptions(values) {
-  const taskFile = values["task-file"];
-  const taskText = values["task-text"];
-  if (taskFile && taskText)
-    throw new Error("--task-file and --task-text are mutually exclusive");
-  if (!taskFile && !taskText)
-    throw new Error("--task-file or --task-text is required");
-
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(values);
   const supervisorAllowedToolsRaw = values["supervisor-allowed-tools"];
 
-  const taskAmend = values["task-amend"] ?? undefined;
-  const taskContent = taskFile ? readFileSync(taskFile, "utf8") : taskText;
-
   return {
     taskContent,
     taskAmend,

package/src/commands/task-input.js

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import { composeTaskFromGitHubEvent } from "../events/github.js";
+
+/**
+ * Resolve `--task-file` / `--task-text` / `--task-event` into the task pair the
+ * runner consumes. Exactly one of the three must be set. For `--task-event`,
+ * libeval reads the event payload and extracts both the main task (from the
+ * template that matches `$GITHUB_EVENT_NAME` + `payload.action`) and the
+ * amendment (from `payload.inputs?.prompt`) — so the workflow doesn't need to
+ * wire `--task-amend` separately. For the other two modes, `--task-amend`
+ * works as before.
+ *
+ * @param {object} values - Parsed option values from cli.parse()
+ * @returns {{ task: string, amend: string | undefined }}
+ */
+export function resolveTaskContent(values) {
+  const taskFile = values["task-file"];
+  const taskText = values["task-text"];
+  const taskEvent = values["task-event"];
+
+  const set = [taskFile, taskText, taskEvent].filter(Boolean).length;
+  if (set === 0) {
+    throw new Error(
+      "one of --task-file, --task-text, --task-event is required",
+    );
+  }
+  if (set > 1) {
+    throw new Error(
+      "--task-file, --task-text, --task-event are mutually exclusive",
+    );
+  }
+
+  const amendFlag = values["task-amend"] ?? undefined;
+
+  if (taskFile) {
+    return { task: readFileSync(taskFile, "utf8"), amend: amendFlag };
+  }
+  if (taskText) {
+    return { task: taskText, amend: amendFlag };
+  }
+
+  const eventName = process.env.GITHUB_EVENT_NAME;
+  if (!eventName) {
+    throw new Error("--task-event requires GITHUB_EVENT_NAME to be set");
+  }
+  const payload = JSON.parse(readFileSync(taskEvent, "utf8"));
+  const composed = composeTaskFromGitHubEvent(payload, eventName);
+  return { task: composed.task, amend: amendFlag ?? composed.amend };
+}

package/src/discuss-tools.js

@@ -20,28 +20,44 @@ import { tool } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
 
 import {
+  ADJOURN_DESC,
   baseTools,
   concludeSession,
   orchestrationServer,
+  RECESS_DESC,
   requestForCommentTool,
+  requireNoPendingAsks,
 } from "./orchestration-toolkit.js";
 
 /** System prompt for discuss-mode agent participants. L0 mechanics only per COALIGNED. */
 export const DISCUSS_AGENT_SYSTEM_PROMPT =
   "You are a participant in a discussion.\n" +
-  "Each question arrives as `[ask#N] <name>: <text>`.\n" +
+  "Each question arrives as `[ask#N] <name>: <text>` in your inbox.\n" +
   "Quote N as askId on your `Answer` to route the reply correctly.\n" +
   "Your `Answer` is posted to the discussion thread as a separate reply.\n" +
   "If the task already contains a completed response with no new human input after it, `Answer` that no further action is needed.\n" +
   "Do not redo completed work.";
 
-const RESUME_TRIGGER_SCHEMA = z
-  .object({
-    kind: z.enum(["responses", "elapsed", "either"]),
-    responses: z.number().optional(),
-    elapsed: z.string().optional(),
-  })
-  .strict();
+const RESUME_TRIGGER_SCHEMA = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("missing_input"),
+      replies: z.number().int().positive(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("escalation_needed"),
+      signal: z.string().min(1),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("elapsed"),
+      elapsed: z.string().min(1),
+    })
+    .strict(),
+]);
 
 /** Discuss-mode lead tool server. */
 export function createDiscussLeadToolServer(ctx) {
@@ -49,13 +65,13 @@ export function createDiscussLeadToolServer(ctx) {
     ...baseTools(ctx, { from: "lead", defaultTo: undefined, broadcast: true }),
     tool(
       "Recess",
-      "Suspend the run. The bridge re-dispatches the workflow when the trigger fires.",
+      RECESS_DESC,
       { reason: z.string(), trigger: RESUME_TRIGGER_SCHEMA },
       createRecessHandler(ctx),
     ),
     tool(
       "Adjourn",
-      "End the discussion with a verdict ('adjourned' / 'failed') and a summary.",
+      ADJOURN_DESC,
       {
         verdict: z.enum(["adjourned", "failed"]),
         summary: z.string(),
@@ -83,6 +99,8 @@ export function createDiscussAgentToolServer(ctx, { from }) {
  */
 export function createRecessHandler(ctx) {
   return async ({ reason, trigger }) => {
+    const guard = requireNoPendingAsks(ctx);
+    if (guard) return guard;
     ctx.recessTrigger = trigger;
     concludeSession(ctx, {
       verdict: "recessed",
@@ -96,6 +114,8 @@ export function createRecessHandler(ctx) {
 /** Adjourn handler — ends the discussion with a verdict. */
 export function createAdjournHandler(ctx) {
   return async ({ verdict, summary, outcome }) => {
+    const guard = requireNoPendingAsks(ctx);
+    if (guard) return guard;
     if (outcome !== undefined) ctx.outcome = outcome;
     concludeSession(ctx, {
       verdict,

package/src/discusser.js

@@ -36,10 +36,11 @@ export const DISCUSS_SYSTEM_PROMPT =
   "Use `Ask` to delegate work to the best-suited participant.\n" +
   "Participants are domain experts; state the task, not how to do it.\n" +
   "Each participant's `Answer` is posted to the discussion thread as a separate reply.\n" +
-  "`Ask` returns {askIds:[N,…]} immediately.\n" +
-  "Answers arrive on your next turn as `[answer#N] <participant>: <text>`.\n" +
-  "Multiple `Ask` calls in one turn run participants concurrently.\n" +
-  "Wait for all participants to `Answer` before calling `Adjourn` or `Recess`.";
+  "`Ask` is async and returns {askIds:[N,…]} immediately.\n" +
+  "Answers arrive on your next turn as `[answer#N] <participant>: <text>` in your inbox.\n" +
+  "End your turn while Asks are pending. The system resumes you when answers arrive.\n" +
+  "Multiple `Ask` calls in one turn run participants in parallel.\n" +
+  "End the discussion by calling `Adjourn` with a verdict and summary, or `Recess` only to wait on an external reply or duration.";
 
 /**
  * Augment a base orchestration context with discuss-mode fields.

package/src/events/github.js

@@ -0,0 +1,133 @@
+/**
+ * GitHub event → task-prompt composition. Replaces ~70 lines of shell in
+ * kata-dispatch.yml's `Compose task text` step. Each branch in the dispatch
+ * function corresponds to one (event_name, action) the agent workflows react
+ * to; the rendered string is identical to what the shell `case` block
+ * produced, so existing facilitator behaviour is preserved.
+ *
+ * Templates live as named `export const` declarations at the top of the file,
+ * mirroring `SUPERVISOR_SYSTEM_PROMPT` / `JUDGE_SYSTEM_PROMPT` / etc., so a
+ * reader scanning libeval source can find the exact string that an agent
+ * receives. Substitutions use `${KEY}` so the literal placeholders are
+ * grep-discoverable.
+ */
+
+export const TASK_TEMPLATE_ISSUE_OPENED =
+  'New issue: "${ISSUE_TITLE}" (#${NUMBER}) by @${AUTHOR} (type: ${AUTHOR_TYPE}). Issue URL: ${URL}.';
+
+export const TASK_TEMPLATE_ISSUE_LABELED =
+  'Label "${LABEL}" was added to issue "${ISSUE_TITLE}" (#${NUMBER}). Issue URL: ${URL}.';
+
+export const TASK_TEMPLATE_PR_LABELED =
+  'Label "${LABEL}" was added to PR "${PR_TITLE}" (#${NUMBER}). PR URL: ${URL}.';
+
+export const TASK_TEMPLATE_PR_MERGED =
+  'PR "${PR_TITLE}" (#${NUMBER}) merged. PR URL: ${URL}.';
+
+export const TASK_TEMPLATE_ISSUE_COMMENT_ON_ISSUE =
+  'New comment on issue "${ISSUE_TITLE}" (#${NUMBER}) by @${AUTHOR} (type: ${AUTHOR_TYPE}). Comment URL: ${URL}.';
+
+export const TASK_TEMPLATE_ISSUE_COMMENT_ON_PR =
+  "New comment on PR #${NUMBER} by @${AUTHOR} (type: ${AUTHOR_TYPE}). Comment URL: ${URL}.";
+
+export const TASK_TEMPLATE_REVIEW_SUBMITTED =
+  'Review submitted on PR "${PR_TITLE}" (#${NUMBER}) by @${AUTHOR} (type: ${AUTHOR_TYPE}). Review URL: ${URL}.';
+
+function render(template, fields) {
+  let out = template;
+  for (const [key, value] of Object.entries(fields)) {
+    out = out.replaceAll("${" + key + "}", value ?? "");
+  }
+  return out;
+}
+
+function extractCommonFields(payload) {
+  return {
+    NUMBER: String(payload.issue?.number ?? payload.pull_request?.number ?? ""),
+    ISSUE_TITLE: payload.issue?.title ?? "",
+    PR_TITLE: payload.pull_request?.title ?? "",
+    LABEL: payload.label?.name ?? "",
+    AUTHOR:
+      payload.comment?.user?.login ??
+      payload.review?.user?.login ??
+      payload.issue?.user?.login ??
+      payload.pull_request?.user?.login ??
+      "",
+    AUTHOR_TYPE:
+      payload.comment?.user?.type ??
+      payload.review?.user?.type ??
+      payload.issue?.user?.type ??
+      payload.pull_request?.user?.type ??
+      "User",
+    URL:
+      payload.comment?.html_url ??
+      payload.review?.html_url ??
+      payload.issue?.html_url ??
+      payload.pull_request?.html_url ??
+      "",
+  };
+}
+
+// Static `(event_name, action)` → template lookup. The "issue_comment" /
+// "created" entry needs payload context (issue vs PR), so it returns a chooser
+// instead of a template. Anything missing from the table throws downstream.
+const TEMPLATE_DISPATCH = {
+  "issues:opened": () => TASK_TEMPLATE_ISSUE_OPENED,
+  "issues:labeled": () => TASK_TEMPLATE_ISSUE_LABELED,
+  "pull_request:closed": () => TASK_TEMPLATE_PR_MERGED,
+  "pull_request:labeled": () => TASK_TEMPLATE_PR_LABELED,
+  "pull_request_target:closed": () => TASK_TEMPLATE_PR_MERGED,
+  "pull_request_target:labeled": () => TASK_TEMPLATE_PR_LABELED,
+  "pull_request_review:submitted": () => TASK_TEMPLATE_REVIEW_SUBMITTED,
+  "issue_comment:created": (payload) =>
+    payload.issue?.pull_request != null
+      ? TASK_TEMPLATE_ISSUE_COMMENT_ON_PR
+      : TASK_TEMPLATE_ISSUE_COMMENT_ON_ISSUE,
+};
+
+function pickTemplate(payload, eventName) {
+  const chooser = TEMPLATE_DISPATCH[`${eventName}:${payload.action}`];
+  return chooser ? chooser(payload) : null;
+}
+
+/**
+ * Compose the task a libeval lead receives from a native GitHub event payload.
+ * Returns `{ task, amend }`: `task` is the template-rendered context for real
+ * events (or empty string for `workflow_dispatch`); `amend` is read from
+ * `payload.inputs?.prompt` so an ad-hoc dispatcher (workflow_dispatch trigger
+ * or bridge) can layer instructions on top without the workflow wiring
+ * `--task-amend` separately. The runner combines them via the existing
+ * taskAmend path.
+ *
+ * Throws on unknown (event_name, action) combos so a typo doesn't silently
+ * ship a misleading prompt.
+ *
+ * @param {object} payload - Native event payload (shape mirrors
+ *   `$GITHUB_EVENT_PATH` JSON written by the runner).
+ * @param {string} eventName - Value of `$GITHUB_EVENT_NAME` for the run.
+ * @returns {{ task: string, amend: string }}
+ */
+export function composeTaskFromGitHubEvent(payload, eventName) {
+  if (!eventName) {
+    throw new Error("composeTaskFromGitHubEvent: eventName is required");
+  }
+
+  const amend = payload.inputs?.prompt ?? "";
+
+  if (eventName === "workflow_dispatch") {
+    if (!amend) {
+      throw new Error(
+        "composeTaskFromGitHubEvent: workflow_dispatch payload must include inputs.prompt",
+      );
+    }
+    return { task: "", amend };
+  }
+
+  const template = pickTemplate(payload, eventName);
+  if (!template) {
+    throw new Error(
+      `composeTaskFromGitHubEvent: no template for event_name="${eventName}" action="${payload.action}"`,
+    );
+  }
+  return { task: render(template, extractCommonFields(payload)), amend };
+}

package/src/facilitator.js

@@ -25,15 +25,16 @@ export const FACILITATOR_SYSTEM_PROMPT =
   "Use `RollCall` to list participants.\n" +
   "Use `Ask` to delegate work to the best-suited participant.\n" +
   "Participants are domain experts; state the task, not how to do it.\n" +
-  "`Ask` returns {askIds:[N,…]} immediately.\n" +
-  "Answers arrive on your next turn as `[answer#N] <participant>: <text>`.\n" +
-  "Multiple `Ask` calls in one turn run participants concurrently.\n" +
-  "Wait for all participants to `Answer` before calling `Conclude`.";
+  "`Ask` is async and returns {askIds:[N,…]} immediately.\n" +
+  "Answers arrive on your next turn as `[answer#N] <participant>: <text>` in your inbox.\n" +
+  "End your turn while Asks are pending. The system resumes you when answers arrive.\n" +
+  "Multiple `Ask` calls in one turn run participants in parallel.\n" +
+  "End every session by calling `Conclude` with a verdict and summary.";
 
 /** System prompt for facilitated agent participants. L0 mechanics only per COALIGNED. */
 export const FACILITATED_AGENT_SYSTEM_PROMPT =
   "You are a participant in a facilitated session.\n" +
-  "Each question arrives as `[ask#N] <name>: <text>`.\n" +
+  "Each question arrives as `[ask#N] <name>: <text>` in your inbox.\n" +
   "Quote N as askId on your `Answer` to route the reply correctly.\n" +
   "If the task already contains a completed response with no new human input after it, `Answer` that no further action is needed.\n" +
   "Do not redo completed work.";

package/src/index.js

@@ -50,6 +50,16 @@ export {
   DISCUSS_AGENT_SYSTEM_PROMPT,
 } from "./discuss-tools.js";
 export { Judge, createJudge, JUDGE_SYSTEM_PROMPT } from "./judge.js";
+export {
+  composeTaskFromGitHubEvent,
+  TASK_TEMPLATE_ISSUE_OPENED,
+  TASK_TEMPLATE_ISSUE_LABELED,
+  TASK_TEMPLATE_PR_LABELED,
+  TASK_TEMPLATE_PR_MERGED,
+  TASK_TEMPLATE_ISSUE_COMMENT_ON_ISSUE,
+  TASK_TEMPLATE_ISSUE_COMMENT_ON_PR,
+  TASK_TEMPLATE_REVIEW_SUBMITTED,
+} from "./events/github.js";
 export {
   Redactor,
   createRedactor,

package/src/orchestration-loop.js

@@ -94,7 +94,11 @@ export class OrchestrationLoop {
    */
   async run(task) {
     this.emitOrchestratorEvent({ type: "session_start" });
-    const initialTask = this.taskAmend ? `${task}\n\n${this.taskAmend}` : task;
+    const initialTask = this.taskAmend
+      ? task
+        ? `${task}\n\n${this.taskAmend}`
+        : this.taskAmend
+      : task;
 
     let firstError = null;
     const abort = (err) => {

package/src/orchestration-toolkit.js

@@ -46,9 +46,24 @@ export function createOrchestrationContext() {
 
 // --- Handler factories ---
 
+/**
+ * Guard for terminal tools (`Conclude`, `Adjourn`, `Recess`). Returns an
+ * error result when the caller still has Asks in flight, telling them to
+ * end the turn and wait for the auto-resume. Returns `null` when no Asks
+ * are pending and the terminal tool is free to run.
+ */
+export function requireNoPendingAsks(ctx) {
+  if (ctx.pendingAsks.size === 0) return null;
+  return errorResult(
+    "Asks are still pending. End your turn. You will be resumed when answers arrive.",
+  );
+}
+
 /** Mark the session as concluded; cancel any open Asks so askers see the synthetic null on their next turn. */
 export function createConcludeHandler(ctx) {
   return async ({ verdict, summary }) => {
+    const guard = requireNoPendingAsks(ctx);
+    if (guard) return guard;
     concludeSession(ctx, { verdict, summary, reason: "session concluded" });
     return { content: [{ type: "text", text: "Session concluded." }] };
   };
@@ -235,8 +250,18 @@ const ANNOUNCE_DESC = "Broadcast a message with no reply expected.";
 
 const ROLLCALL_DESC = "List all participants in the session.";
 
+// Terminal-tool descriptions. Each one ends the run. Group them so the
+// contrast is visible: Conclude (success/failure), Adjourn (settled in
+// thread), Recess (paused for out-of-session input). Each description
+// leads with the cost.
 const CONCLUDE_DESC =
-  "End the session with a verdict ('success' or 'failure') and a summary.";
+  "End the session. Provide a verdict ('success' or 'failure') and a summary.";
+
+const ADJOURN_DESC =
+  "End the discussion. Provide a verdict ('adjourned' or 'failed') and a summary. Cancels any unanswered Asks.";
+
+const RECESS_DESC =
+  "End the run and schedule an out-of-session re-dispatch. Cancels any unanswered Asks. Use only when waiting on an external reply or duration. Do not use to wait on in-flight Asks.";
 
 // --- Tool builders ---
 
@@ -244,6 +269,7 @@ const CONCLUDE_DESC =
 function textResult(text) {
   return { content: [{ type: "text", text }] };
 }
+/** Build an MCP tool error result wrapping a single text message. */
 function errorResult(text) {
   return { content: [{ type: "text", text }], isError: true };
 }
@@ -391,4 +417,11 @@ function requestForCommentTool(ctx) {
 
 // Re-export the building blocks discuss-tools.js needs to assemble its
 // own lead tool surface (it has two extra terminal tools).
-export { baseTools, orchestrationServer, requestForCommentTool };
+export {
+  ADJOURN_DESC,
+  baseTools,
+  errorResult,
+  orchestrationServer,
+  RECESS_DESC,
+  requestForCommentTool,
+};

package/src/render/tool-hints.js

@@ -101,7 +101,8 @@ export function simplifyToolName(name) {
  *
  * Three branches, in priority order:
  *  - A built-in tool with an entry in `HINT_HANDLERS` → sanitized hint, no
- *    `{` / `"` from the input (spec 540 criterion #2 for non-MCP tools).
+ *    `{` / `"` from the input (built-in tool hints stay free of JSON
+ *    punctuation so readers see clean one-liners).
  *  - An MCP-prefixed tool (`mcp__*`) → full input rendered as compact
  *    single-line JSON; `{` and `"` intentionally appear so readers see
  *    the actual MCP payload.

package/src/render/turn-renderer.js

@@ -2,8 +2,7 @@
  * Turn renderer — maps a structured turn into formatted text lines.
  *
  * Shared by `TeeWriter.flushTurns()` (live stream) and
- * `TraceCollector.toText()` (offline replay) so both emit identical output
- * (spec 540).
+ * `TraceCollector.toText()` (offline replay) so both emit identical output.
  */
 
 import {

package/src/supervisor.js

@@ -32,15 +32,16 @@ export const SUPERVISOR_SYSTEM_PROMPT =
   "You supervise one agent.\n" +
   "You have no tools to perform work yourself.\n" +
   "Use `Ask` to delegate work to the agent.\n" +
-  "`Ask` returns {askIds:[N]} immediately.\n" +
-  "The reply arrives on your next turn as `[answer#N] agent: <text>`.\n" +
+  "`Ask` is async and returns {askIds:[N]} immediately.\n" +
+  "The reply arrives on your next turn as `[answer#N] agent: <text>` in your inbox.\n" +
+  "End your turn while Asks are pending. The system resumes you when an answer arrives.\n" +
   "If the agent goes off-track, send a corrective `Ask`.\n" +
-  "End every session by calling `Conclude`.";
+  "End every session by calling `Conclude` with a verdict and summary.";
 
 /** System prompt for the supervised agent. L0 mechanics only per COALIGNED. */
 export const AGENT_SYSTEM_PROMPT =
   "A supervisor directs your work.\n" +
-  "Each question arrives as `[ask#N] supervisor: <text>`.\n" +
+  "Each question arrives as `[ask#N] supervisor: <text>` in your inbox.\n" +
   "Quote N as askId on your `Answer` to route the reply correctly.\n" +
   "If the task already contains a completed response with no new human input after it, `Answer` that no further action is needed.\n" +
   "Do not redo completed work.";

package/src/tee-writer.js

@@ -9,7 +9,7 @@
  *
  * Human text rendering is delegated to the pure modules under `./render/`
  * so the live stream and the offline `TraceCollector.toText()` replay share
- * one formatting path (spec 540). The NDJSON going to `fileStream` is
+ * one formatting path. The NDJSON going to `fileStream` is
  * untouched — only what reaches `textStream` changes.
  *
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
@@ -67,10 +67,9 @@ export class TeeWriter extends Writable {
     }
 
     // Emit the trailing `--- Result: ... ---` footer — the one summary line
-    // humans want (spec 540). This is the same tail TraceCollector.toText()
-    // appends, so the live stream and the offline replay stay in sync
-    // (spec 540 criterion #6). The superseded `--- Evaluation ... ---`
-    // footer is gone in every mode.
+    // humans want. This is the same tail TraceCollector.toText()
+    // appends, so the live stream and the offline replay stay in sync.
+    // The superseded `--- Evaluation ... ---` footer is gone in every mode.
     if (this.collector.result) {
       const text = this.collector.toText();
       const idx = text.lastIndexOf("\n---");
@@ -78,7 +77,7 @@ export class TeeWriter extends Writable {
         // Slice past the leading `\n` — the previously-streamed body
         // already ended with its own newline, so re-emitting `\n---` here
         // would produce a blank line before the footer and desync from
-        // the offline replay (spec 540 #6).
+        // the offline replay.
         this.textStream.write(text.slice(idx + 1) + "\n");
       }
     }
@@ -107,7 +106,8 @@ export class TeeWriter extends Writable {
       this.collector.addLine(line);
 
       // Orchestrator lifecycle events are suppressed from the text stream
-      // entirely (spec 540). They still reached fileStream above.
+      // entirely — humans only want agent-visible content. They still
+      // reached fileStream above.
       if (
         parsed.source === "orchestrator" &&
         isSuppressedOrchestratorEvent(parsed.event)
@@ -118,7 +118,7 @@ export class TeeWriter extends Writable {
       return;
     }
 
-    // Bare event (run mode pre-migration or direct feed)
+    // Bare event (unwrapped run mode line or direct feed)
     this.collector.addLine(line);
     this.flushTurns();
   }

package/src/trace-collector.js

@@ -6,7 +6,7 @@
  *
  * Human text rendering is delegated to the pure modules under `./render/`
  * so the live `TeeWriter` stream and the offline `toText()` replay share
- * one formatting path (spec 540).
+ * one formatting path.
  */
 
 import { renderTurnLines } from "./render/turn-renderer.js";
@@ -293,7 +293,7 @@ export class TraceCollector {
   }
 
   /**
-   * Format the trailing result summary line (spec 540). When an orchestrator
+   * Format the trailing result summary line. When an orchestrator
    * summary is present (supervised / facilitated mode), the headline word is
    * the supervisor's verdict ("success" / "failure") rather than the SDK's
    * per-runner subtype, so the footer aligns with the CI exit code.