pi-daddy 0.32.1 → 0.34.0

package/src/advisors/advisor.ts

@@ -0,0 +1,123 @@
+/**
+ * The wrapper that makes "every use is recorded" structural rather than a rule (ADR-0077).
+ *
+ * A caller cannot reach a `Decider` directly through this layer's public surface: it asks an `Advisor`, and asking
+ * always produces an `advice` record — including when the answer was "no advice", which is the case a reviewer most
+ * needs to see, because an advisor that silently stops answering would otherwise look exactly like one nobody used.
+ *
+ * **What is recorded, and what is not.** The record names the purpose, the decider, the question keys, the answers
+ * and how long it took. It does NOT contain the state. A caller composes that state from its own context, which can
+ * include task text, file contents and a repository's private material; the ledger has never stored a task
+ * (ADR-0021) and an advisor must not become the way it starts. The question keys are the caller's own constants,
+ * so they name the decision without describing the situation.
+ */
+import type { Advice, AdviceRequest, Decider } from "./decider.ts";
+
+/** Two seconds. An advisor is on the path of a decision a human is waiting for; it is not worth more than that. */
+export const DEFAULT_ADVICE_TIMEOUT_MS = 2000;
+
+export interface AdviceRecord {
+  /** Which decision this advice was for, from the caller's own closed list. */
+  purpose: string;
+  decider: string;
+  /** Question keys only — never the state, and never a question's free text. */
+  questions: string[];
+  answered: boolean;
+  durationMs: number;
+  /** Present only when advice came back. */
+  answers?: Readonly<Record<string, { value: string | number | boolean; confidence?: number }>>;
+  model?: string;
+  /**
+   * Why there is no advice. `declined` means the advisor answered with nothing; `error` means it could not be
+   * reached or its response was unrecognised; `cancelled` means the CALLER went away, which is not the advisor's
+   * failure and must not read as one.
+   */
+  outcome: "answered" | "disabled" | "timeout" | "error" | "declined" | "cancelled";
+}
+
+export interface Advisor {
+  ask(purpose: string, request: AdviceRequest, signal?: AbortSignal): Promise<Advice | null>;
+}
+
+export function createAdvisor(input: {
+  decider: Decider;
+  /** Where the record goes. Injected so this layer does no I/O and governance does not import it. */
+  record: (entry: AdviceRecord) => void | Promise<void>;
+  timeoutMs?: number;
+  /** Absent or false means the null decider is used whatever `decider` says. */
+  enabled?: boolean;
+}): Advisor {
+  const timeoutMs = input.timeoutMs ?? DEFAULT_ADVICE_TIMEOUT_MS;
+  return {
+    async ask(purpose, request, signal) {
+      const started = Date.now();
+      const base = { purpose, decider: input.decider.name, questions: Object.keys(request.questions) };
+      const write = async (entry: AdviceRecord) => {
+        try {
+          await input.record(entry);
+        } catch {
+          // Recording is an observation of a decision that has already been taken. Failing to write it must not
+          // change what the caller does, for `execute-child`'s reason: an audit failure that discards the work is
+          // worse than one that is merely missing.
+        }
+      };
+      if (input.enabled !== true) {
+        await write({ ...base, decider: "none", answered: false, durationMs: 0, outcome: "disabled" });
+        return null;
+      }
+      const timer = new AbortController();
+      const cancel = setTimeout(() => timer.abort(), timeoutMs);
+      const linked = signal ? AbortSignal.any([signal, timer.signal]) : timer.signal;
+      try {
+        // RACED, not merely signalled. A decider that ignores its signal would otherwise run as long as it liked
+        // and then be recorded as a timeout — measured at fifty times the configured bound. The `Decider` contract
+        // cannot make an implementation honour an abort, so the bound is enforced on this side of it.
+        const advice = await Promise.race([
+          input.decider.decide(request, linked),
+          new Promise<null>((settle) => linked.addEventListener("abort", () => settle(null), { once: true })),
+        ]);
+        const durationMs = Date.now() - started;
+        if (!advice) {
+          await write({ ...base, answered: false, durationMs, outcome: outcomeFor(timer.signal, signal, "declined") });
+          return null;
+        }
+        await write({
+          ...base,
+          answered: true,
+          durationMs,
+          outcome: "answered",
+          answers: Object.fromEntries(
+            Object.entries(advice.answers).map(([key, answer]) => [
+              key,
+              { value: answer.value, ...(answer.confidence === undefined ? {} : { confidence: answer.confidence }) },
+            ]),
+          ),
+          ...(advice.model ? { model: advice.model } : {}),
+        });
+        return advice;
+      } catch {
+        // Including an abort. A caller asked for advice and is getting none; it proceeds exactly as it would have.
+        await write({
+          ...base,
+          answered: false,
+          durationMs: Date.now() - started,
+          outcome: outcomeFor(timer.signal, signal, "error"),
+        });
+        return null;
+      } finally {
+        clearTimeout(cancel);
+      }
+    },
+  };
+}
+
+/** The bound fired, the caller went away, or neither — three different facts a reviewer needs to tell apart. */
+function outcomeFor(
+  timer: AbortSignal,
+  caller: AbortSignal | undefined,
+  otherwise: "declined" | "error",
+): AdviceRecord["outcome"] {
+  if (timer.aborted && !caller?.aborted) return "timeout";
+  if (caller?.aborted) return "cancelled";
+  return otherwise;
+}

package/src/advisors/decider.ts

@@ -0,0 +1,64 @@
+/**
+ * An advisor is a thing that answers a typed question. It is never a thing that decides (ADR-0077).
+ *
+ * The boundary is the whole design, and it is structural rather than remembered: **no type in this layer names a
+ * `Capability` or a refusal code**, and no function in `kernel/` or `governance/` accepts an advisor's result. An
+ * advisor may select among options the caller already had, rank them, annotate them, or propose one. It can never
+ * widen an `effective` set, satisfy a gate, or stand in for a human's answer — not because it is asked not to, but
+ * because nothing on those paths can receive what it returns. `test/advisors.test.ts` forces that.
+ *
+ * Non-generative on purpose. The first advisor is a classifier that returns a typed answer with a probability, not
+ * prose, which is what makes an advisor auditable: "it chose `b` at 0.91" is a fact a reviewer can disagree with,
+ * where a paragraph of reasoning is not.
+ *
+ * Degradation is "no advice", never a guess. Every path that cannot produce an answer — disabled, missing key,
+ * timeout, transport error, a response shape we do not recognise — returns `null`, and the caller does what it
+ * would have done without an advisor at all. That is why a caller must be written to work with `nullDecider`
+ * first, and why `nullDecider` is the default.
+ */
+
+/** A question, in the three shapes the first advisor understands. */
+export type Question =
+  | { kind: "noul"; instructions: string; whenTrue: string; whenFalse: string }
+  | { kind: "choice"; instructions: string; options: Readonly<Record<string, string>> }
+  | { kind: "score"; instructions: string; levels: readonly string[] };
+
+/** One typed answer. `confidence` is absent when the transport did not report one; it is never invented. */
+export type Answer =
+  | { kind: "noul"; value: boolean; confidence?: number }
+  | { kind: "choice"; value: string; confidence?: number }
+  // `level` is the string the value indexes, so a caller never has to know which end the scale starts at.
+  | { kind: "score"; value: number; level: string; confidence?: number };
+
+export interface AdviceRequest {
+  /**
+   * What the advisor is told about the situation. **Caller-composed and deliberately not the raw task**: the task
+   * is never stored (ADR-0021) and must not be shipped to a third party either, so a caller passes the facts it
+   * chose, and the record below names them by key without their values.
+   */
+  state: Readonly<Record<string, unknown>>;
+  questions: Readonly<Record<string, Question>>;
+}
+
+export interface Advice {
+  answers: Readonly<Record<string, Answer>>;
+  /** What actually answered, as the transport reported it — a dated model id, not the one we asked for. */
+  model?: string;
+}
+
+export interface Decider {
+  /** Recorded in the ledger so a reviewer can tell which advisor a decision was taken beside. */
+  readonly name: string;
+  decide(request: AdviceRequest, signal?: AbortSignal): Promise<Advice | null>;
+}
+
+/**
+ * The default, and the one every caller must work correctly with.
+ *
+ * Not a placeholder: it is how advisors stay optional. A caller that behaves differently under `nullDecider` than
+ * under no advisor at all has made advice load-bearing, which is the one thing ADR-0077 forbids.
+ */
+export const nullDecider: Decider = {
+  name: "none",
+  decide: async () => null,
+};

package/src/advisors/jev.ts

@@ -0,0 +1,130 @@
+/**
+ * Jev, through OpenRouter's Decisions endpoint — the first advisor adapter (ADR-0077).
+ *
+ * **What is verified and what is not.** The REQUEST shape below is taken from OpenRouter's own SDK reference for
+ * `POST /api/alpha/decisions`: `{model, state, questions}`, where each question is `noul` with `criteria.true` and
+ * `criteria.false`, `choice` with a `criteria` map of option to description, or `score` with a `criteria` array of
+ * level descriptions. That much is documented. The RESPONSE is described there only as an `answers` object beside
+ * `id`, `model`, `provider` and `usage`, with probabilities and confidence mentioned but never shown, and the one
+ * public guide to this endpoint says plainly that it has not run paid calls either. **So no shape below has been
+ * confirmed against a live response.** The parser therefore accepts what the documentation describes, tolerates the
+ * obvious variants, and returns `null` for anything else rather than guessing — which is the same thing it does when
+ * the endpoint is down. A live check is the `PI_DADDY_IT_JEV=1` tier, and until somebody runs it this adapter's
+ * response handling is a reading of documentation, not a measurement.
+ *
+ * Nothing here can widen anything: it returns `Advice`, and no kernel or governance function accepts one.
+ */
+import type { Advice, AdviceRequest, Answer, Decider, Question } from "./decider.ts";
+
+export const JEV_ENDPOINT = "https://openrouter.ai/api/alpha/decisions";
+export const JEV_MODEL = "typesafe/jev-1.13";
+
+/** The wire form of one question, exactly as OpenRouter's reference documents it. */
+export function wireQuestion(question: Question): Record<string, unknown> {
+  if (question.kind === "noul")
+    return {
+      type: "noul",
+      instructions: question.instructions,
+      criteria: { true: question.whenTrue, false: question.whenFalse },
+    };
+  if (question.kind === "choice")
+    return { type: "choice", instructions: question.instructions, criteria: { ...question.options } };
+  return { type: "score", instructions: question.instructions, criteria: [...question.levels] };
+}
+
+export function wireRequest(request: AdviceRequest, model: string): Record<string, unknown> {
+  return {
+    model,
+    state: request.state,
+    questions: Object.fromEntries(Object.entries(request.questions).map(([key, q]) => [key, wireQuestion(q)])),
+  };
+}
+
+/**
+ * Read one answer out of a response, or nothing.
+ *
+ * Deliberately generous about WHERE the value and the probability sit, because the documentation names the fields
+ * without showing them, and strict about WHAT they are: a `choice` answer must be one of the options that were
+ * asked about, and a `score` must be an index into the levels. An answer outside the question's own vocabulary is
+ * not a low-confidence answer, it is a response we did not understand, and the honest reading of that is no advice.
+ */
+export function parseAnswer(question: Question, raw: unknown): Answer | undefined {
+  if (raw === null || raw === undefined) return undefined;
+  const object = typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : undefined;
+  const value = object ? (object.value ?? object.answer ?? object.choice ?? object.result) : raw;
+  const confidenceRaw = object ? (object.confidence ?? object.probability ?? object.p) : undefined;
+  const confidence = typeof confidenceRaw === "number" && Number.isFinite(confidenceRaw) ? confidenceRaw : undefined;
+  const withConfidence = <T extends Answer>(answer: T): T =>
+    (confidence === undefined ? answer : { ...answer, confidence }) as T;
+
+  if (question.kind === "noul") {
+    if (typeof value !== "boolean") return undefined;
+    return withConfidence({ kind: "noul", value });
+  }
+  if (question.kind === "choice") {
+    if (typeof value !== "string" || !Object.hasOwn(question.options, value)) return undefined;
+    return withConfidence({ kind: "choice", value });
+  }
+  // ONE reading: a score is a 0-based index into the `criteria` array that was asked about, and `level` carries the
+  // string so a caller never indexes the number itself.
+  //
+  // The first draft accepted both a 0-based and a 1-based reading "because the documentation shows neither", which
+  // pushed the ambiguity onto the caller and into the ledger: with three levels, 1 and 2 were valid under both, so
+  // `levels[value]` could read "high" where the model meant "mid". An advisor exists to remove that guess, not to
+  // relocate it. **The 0-based reading is an assumption** — it indexes the documented array form — and it is
+  // unverified for the same reason everything else about the response is: no live call has been made. If Jev is
+  // 1-based, its top level falls outside the array and the whole answer is refused as unrecognised, which is the
+  // loud failure rather than a silently shifted one, and the `PI_DADDY_IT_JEV=1` tier is what would show it.
+  if (typeof value !== "number" || !Number.isInteger(value)) return undefined;
+  if (value < 0 || value >= question.levels.length) return undefined;
+  return withConfidence({ kind: "score", value, level: question.levels[value] });
+}
+
+export function parseAdvice(request: AdviceRequest, body: unknown): Advice | null {
+  if (typeof body !== "object" || body === null) return null;
+  const envelope = body as Record<string, unknown>;
+  const raw = envelope.answers;
+  if (typeof raw !== "object" || raw === null) return null;
+  const answers: Record<string, Answer> = {};
+  for (const [key, question] of Object.entries(request.questions)) {
+    const parsed = parseAnswer(question, (raw as Record<string, unknown>)[key]);
+    // Every question or none: a caller that asked two questions and silently received one would have to guess which
+    // of its branches the missing answer belonged to, and guessing is what an advisor exists to remove.
+    if (!parsed) return null;
+    answers[key] = parsed;
+  }
+  return { answers, ...(typeof envelope.model === "string" ? { model: envelope.model } : {}) };
+}
+
+export interface JevConfig {
+  apiKey: string;
+  model?: string;
+  endpoint?: string;
+  /** Injected so the adapter is testable without a network, and so nothing here reaches for a global. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export function jevDecider(config: JevConfig): Decider {
+  return {
+    name: "jev",
+    async decide(request, signal) {
+      const send = config.fetch ?? globalThis.fetch;
+      const response = await send(config.endpoint ?? JEV_ENDPOINT, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${config.apiKey}` },
+        body: JSON.stringify(wireRequest(request, config.model ?? JEV_MODEL)),
+        ...(signal ? { signal } : {}),
+      });
+      // A dead endpoint and an advisor with nothing to say must not read alike in the ledger: the whole reason for
+      // recording the nothing-cases is that an advisor which quietly stopped answering should not look like one
+      // nobody called. Thrown, so `createAdvisor` records `error` rather than `declined`; it catches, so nothing
+      // reaches the caller but `null` either way.
+      if (!response.ok) throw new Error(`advisor endpoint returned ${response.status}`);
+      try {
+        return parseAdvice(request, await response.json());
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/src/advisors/settings.ts

@@ -0,0 +1,73 @@
+/**
+ * Whether an advisor is on, and which one (ADR-0077).
+ *
+ * **Default off, and off is the whole configuration when nothing says otherwise.** An advisor sends a description
+ * of the caller's situation to a third party, so it is not something a package turns on for somebody: it is turned
+ * on in `.pi/pi-daddy/settings.json`, the file an operator reviews and commits, beside the grant that governs
+ * everything else. Malformed configuration disables the advisor and says so, which is this project's rule for
+ * configuration everywhere: a typo must not be a way to enable something.
+ *
+ * **Not a dashboard toggle**, which is what the programme originally sketched. The dashboard is a read-only
+ * renderer in a separate process that "never affects enforcement" (ADR-0036), and a control there that wrote to
+ * settings would be the first thing it ever wrote. Turning an advisor on is an operator decision that belongs in
+ * the reviewable file; `/grants` reports what is in force. That is a deliberate departure from the roadmap line.
+ *
+ * The key is never in this file. It is read from the environment, because a settings file is committed and an API
+ * key must not be.
+ */
+
+// Spelled once, in the kernel's table, so this layer cannot drift from the list `childEnv` refuses to write.
+export { ENV_ADVISOR_KEY as ADVISOR_KEY_ENV } from "../kernel/env-names.ts";
+import { ENV_ADVISOR_KEY } from "../kernel/env-names.ts";
+
+export interface AdvisorSettings {
+  enabled: boolean;
+  /** The only decider this release knows besides the null one. */
+  decider: "none" | "jev";
+  /** Overrides the adapter's pinned model id; absent means the adapter's own default. */
+  model?: string;
+  timeoutMs?: number;
+  /** Why an advisor is off when the settings asked for one on — reported, never silently applied. */
+  refusal?: string;
+}
+
+export const ADVISOR_OFF: AdvisorSettings = Object.freeze({ enabled: false, decider: "none" });
+
+/**
+ * Read the `advisor` block of a project settings file. Absent is off; malformed is off WITH a reason.
+ *
+ * The reason matters more than it looks: an operator who wrote `"enabeld": true` and got silence would conclude the
+ * feature does not work, and an operator who wrote it and got an advisor anyway would have a third party reading
+ * their session without having successfully asked for it. Both are worse than a sentence naming the field.
+ */
+export function advisorSettingsFrom(raw: unknown, env: NodeJS.ProcessEnv = process.env): AdvisorSettings {
+  if (raw === undefined || raw === null) return ADVISOR_OFF;
+  if (typeof raw !== "object" || Array.isArray(raw))
+    return { ...ADVISOR_OFF, refusal: "settings.advisor must be an object; no advisor is enabled" };
+  const block = raw as Record<string, unknown>;
+  const unknownKeys = Object.keys(block).filter((key) => !["enabled", "decider", "model", "timeoutMs"].includes(key));
+  if (unknownKeys.length > 0)
+    return { ...ADVISOR_OFF, refusal: `settings.advisor has unknown field(s) ${unknownKeys.join(", ")}` };
+  if (block.enabled !== true) return ADVISOR_OFF;
+  if (block.decider !== "jev")
+    return { ...ADVISOR_OFF, refusal: `settings.advisor.decider must be "jev"; no advisor is enabled` };
+  if (block.model !== undefined && typeof block.model !== "string")
+    return { ...ADVISOR_OFF, refusal: "settings.advisor.model must be a string" };
+  if (
+    block.timeoutMs !== undefined &&
+    (!Number.isInteger(block.timeoutMs) || (block.timeoutMs as number) < 1 || (block.timeoutMs as number) > 30_000)
+  )
+    return { ...ADVISOR_OFF, refusal: "settings.advisor.timeoutMs must be an integer between 1 and 30000" };
+  const key = env[ENV_ADVISOR_KEY]?.trim();
+  if (!key)
+    return {
+      ...ADVISOR_OFF,
+      refusal: `settings.advisor is enabled but ${ENV_ADVISOR_KEY} is not set; no advisor is enabled`,
+    };
+  return {
+    enabled: true,
+    decider: "jev",
+    ...(typeof block.model === "string" ? { model: block.model } : {}),
+    ...(block.timeoutMs !== undefined ? { timeoutMs: block.timeoutMs as number } : {}),
+  };
+}

package/src/executors/activity-session.ts

@@ -23,7 +23,35 @@ export interface ActivitySession {
   dispose(): Promise<void>;
 }
 
+/** The newest session file pi wrote into a directory we own, as a size:mtime marker. */
+function probeDirectory(directory: string) {
+  return async (): Promise<string | undefined> => {
+    try {
+      const { readdir, stat } = await import("node:fs/promises");
+      const names = (await readdir(directory)).filter((name) => name.endsWith(".jsonl"));
+      if (names.length === 0) return undefined;
+      const marks = await Promise.all(
+        names.map(async (name) => {
+          const s = await stat(join(directory, name));
+          return `${name}:${s.size}:${s.mtimeMs}`;
+        }),
+      );
+      return marks.sort().join("|");
+    } catch {
+      return undefined;
+    }
+  };
+}
+
 export async function activitySessionFor(planArgs: string[], executionId: string): Promise<ActivitySession> {
+  // A forked child (ADR-0078) has no `--session`, and adding one would make pi refuse the spawn outright: it
+  // rejects `--fork` beside `--session` or `--no-session`. The fork writes exactly one session into a directory
+  // that is ours, so the probe watches the directory and the argv is left exactly as planned.
+  const fork = planArgs.indexOf("--fork");
+  if (fork >= 0) {
+    const dir = planArgs[planArgs.indexOf("--session-dir") + 1];
+    return { args: planArgs, path: dir, probe: probeDirectory(dir), dispose: async () => undefined };
+  }
   const flag = planArgs.indexOf("--session");
   const probeFor = (path: string) => async () => {
     try {

package/src/executors/herdr-stage.ts

@@ -26,10 +26,22 @@ import { join } from "node:path";
  * direct executor passes the same text inline with no trouble, and a plan builder that pre-emptively wrote
  * temp files for everybody would be paying one executor's tax on both paths.
  */
-export function splitSystemPrompt(args: string[]): { args: string[]; systemPrompt?: string } {
-  const at = args.indexOf("--append-system-prompt");
-  if (at === -1 || at + 1 >= args.length) return { args };
-  return { args: [...args.slice(0, at), ...args.slice(at + 2)], systemPrompt: args[at + 1] };
+export function splitSystemPrompt(args: string[]): { args: string[]; systemPrompts: string[] } {
+  // EVERY occurrence, not the first. pi accumulates `--append-system-prompt`, and ADR-0078 added a second one for a
+  // granted context handoff — whose fence always contains newlines. Taking only the first left that fence inline,
+  // and `herdr agent start` refuses a multi-line argument, so every non-fork handoff failed on the Herdr executor
+  // AFTER the gate, the ledger record and the fan-out spend. Measured during review.
+  const kept: string[] = [];
+  const systemPrompts: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--append-system-prompt" && index + 1 < args.length) {
+      systemPrompts.push(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    kept.push(args[index]);
+  }
+  return { args: kept, systemPrompts };
 }
 
 /**
@@ -43,12 +55,18 @@ export async function stageSystemPrompt(
   args: string[],
 ): Promise<{ args: string[]; promptDir?: string; error?: string }> {
   const split = splitSystemPrompt(args);
-  if (split.systemPrompt === undefined) return { args: split.args };
+  if (split.systemPrompts.length === 0) return { args: split.args };
   try {
     const promptDir = await mkdtemp(join(tmpdir(), "grants-herdr-"));
-    const file = join(promptDir, "system-prompt.md");
-    await writeFile(file, split.systemPrompt, "utf8");
-    return { args: [...split.args, "--append-system-prompt", file], promptDir };
+    const staged: string[] = [];
+    // One file per prompt, in order: pi appends them in argv order and the definition body must still precede the
+    // context a parent chose to add to it.
+    for (const [index, prompt] of split.systemPrompts.entries()) {
+      const file = join(promptDir, `system-prompt-${index}.md`);
+      await writeFile(file, prompt, "utf8");
+      staged.push("--append-system-prompt", file);
+    }
+    return { args: [...split.args, ...staged], promptDir };
   } catch (error) {
     return { args: split.args, error: `could not stage the system prompt for herdr: ${String(error)}` };
   }

package/src/governance/ledger-v3-validation.ts

@@ -101,6 +101,7 @@ const FIELDS = {
     "humanDenied",
     "gateOutcome",
     "definitionDigest",
+    "handoff",
     "executor",
     "taskFrom",
     "taskFromExecutionId",

package/src/governance/ledger.ts

@@ -141,6 +141,19 @@ export interface GrantRecord extends LedgerEventBase {
    * it. Absent for a `tools:`-style delegation, which has no definition.
    */
   definitionDigest?: DefinitionDigest;
+  /**
+   * The context handoff this child RECEIVED (ADR-0078): the mode whose capability survived, and what crossed.
+   * Absent means nothing crossed, which is the default and the overwhelming majority of records.
+   */
+  handoff?: {
+    mode: string;
+    sections: number;
+    bytes: number;
+    truncatedBytes: number;
+    keptTurns?: number;
+    droppedTurns?: number;
+    rule?: string;
+  };
   /**
    * WHERE this child ran — ADR-0031.
    *
@@ -214,6 +227,7 @@ export function buildRecord(args: {
   humanDenied?: boolean;
   gateOutcome?: PromptOutcomeKind;
   definitionDigest?: DefinitionDigest;
+  handoff?: GrantRecord["handoff"];
   /** Where the child ran (ADR-0031). Required: the probe's answer survives nowhere else. */
   executor: ExecutorKind;
   /** The logical child whose output composed this task (ADR-0033). */
@@ -261,6 +275,7 @@ export function buildRecord(args: {
     ...(args.taskFrom ? { taskFrom: args.taskFrom } : {}),
     ...(args.taskFromExecutionId ? { taskFromExecutionId: args.taskFromExecutionId } : {}),
     ...(args.taskDigest !== undefined ? { taskDigest: args.taskDigest } : {}),
+    ...(args.handoff ? { handoff: { ...args.handoff } } : {}),
     ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
     ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
     requested: args.requested,

package/src/kernel/capabilities.ts

@@ -14,6 +14,7 @@
 
 import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
 import { WILDCARD } from "./pi-tools.ts";
+import { isContextCapability } from "./context-handoff.ts";
 import { GovernanceRefusal, refusal } from "./refusals.ts";
 
 /** The capability that authorises spawning a definition (ADR-0017). `tool:*` satisfies any of them. */
@@ -61,7 +62,7 @@ export const DELEGATE_CAPABILITY: Capability = "tool:delegate";
  *
  * The README's grammar section is the prose statement of the same list and is kept in step with it.
  */
-export const CAPABILITY_NAMESPACE_PREFIXES = ["tool:", "ext:", "skill:", "agent:", "workspace:"] as const;
+export const CAPABILITY_NAMESPACE_PREFIXES = ["tool:", "ext:", "skill:", "agent:", "workspace:", "context:"] as const;
 
 /** Accept `read` or `tool:read` or `ext:pkg/tool` and normalise to a capability id. */
 export function normaliseCapability(raw: string): Capability {
@@ -184,6 +185,9 @@ export function isSafeCapability(id: Capability): boolean {
   if (id.startsWith("workspace:")) return isSafeWorkspaceId(id.slice("workspace:".length));
   return (
     new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
+    // ADR-0078. The tail is a closed vocabulary rather than a name, so the grammar names it exactly: an id like
+    // `context:everything` is a refusal at the boundary that GENERATES grants, not an unknown capability later.
+    (id.startsWith("context:") && isContextCapability(id)) ||
     new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id)
   );
 }

package/src/kernel/catalog.ts

@@ -26,6 +26,7 @@ import { PI_BUILTIN_TOOLS, WILDCARD } from "./pi-tools.ts";
 import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
 import { loadWorkspaceRegistry, type WorkspaceRegistryFile } from "./workspace.ts";
 import { CAPABILITY_NAMESPACE_PREFIXES, isSafeWorkspaceId } from "./capabilities.ts";
+import { isContextCapability } from "./context-handoff.ts";
 import { piProjectDir } from "./project-paths.ts";
 
 export type CapabilityKind = "builtin" | "extension" | "skill" | "agentType" | "workspace";
@@ -195,10 +196,15 @@ export function unknownCapabilities(requested: Capability[], catalog: Catalog):
   // `WORKSPACE_WILDCARD` is listed with the other two because it is GRAMMAR, and `isSafeCapability` refuses
   // wildcards by design — so folding it into the namespace test below un-exempts it. Caught by the tests for
   // the previous two fixes, which is the checklist paying for itself.
+  // `context:` is exempt for the workspace reason one step further on: its vocabulary is CLOSED, so
+  // `isContextCapability` is the authority and a catalog entry could only restate it less precisely. A malformed
+  // `context:everything` is not exempted, so it still reaches the operator as an unknown capability rather than
+  // reaching a child's grant as authority over nothing (ADR-0078).
   const exempt = (c: Capability) =>
     c === WILDCARD ||
     c === AGENT_WILDCARD ||
     c === WORKSPACE_WILDCARD ||
+    isContextCapability(c) ||
     (c.startsWith("workspace:") && isSafeWorkspaceId(c.slice("workspace:".length)));
   return requested.filter((c) => !exempt(c) && !catalog.has(c)).sort();
 }

package/src/kernel/chain.ts

@@ -158,6 +158,8 @@ export interface ChainStep {
   model?: string;
   /** Requested Pi thinking level; validated by the same schema as delegate/delegate_all. */
   thinking?: string;
+  /** ADR-0078: what of the parent's session this step receives. Capped by the step's own definition, like a tool. */
+  context?: unknown;
   correlation?: import("./correlation.ts").CorrelationMetadata;
   workspace?: { workspace_id: string; access: import("./workspace.ts").WorkspaceAccess };
 }