balladeer 1.0.15 → 1.0.17

package/README.md

@@ -206,6 +206,8 @@ your own branch protection.
 | `npx -y balladeer@latest discover`     | File a whole catalog, up to ten promises from one file, behind one review link   |
 | `npx -y balladeer@latest touch-map`    | Record which files each promise's verifier runs, on this machine only            |
 | `npx -y balladeer@latest affected`     | Say which promises the files you name touch, out of that record                  |
+| `npx -y balladeer@latest risk`         | Rank the promises a change could put at risk, on this machine only               |
+| `npx -y balladeer@latest offers`       | Read a change for up to three rules no promise records, and record nothing       |
 | `npx -y balladeer@latest session`      | Print the id for this piece of work, and the line to write into the commit       |
 | `npx -y balladeer@latest mcp`          | Forward one MCP session over stdio using this repository's connection            |
 | `npx -y balladeer@latest explain`      | What Balladeer can and cannot see, where to watch it, and what leaving costs     |

package/dist/behavior-map-schema.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `balladeer-behavior-map/v1`, as `docs/agentic-testing/contracts.md` spells it.
+ *
+ * Written without a schema library on purpose. The published command carries
+ * exactly one reviewed runtime dependency (`tests/packaging/cli-package.test.ts`
+ * holds it there), so the shape is checked by hand here, with the field names
+ * copied from the contract. It is the one reader of maps: `balladeer map` writes
+ * through it and the risk ranking (`risk/`) reads through it, so a field added
+ * here reaches both, and `tests/risk/contract.test.ts` round-trips a full map.
+ */
+export declare const BEHAVIOR_MAP_SCHEMA_VERSION = "balladeer-behavior-map/v1";
+export declare const BEHAVIOR_MAP_DIRECTORY = ".continuity/behavior-maps";
+export declare const ENTRY_POINT_KINDS: readonly ["route", "command", "ui", "job", "event", "function"];
+export declare const SYMBOL_KINDS: readonly ["function", "class", "method", "const", "type", "module"];
+export declare const SYMBOL_ROLES: readonly ["core", "supporting"];
+export declare const RESOURCE_KINDS: readonly ["table", "column", "route", "flag", "env", "queue", "event", "outbound", "file", "config"];
+export declare const RESOURCE_ACCESS: readonly ["read", "write", "both", "call"];
+/** Positions in the agreed meaning: `passing-1`, `failing-2`, `refactor-1`. */
+export declare const CASE_ID: RegExp;
+export type BehaviorMapEntryPoint = {
+    file: string;
+    symbol: string;
+    kind: (typeof ENTRY_POINT_KINDS)[number];
+    note: string;
+};
+export type BehaviorMapSymbol = {
+    file: string;
+    name: string;
+    kind: (typeof SYMBOL_KINDS)[number];
+    role: (typeof SYMBOL_ROLES)[number];
+};
+export type BehaviorMapResource = {
+    kind: (typeof RESOURCE_KINDS)[number];
+    name: string;
+    access: (typeof RESOURCE_ACCESS)[number];
+};
+export type BehaviorMapLinkedTest = {
+    file: string;
+    name: string;
+    cases: string[];
+};
+export type BehaviorMapSink = {
+    caseId: string;
+    effect: string;
+    resources: string[];
+    /** `file#symbol`. */
+    symbols: string[];
+};
+/**
+ * The part of the agreed meaning a scorer needs without asking the server:
+ * the contract addendum of 28 September. `surfaces` is the promise's own scope
+ * surfaces, which the scope-only baseline reads.
+ */
+export type BehaviorMapMeaning = {
+    title: string;
+    observableOutcome: string;
+    failingExamples: {
+        id: string;
+        text: string;
+    }[];
+    nonGoals: string[];
+    surfaces?: string[];
+};
+export type BehaviorMap = {
+    schemaVersion: typeof BEHAVIOR_MAP_SCHEMA_VERSION;
+    promiseId: string;
+    semanticDigest: string;
+    mappedAt: {
+        sha: string;
+        at: string;
+        client: "claude" | "codex";
+        model: string;
+    };
+    entryPoints: BehaviorMapEntryPoint[];
+    symbols: BehaviorMapSymbol[];
+    resources: BehaviorMapResource[];
+    linkedTests: BehaviorMapLinkedTest[];
+    sinks: BehaviorMapSink[];
+    confidence: number;
+    notes: string;
+    meaning?: BehaviorMapMeaning;
+};
+/** Ceilings, so a map stays a small file a person can read in a review. */
+export declare const MAP_LIMITS: {
+    readonly entryPoints: 20;
+    readonly symbols: 60;
+    readonly resources: 40;
+    readonly linkedTests: 20;
+    readonly sinks: 20;
+    readonly text: 2000;
+    readonly name: 400;
+};
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Promise ids: `prom_` ids from Balladeer, and the evaluation harness's own ids. */
+export declare const PROMISE_ID: RegExp;
+/** A whole map, checked against the contract. Unknown fields are refused. */
+export declare function parseBehaviorMap(value: unknown): ParseResult<BehaviorMap>;
+/** Every file a map names: the derived `files` field, which is never stored. */
+export declare function mapFiles(map: BehaviorMap): string[];
+/** The map as it is written to disk: two-space JSON and a final newline. */
+export declare function serializeBehaviorMap(map: BehaviorMap): string;

package/dist/behavior-map-schema.js

@@ -0,0 +1,232 @@
+/**
+ * `balladeer-behavior-map/v1`, as `docs/agentic-testing/contracts.md` spells it.
+ *
+ * Written without a schema library on purpose. The published command carries
+ * exactly one reviewed runtime dependency (`tests/packaging/cli-package.test.ts`
+ * holds it there), so the shape is checked by hand here, with the field names
+ * copied from the contract. It is the one reader of maps: `balladeer map` writes
+ * through it and the risk ranking (`risk/`) reads through it, so a field added
+ * here reaches both, and `tests/risk/contract.test.ts` round-trips a full map.
+ */
+export const BEHAVIOR_MAP_SCHEMA_VERSION = "balladeer-behavior-map/v1";
+export const BEHAVIOR_MAP_DIRECTORY = ".continuity/behavior-maps";
+export const ENTRY_POINT_KINDS = ["route", "command", "ui", "job", "event", "function"];
+export const SYMBOL_KINDS = ["function", "class", "method", "const", "type", "module"];
+export const SYMBOL_ROLES = ["core", "supporting"];
+export const RESOURCE_KINDS = [
+    "table",
+    "column",
+    "route",
+    "flag",
+    "env",
+    "queue",
+    "event",
+    "outbound",
+    "file",
+    "config",
+];
+export const RESOURCE_ACCESS = ["read", "write", "both", "call"];
+/** Positions in the agreed meaning: `passing-1`, `failing-2`, `refactor-1`. */
+export const CASE_ID = /^(passing|failing|refactor)-[1-9][0-9]{0,2}$/;
+/** Ceilings, so a map stays a small file a person can read in a review. */
+export const MAP_LIMITS = {
+    entryPoints: 20,
+    symbols: 60,
+    resources: 40,
+    linkedTests: 20,
+    sinks: 20,
+    text: 2000,
+    name: 400,
+};
+const text = (max, allowEmpty = true) => (value, at, errors) => {
+    if (typeof value !== "string") {
+        errors.push(`${at} must be a string`);
+        return undefined;
+    }
+    if (!allowEmpty && value.trim() === "") {
+        errors.push(`${at} must not be empty`);
+        return undefined;
+    }
+    if (value.length > max) {
+        errors.push(`${at} is longer than ${max} characters`);
+        return undefined;
+    }
+    return value;
+};
+const oneOf = (values) => (value, at, errors) => {
+    if (typeof value === "string" && values.includes(value))
+        return value;
+    errors.push(`${at} must be one of ${values.join(", ")}`);
+    return undefined;
+};
+/** Repository-relative, forward slashes, inside the repository. */
+const repositoryPath = (value, at, errors) => {
+    const path = text(MAP_LIMITS.name, false)(value, at, errors);
+    if (path === undefined)
+        return undefined;
+    if (path.startsWith("/") ||
+        path.includes("\\") ||
+        /^[A-Za-z]:/.test(path) ||
+        path.split("/").some((part) => part === "..")) {
+        errors.push(`${at} must be a repository-relative path with forward slashes`);
+        return undefined;
+    }
+    return path;
+};
+const listOf = (item, max) => (value, at, errors) => {
+    if (!Array.isArray(value)) {
+        errors.push(`${at} must be a list`);
+        return undefined;
+    }
+    if (value.length > max) {
+        errors.push(`${at} has more than ${max} entries`);
+        return undefined;
+    }
+    const out = [];
+    let failed = false;
+    value.forEach((entry, index) => {
+        const checked = item(entry, `${at}[${index}]`, errors);
+        if (checked === undefined)
+            failed = true;
+        else
+            out.push(checked);
+    });
+    return failed ? undefined : out;
+};
+const record = (fields, optional = []) => (value, at, errors) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        errors.push(`${at} must be an object`);
+        return undefined;
+    }
+    const input = value;
+    const unknown = Object.keys(input).filter((key) => !(key in fields));
+    if (unknown.length > 0) {
+        errors.push(`${at} has fields the contract does not define: ${unknown.join(", ")}`);
+        return undefined;
+    }
+    const out = {};
+    let failed = false;
+    for (const key of Object.keys(fields)) {
+        if (!(key in input) || input[key] === undefined) {
+            if (optional.includes(key))
+                continue;
+            errors.push(`${at}.${key} is missing`);
+            failed = true;
+            continue;
+        }
+        const checked = fields[key](input[key], `${at}.${key}`, errors);
+        if (checked === undefined)
+            failed = true;
+        else
+            out[key] = checked;
+    }
+    return failed ? undefined : out;
+};
+const caseId = (value, at, errors) => {
+    if (typeof value === "string" && CASE_ID.test(value))
+        return value;
+    errors.push(`${at} must be a case id such as passing-1 or failing-2`);
+    return undefined;
+};
+const fileSymbol = (value, at, errors) => {
+    const reference = text(MAP_LIMITS.name, false)(value, at, errors);
+    if (reference === undefined)
+        return undefined;
+    const hash = reference.indexOf("#");
+    if (hash <= 0 || hash === reference.length - 1) {
+        errors.push(`${at} must be file#symbol`);
+        return undefined;
+    }
+    return repositoryPath(reference.slice(0, hash), at, errors) === undefined ? undefined : reference;
+};
+const confidence = (value, at, errors) => {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1)
+        return value;
+    errors.push(`${at} must be a number from 0 to 1`);
+    return undefined;
+};
+const SHA = /^[0-9a-f]{40}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+/** Promise ids: `prom_` ids from Balladeer, and the evaluation harness's own ids. */
+export const PROMISE_ID = /^[A-Za-z0-9_.-]{1,128}$/;
+const pattern = (regex, description) => (value, at, errors) => {
+    if (typeof value === "string" && regex.test(value))
+        return value;
+    errors.push(`${at} must be ${description}`);
+    return undefined;
+};
+const isoInstant = (value, at, errors) => {
+    if (typeof value === "string" && !Number.isNaN(Date.parse(value)))
+        return value;
+    errors.push(`${at} must be an ISO timestamp`);
+    return undefined;
+};
+const meaningChecker = record({
+    title: text(MAP_LIMITS.text, false),
+    observableOutcome: text(16_000, false),
+    failingExamples: listOf(record({ id: caseId, text: text(8000, false) }), MAP_LIMITS.sinks),
+    nonGoals: listOf(text(MAP_LIMITS.text), 40),
+    surfaces: listOf(text(MAP_LIMITS.name, false), 40),
+}, ["surfaces"]);
+const mapChecker = record({
+    schemaVersion: oneOf([BEHAVIOR_MAP_SCHEMA_VERSION]),
+    promiseId: pattern(PROMISE_ID, "a promise id"),
+    semanticDigest: pattern(DIGEST, "sha256: followed by 64 hex characters"),
+    mappedAt: record({
+        sha: pattern(SHA, "a 40-character commit sha"),
+        at: isoInstant,
+        client: oneOf(["claude", "codex"]),
+        model: text(MAP_LIMITS.name),
+    }),
+    entryPoints: listOf(record({
+        file: repositoryPath,
+        symbol: text(MAP_LIMITS.name, false),
+        kind: oneOf(ENTRY_POINT_KINDS),
+        note: text(MAP_LIMITS.text),
+    }), MAP_LIMITS.entryPoints),
+    symbols: listOf(record({
+        file: repositoryPath,
+        name: text(MAP_LIMITS.name, false),
+        kind: oneOf(SYMBOL_KINDS),
+        role: oneOf(SYMBOL_ROLES),
+    }), MAP_LIMITS.symbols),
+    resources: listOf(record({
+        kind: oneOf(RESOURCE_KINDS),
+        name: text(MAP_LIMITS.name, false),
+        access: oneOf(RESOURCE_ACCESS),
+    }), MAP_LIMITS.resources),
+    linkedTests: listOf(record({
+        file: repositoryPath,
+        name: text(MAP_LIMITS.name),
+        cases: listOf(caseId, 40),
+    }), MAP_LIMITS.linkedTests),
+    sinks: listOf(record({
+        caseId,
+        effect: text(MAP_LIMITS.text, false),
+        resources: listOf(text(MAP_LIMITS.name, false), 20),
+        symbols: listOf(fileSymbol, 20),
+    }), MAP_LIMITS.sinks),
+    confidence,
+    notes: text(MAP_LIMITS.text),
+    meaning: meaningChecker,
+}, ["meaning"]);
+/** A whole map, checked against the contract. Unknown fields are refused. */
+export function parseBehaviorMap(value) {
+    const errors = [];
+    const map = mapChecker(value, "map", errors);
+    return map === undefined ? { ok: false, errors } : { ok: true, value: map };
+}
+/** Every file a map names: the derived `files` field, which is never stored. */
+export function mapFiles(map) {
+    return [
+        ...new Set([
+            ...map.entryPoints.map((entry) => entry.file),
+            ...map.symbols.map((entry) => entry.file),
+            ...map.linkedTests.map((entry) => entry.file),
+        ]),
+    ].sort();
+}
+/** The map as it is written to disk: two-space JSON and a final newline. */
+export function serializeBehaviorMap(map) {
+    return `${JSON.stringify(map, null, 2)}\n`;
+}

package/dist/cli.d.ts

@@ -33,7 +33,7 @@ type Parsed = Readonly<{
      */
     repositories: readonly string[];
     hook: "codex" | "claude" | undefined;
-    event: "SessionStart" | "UserPromptSubmit" | "SubagentStart" | undefined;
+    event: "SessionStart" | "UserPromptSubmit" | "SubagentStart" | "PostToolUse" | undefined;
     owner: string | undefined;
     /** `check-seals --install-hook`: write the optional pre-push hook. */
     installHook: boolean;
@@ -45,6 +45,11 @@ type Parsed = Readonly<{
     again: boolean;
     /** `check-seals --runner`: where the pinned runner is, when it has moved. */
     runner: string | undefined;
+    /** `risk --base` and `--head`: the two ends of the change. */
+    base: string | undefined;
+    head: string | undefined;
+    /** `risk --maps`: where the behavior maps are, when not in the checkout. */
+    maps: string | undefined;
     createWorkspace: string | undefined;
     /** Everything that was not a flag: the addresses `invite` sends to. */
     positional: readonly string[];

package/dist/cli.js

@@ -9,10 +9,14 @@ import { runDiscover } from "./commands/discover.js";
 import { runExplain } from "./commands/explain.js";
 import { parseRole, runInvite } from "./commands/invite.js";
 import { runGuidance } from "./commands/guidance.js";
+import { JUDGE_USAGE, judgeCommand } from "./commands/judge.js";
+import { MAP_USAGE, mapCommand } from "./commands/map.js";
+import { OFFERS_USAGE, offersCommand } from "./commands/offers.js";
 import { runMcp } from "./commands/mcp.js";
 import { runPrepare } from "./commands/prepare.js";
 import { runPropose } from "./commands/propose.js";
 import { runRepositories } from "./commands/repositories.js";
+import { runRisk } from "./commands/risk.js";
 import { CREATE_WORKSPACE_MAX_LENGTH, runSetup } from "./commands/setup.js";
 import { runSession } from "./commands/session.js";
 import { runStatus } from "./commands/status.js";
@@ -21,7 +25,7 @@ import { runWhoami } from "./commands/whoami.js";
 import { runInstall } from "./install.js";
 import { openInBrowser } from "./open-browser.js";
 import { PUBLISHED_SPECIFIER } from "./release.js";
-import { CODEX_HOOK_APPROVAL, installUserScope, runningFromCheckout, userHome, } from "./user-scope.js";
+import { codexHookApproval, installUserScope, pushCheckSetupLine, pushCheckState, runningFromCheckout, userHome, } from "./user-scope.js";
 import { updateNotice } from "./currency.js";
 import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "./remove-earlier.js";
 import { recordSelfUpdateState, SELF_UPDATE_ENVIRONMENT } from "./self-update.js";
@@ -155,6 +159,17 @@ const USAGE = `balladeer ${CLI_VERSION}
       answer whose verifier has changed since the map was built. It reads one
       local file and contacts nothing.
 
+${MAP_USAGE}
+${JUDGE_USAGE}
+${OFFERS_USAGE}
+  ${CLI_INVOCATION} risk [--base <ref>] [--head <ref>] [--json] [--maps <dir>]
+      Rank the promises this change could put at risk, with the evidence for
+      each: a mapped function or test it changes, a table, route or file it
+      shares, what imports what, and what its commit messages say. It reads
+      the behavior maps in .continuity/behavior-maps/ and the change from git,
+      from the merge base with this branch's upstream (else origin/main) to
+      HEAD unless named. Runs offline; nothing is sent. --json prints the report.
+
   ${CLI_INVOCATION} session [--new] [--record] [--repo owner/name] [--repository <uuid>] [--json]
                     [--control-plane <url>]
       Print the id for this piece of work, and the one line to write into the
@@ -211,6 +226,9 @@ export function parseArguments(argv) {
     let record = false;
     let again = false;
     let runner;
+    let base;
+    let head;
+    let maps;
     let controlPlane;
     let repo;
     let file;
@@ -229,6 +247,9 @@ export function parseArguments(argv) {
         "--role": "contributor, viewer, or administrator",
         "--client": "codex or claude",
         "--runner": "a path to the pinned runner's cli.js",
+        "--base": "a git ref",
+        "--head": "a git ref",
+        "--maps": "a directory of behavior maps",
     };
     const value = (flag, inline) => {
         const next = inline ?? args.shift();
@@ -254,8 +275,9 @@ export function parseArguments(argv) {
             const requested = value("--event", inline);
             if (requested !== "SessionStart" &&
                 requested !== "UserPromptSubmit" &&
-                requested !== "SubagentStart")
-                throw new StoreError("usage", "--event needs SessionStart, UserPromptSubmit or SubagentStart.");
+                requested !== "SubagentStart" &&
+                requested !== "PostToolUse")
+                throw new StoreError("usage", "--event needs SessionStart, UserPromptSubmit, SubagentStart or PostToolUse.");
             event = requested;
         }
         else if (name === "--json")
@@ -270,6 +292,12 @@ export function parseArguments(argv) {
             record = true;
         else if (name === "--runner")
             runner = value("--runner", inline);
+        else if (name === "--base")
+            base = value("--base", inline);
+        else if (name === "--head")
+            head = value("--head", inline);
+        else if (name === "--maps")
+            maps = value("--maps", inline);
         else if (name === "--wait")
             wait = true;
         else if (name === "--no-open")
@@ -380,6 +408,8 @@ export function parseArguments(argv) {
     }
     if (hook !== undefined && command !== "guidance")
         throw new StoreError("usage", "--hook belongs to guidance.");
+    if ((base !== undefined || head !== undefined || maps !== undefined) && command !== "risk")
+        throw new StoreError("usage", "--base, --head and --maps belong to risk.");
     if (event !== undefined && command !== "guidance")
         throw new StoreError("usage", "--event belongs to guidance.");
     const chosen = controlPlane ?? process.env.BALLADEER_CONTROL_PLANE?.trim() ?? DEFAULT_CONTROL_PLANE;
@@ -407,6 +437,9 @@ export function parseArguments(argv) {
         record,
         again,
         runner,
+        base,
+        head,
+        maps,
         createWorkspace,
         positional,
         role,
@@ -414,6 +447,20 @@ export function parseArguments(argv) {
     };
 }
 export async function main(argv) {
+    // `map`, `judge` and `offers` read their own flags: `--hook`, `--repo` and
+    // `--install-hook` mean something different there, and `judge --hook` runs
+    // inside a coding host where a stderr nag would reach the agent.
+    if (argv[0] === "map" || argv[0] === "judge" || argv[0] === "offers") {
+        const io = {
+            cwd: process.cwd(),
+            environment: process.env,
+            write: (text) => void process.stdout.write(text),
+            error: (text) => void process.stderr.write(text),
+        };
+        if (argv[0] === "offers")
+            return offersCommand(argv.slice(1), io);
+        return argv[0] === "map" ? mapCommand(argv.slice(1), io) : judgeCommand(argv.slice(1), io);
+    }
     let parsed;
     try {
         parsed = parseArguments(argv);
@@ -451,12 +498,14 @@ function commandVersion(name) {
 function installEverything(options) {
     const published = !runningFromCheckout();
     let writes;
+    let pushCheck = "unavailable";
     const register = (installed) => {
         writes = installUserScope({
             environment: process.env,
             published,
             ...(installed === undefined ? {} : { installed }),
         });
+        pushCheck = pushCheckState(process.env, published, installed);
         return writes;
     };
     const code = runInstall({
@@ -464,12 +513,15 @@ function installEverything(options) {
         json: options.json,
         write: options.write,
         allowPartial: options.allowPartial,
-        onInstalled: (result) => ({ userScope: register(result.command) }),
+        onInstalled: (result) => {
+            const userScope = register(result.command);
+            return { userScope, pushCheck };
+        },
     });
     if (writes === undefined) {
         const fallback = register();
         if (options.json)
-            options.write(`${JSON.stringify({ step: "user_scope", userScope: fallback })}\n`);
+            options.write(`${JSON.stringify({ step: "user_scope", userScope: fallback, pushCheck })}\n`);
     }
     for (const w of writes ?? [])
         if (!options.json)
@@ -485,7 +537,7 @@ function installEverything(options) {
         if (options.json)
             options.write(`${JSON.stringify({ step: "codex_hooks", approval: codex.status === "written" ? "required" : "check", command: "/hooks" })}\n`);
         else
-            options.write(`${CODEX_HOOK_APPROVAL}\n`);
+            options.write(`${codexHookApproval(pushCheck !== "unavailable")}\n`);
     }
     // With the user-scope form in place, the older per-repository form in this
     // checkout only makes the session hear the guidance twice. Out it goes, with
@@ -508,6 +560,13 @@ function installEverything(options) {
         options.write("Balladeer now runs in every Claude Code" +
             ((writes ?? []).some((w) => w.host === "codex") ? " and Codex" : "") +
             " session on this machine. In a folder of a connected repository it works as before; anywhere else it stays quiet, and `balladeer status` there says why.\n");
+    // The push check rides on the same hooks file, so it is on wherever that
+    // file was written: said once per run, with how to turn it off. Under
+    // --json it is the `pushCheck` field of the install step, so that step stays
+    // one object.
+    const hooksFile = (writes ?? []).find((w) => w.path.endsWith("settings.json"));
+    if (!options.json && hooksFile !== undefined && hooksFile.status !== "refused")
+        options.write(`${pushCheckSetupLine(pushCheck)}\n`);
     const outcome = (writes ?? []).some((w) => w.status === "refused") ? 4 : code;
     // Started by the session hook's background update: leave how it ended where
     // the next hook fire will find it and tell the server.
@@ -654,6 +713,15 @@ async function dispatch(parsed, write) {
                 cwd: process.cwd(),
                 write,
             });
+        case "risk":
+            return runRisk({
+                json: parsed.json,
+                ...(parsed.base === undefined ? {} : { base: parsed.base }),
+                ...(parsed.head === undefined ? {} : { head: parsed.head }),
+                ...(parsed.maps === undefined ? {} : { maps: parsed.maps }),
+                cwd: process.cwd(),
+                write,
+            });
         case "affected":
             return runAffected({
                 json: parsed.json,

package/dist/commands/guidance.d.ts

@@ -5,7 +5,8 @@ export type GuidanceOptions = Readonly<{
     controlPlane: string;
     repositoryId?: string;
     hook: "codex" | "claude";
-    event?: GuidanceEvent;
+    /** PostToolUse is the relay note, not guidance: see `runRelayNote`. */
+    event?: GuidanceEvent | "PostToolUse";
     runtimeGeneration?: string;
     environment: NodeJS.ProcessEnv;
     cwd: string;

package/dist/commands/guidance.js

@@ -1,3 +1,4 @@
+import { relayHook } from "../relay.js";
 import { validateProjectGuidanceScope } from "../guidance-install.js";
 import { GUIDANCE_UNAVAILABLE, loadGuidance, recordGuidanceContext, } from "../guidance.js";
 import { readCredentials } from "../store.js";
@@ -60,8 +61,62 @@ function eventFrom(input) {
 function identifier(input) {
     return typeof input === "string" && input.length > 0 && input.length <= 256 ? input : undefined;
 }
+/**
+ * After a Balladeer tool acts, a note the agent reads before it replies: tell
+ * the person what Balladeer did, in your own words (promise
+ * prom_45ef4e3d9e5545a9a411; plans/promise-relations/plan.md, step 1). Codex
+ * relayed every detail in 10 of 10 lab sessions with it and 6 of 10 without.
+ * Local only: no connection, no network, nothing stored. A tool result can be
+ * large, so the input bound is wider than guidance's; anything unreadable,
+ * oversized or late prints nothing, never the guidance-unavailable notice.
+ */
+async function runRelayNote(options) {
+    const input = await new Promise((resolve) => {
+        const chunks = [];
+        let bytes = 0;
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.stdin.removeListener("data", data);
+            resolve(value);
+        };
+        const data = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            bytes += buffer.length;
+            if (bytes > 1_048_576)
+                done(undefined);
+            else
+                chunks.push(buffer);
+        };
+        const timer = setTimeout(() => done(undefined), 1_000);
+        options.stdin.on("data", data);
+        options.stdin.once("end", () => {
+            try {
+                done(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                done(undefined);
+            }
+        });
+        options.stdin.once("error", () => done(undefined));
+    });
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return 0;
+    const record = input;
+    if (record.hook_event_name !== "PostToolUse")
+        return 0;
+    const out = relayHook(record);
+    if (out)
+        options.write(`${out}\n`);
+    return 0;
+}
 /** Hook stdout is bounded context only. Host prompts and transcript paths never leave this process. */
 export async function runGuidance(options) {
+    if (options.event === "PostToolUse")
+        return runRelayNote(options);
     // A project hook names its repository and must match the checkout it sits
     // in. A user-scope hook names none: the folder's remotes decide.
     const projectScoped = options.repositoryId !== undefined;