pi-daddy 0.32.0 → 0.34.0

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/cli.ts

@@ -27,6 +27,8 @@ import {
   settingsIgnoredByGit,
 } from "./governance/init.ts";
 import { registeredWorkspaceIds } from "./kernel/workspace.ts";
+import { explainDoubledNamespace } from "./kernel/catalog.ts";
+import type { Capability } from "./kernel/resolve.ts";
 import {
   discoverSkillPackages,
   skillPackageRoots,
@@ -201,7 +203,8 @@ async function init(cwd: string, force: boolean): Promise<number> {
 }
 
 /** Say what was refused and what the fix is. Each reason has a different one. */
-function reportRefusal(pkg: SkillPackage, refusal: RefusedSkill): string {
+/** Exported so the message an operator actually reads can be tested; `init` composes it, nothing else calls it. */
+export function reportRefusal(pkg: SkillPackage, refusal: RefusedSkill): string {
   const head = `REFUSED ${pkg.name}: ${JSON.stringify(refusal.subject)}`;
   switch (refusal.reason) {
     case "unsafe-name":
@@ -209,12 +212,19 @@ function reportRefusal(pkg: SkillPackage, refusal: RefusedSkill): string {
         `${head} cannot be governed — a definition name becomes a capability id in a comma-separated ` +
         `grant, a line in a file you source, and a path. Names must match [A-Za-z0-9][A-Za-z0-9._-]*.`
       );
-    case "unsafe-capability":
+    case "unsafe-capability": {
+      // The one shape of unsafe id that has a known cause worth naming: an `allowed-tools` entry written with a
+      // capitalised namespace, which the bare-entry path prefixes a second time. `isSafeCapability` rejects the
+      // extra colon, so this refusal — not the spawn refusal and not `planInit`'s cautions — is where a doubled
+      // id actually reaches an operator. Measured: a package declaring `Tool:Read` never reaches `planInit`.
+      const doubled = refusal.detail.map((id) => explainDoubledNamespace(id as Capability)).filter(Boolean);
       return (
         `${head} declares ${refusal.detail.join(", ")}, which cannot be written into a grant file — a ` +
         `capability id is tool:/skill:/agent:<name> or ext:<pkg>/<tool>. A quote or a separator here ` +
-        `would end up in a file you are told to \`source\`.`
+        `would end up in a file you are told to \`source\`.` +
+        (doubled.length ? `\n  ${doubled.join("\n  ")}` : "")
       );
+    }
     case "wildcard":
       return (
         `${head} declares ${refusal.detail.join(", ")} — that is root authority, not a description of what ` +

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-cli.ts

@@ -7,7 +7,7 @@
  * herdr executor would mean the session imported the thing it was deciding whether to use.
  *
  * Every rule here is tested against an injected `exec`, so the suite stays fast, pi-free and herdr-free. The
- * facts the fakes reproduce were measured against real herdr 0.7.5 (`docs/probes/g16-herdr`).
+ * facts the fakes reproduce were measured against real herdr 0.7.5 (probe `g16-herdr`).
  */
 
 import { execFile } from "node:child_process";

package/src/executors/herdr-poll.ts

@@ -6,7 +6,7 @@
  * *observing* an agent, `run-herdr.ts` is about *starting and cleaning up after* one. Nothing here creates or
  * destroys anything.
  *
- * The two facts it is built on were measured against real herdr 0.7.5 (`docs/probes/g16-herdr`) and both are
+ * The two facts it is built on were measured against real herdr 0.7.5 (probe `g16-herdr`) and both are
  * counter-intuitive enough to be worth the module comment: `agent wait --until idle` matches the state the
  * agent was **already** in, and `agent read` is the one command that does **not** return a JSON envelope.
  */

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/executors/pane-reaper.ts

@@ -7,7 +7,7 @@
  * `agent_settled` (async) and at process `exit` (sync backstop).
  *
  * The gap that remains is the one this module was created for. A pi session **killed outright** runs no `exit`
- * handler, so it leaves one pane per tracked child, and `docs/probes/g16-herdr` records that an orphaned pane is
+ * handler, so it leaves one pane per tracked child, and probe `g16-herdr` records that an orphaned pane is
  * not trivially closable afterwards. R-62 was re-rated L×L → M×L when ADR-0031 made panes the default path.
  *
  * **Registered on `exit` only, deliberately — not on SIGINT or SIGTERM.** That is the part worth reading,
@@ -203,7 +203,7 @@ export function reapOpenPanes(syncExec: (args: string[]) => void = defaultSyncEx
 async function closePane(exec: HerdrExec, pane: OpenPane): Promise<boolean> {
   // **No `agent stop`.** It is not a herdr command — measured against 0.7.5, where it prints the usage banner
   // and exits 0, which `defaultExec` reports as success. Two call sites here and one in `run-herdr.ts` issued it
-  // for nothing, and `docs/probes/g16-herdr` asserted it worked from a block that was never run. Closing the tab
+  // for nothing, and probe `g16-herdr` asserted it worked from a block that was never run. Closing the tab
   // is the only kill herdr offers, and it does kill the child.
   const reply = await exec(["tab", "close", pane.tab]).catch(() => undefined);
   const closed = reply !== undefined && !parseReply(reply).error;

package/src/executors/run-herdr.ts

@@ -8,7 +8,7 @@
  * **Why go through herdr's CLI rather than the third-party `pi-herdr` extension.** That extension exposes
  * `agentArgs` and `env` as MODEL-facing tool parameters (R-30), which hands a model an argv array and the
  * environment variable the grant travels on. Here the model chooses a definition and a task; this package
- * builds the argv. Measured facts this relies on (`docs/probes/g16-herdr`):
+ * builds the argv. Measured facts this relies on (probe `g16-herdr`):
  *
  *  - `herdr agent start … -- <args>` delivers argv **verbatim**, echoed back in the reply.
  *  - `--tools` is enforced inside a pane exactly as it is for a direct spawn; `--no-tools` yields none.
@@ -76,7 +76,7 @@ export interface HerdrRunRequest {
    * The task, delivered with `herdr agent prompt` rather than as an argv element.
    *
    * This is strictly safer than the direct-spawn path, which has to defend a model-authored string from
-   * pi's argv parser by prefixing a space (`neutralisePrompt`, `docs/probes/g1-argv`). Here the task never
+   * pi's argv parser by prefixing a space (`neutralisePrompt`, probe `g1-argv`). Here the task never
    * reaches argv at all, so there is no parser in front of it.
    */
   prompt: string;
@@ -97,7 +97,7 @@ export interface HerdrRunRequest {
    * Leave the pane open after the run so a human can read or resume it.
    *
    * Default **false**: a fan-out that leaks a pane per child fills the operator's workspace, and
-   * `docs/probes/g16-herdr` records that panes are not trivially closable once orphaned.
+   * probe `g16-herdr` records that panes are not trivially closable once orphaned.
    */
   keepPane?: boolean;
   exec?: HerdrExec;
@@ -289,7 +289,7 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
    * running descendant."* **`herdr agent stop` does not exist.** Measured against herdr 0.7.5: the `agent`
    * subcommands are `list get read send-keys prompt rename focus wait attach start explain`, and `agent stop`
    * prints the usage banner and exits 0 — which `defaultExec` reports as a success, so nothing ever noticed.
-   * `docs/probes/g16-herdr/README.md` asserted it worked, in a *How to rerun* block that was never run.
+   * probe `g16-herdr` asserted it worked, in a *How to rerun* block that was never run.
    *
    * So there is exactly one kill available: closing the tab. That forces the distinction below.
    *

package/src/governance/ledger-report.ts

@@ -53,7 +53,7 @@ export interface LedgerReport {
    * **Added because the field was written and never read, which is R-51's shape exactly.** R-51 was
    * `definitionDigest`: recorded from the start, absent from every report, so the questions ADR-0018 advertised
    * needed hand-written `jq`. `executor` arrived the same way — `src/governance/ledger.ts` justifies making it *required*
-   * with "reading it back is the only reason it exists", and nothing read it back. `docs/SPEC.md` claims the
+   * with "reading it back is the only reason it exists", and nothing read it back. The README claims the
    * executor is "announced three times… per child in the ledger"; without this the third announcement was to
    * `jq` only.
    *

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

@@ -2,7 +2,7 @@
  * Append-only grant ledger.
  *
  * Exists because pi-fabric's persisted execution trace records `args: {}` — it captures *that* a child
- * ran, not *what it was authorised to do* (docs/probes/pi-fabric-eval probe 5). Without this record
+ * ran, not *what it was authorised to do* (probe `pi-fabric-eval` probe 5). Without this record
  * you cannot answer "what was this sub-agent permitted to do?" after the fact, which is the whole
  * point of a governance layer.
  *
@@ -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/governance/workspace-lease.ts

@@ -145,7 +145,7 @@ export async function acquireWorkspaceLease(input: {
    * the lock file descriptor and holds the lock in its own right — killing only `flock` leaves the
    * lock HELD by an orphan, and every later acquisition then reports WORKSPACE_WRITE_CONFLICT, which
    * is the one message an operator would use to conclude another agent is writing. Measured in
-   * `docs/probes/g35-flock-fd-inheritance` (R-99).
+   * probe `g35-flock-fd-inheritance` (R-99).
    */
   const hardKill = () => {
     // The GROUP, so this works on the readiness-timeout path too — there `helperPid` is usually still

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. */
@@ -59,9 +60,9 @@ export const DELEGATE_CAPABILITY: Capability = "tool:delegate";
  * Consolidating the sites is a separate change, and a count nobody re-derives is the defect this list exists
  * to prevent.
  *
- * `docs/SPEC.md`'s grammar section is the prose statement of the same list and is kept in step with it.
+ * 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 {
@@ -80,7 +81,7 @@ export function workspaceCapability(workspaceId: string): Capability {
  *
  * Mirrors `maySpawnDefinition` deliberately — same shape, same wildcard handling, same reason. Routing was
  * the one governance dimension that did not attenuate (R-131, measured in
- * `docs/probes/g36-workspace-attenuation`): the registry inherited into every child and nothing checked the
+ * probe `g36-workspace-attenuation`): the registry inherited into every child and nothing checked the
  * caller's authority, so a child routed to `staging` could route its grandchild to `prod`.
  *
  * `tool:*` satisfies it because governance is opt-in — an ungoverned session holds the wildcard and must
@@ -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

@@ -25,7 +25,8 @@ import { loadDefinitions, type SkillDefinition } from "./definitions.ts";
 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 { isSafeWorkspaceId } from "./capabilities.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();
 }
@@ -295,6 +301,66 @@ export function suggestForUnknown(unknown: Capability, catalog: Catalog): Capabi
   return bestDistance <= limit ? best : null;
 }
 
+/**
+ * Why an id carries two namespaces, said as the mistake that produced it.
+ *
+ * `ceilingForDefinition` prefixes a BARE entry with `tool:` and recognises an explicit namespace by its literal
+ * lower-case prefix, so `allowed-tools: Read` and `allowed-tools: tool:read` are both right. The capitalised
+ * spelling the same field invites is not: the frontmatter is copied from Claude Code, where the tool names are
+ * `Read` and `Grep`, so an author who also reaches for the namespace writes `Tool:Read` — which misses the prefix
+ * test, is lower-cased with the rest of the bare entry, and arrives as `tool:tool:read`. Every namespace has this
+ * shape (`Workspace:prod` becomes `tool:workspace:prod`), which is why the prefix is read from the one shared list
+ * rather than a second spelling of it.
+ *
+ * The messages that followed were loud and useless. A spawn refusal said "not present in this session's catalog
+ * (typo, or an uninstalled package?)" about an id nobody typed, and `suggestForUnknown` cannot rescue it either:
+ * `tool:read` is five edits from `read`, well past a threshold that never exceeds two. `pi-daddy init` refuses the
+ * whole definition earlier still, because `isSafeCapability` rejects the extra colon, and named the mangled id too.
+ *
+ * It names the mistake and does not repair it, for `ceilingForDefinition`'s own reason: a capability this package
+ * inferred rather than read is a grant nobody wrote. The author edits the file.
+ *
+ * **What the suggestion cannot recover.** The doubling happens on the bare-entry path, which lower-cases the whole
+ * entry before this function ever sees it, so `Workspace:Prod` and `Workspace:prod` both arrive as
+ * `tool:workspace:prod`. For `tool:` that loses nothing, since a pi tool name is lower-case anyway. For the other
+ * namespaces the identifier's own capitalisation is already gone, so the suggestion says so rather than implying
+ * that copying it verbatim must work. Nor is "or the bare name" offered outside `tool:`: a bare `prod` becomes
+ * `tool:prod`, which is a second unknown capability rather than a fix.
+ */
+export function explainDoubledNamespace(unknown: Capability): string | null {
+  const intended = undoubleNamespace(unknown);
+  if (intended === unknown) return null;
+  const prefix = CAPABILITY_NAMESPACE_PREFIXES.find((p) => unknown.slice("tool:".length).toLowerCase().startsWith(p))!;
+  const tail =
+    prefix === "tool:"
+      ? ` (or the bare name \`${intended.slice("tool:".length)}\`)`
+      : `, whose own capitalisation was folded when the bare entry was read, so restore it if that id has any`;
+  return (
+    `${unknown} is prefixed twice: \`allowed-tools\` adds \`tool:\` to a bare entry and recognises an ` +
+    `explicit \`${prefix}\` prefix only in lower case, so an entry already carrying a namespace was given ` +
+    `another — write \`${intended}\`${tail} in the definition`
+  );
+}
+
+/**
+ * The entry the author meant, with every extra `tool:` removed.
+ *
+ * Recursive, because `tool:tool:tool:read` is one mistake made twice and advising `tool:tool:read` would hand back
+ * an id with the same defect. The namespace is matched case-insensitively and re-emitted in lower case, so
+ * `tool:Tool:Read` — reachable on the model-chosen `tools:` path, which does not case-fold — suggests `tool:read`
+ * rather than the broken spelling it arrived in. A `tool:` name is lower-cased because pi's tool names are; any
+ * other identifier is left as it arrived, since its case may be significant and is not this function's to change.
+ */
+function undoubleNamespace(id: Capability): Capability {
+  if (!id.startsWith("tool:")) return id;
+  const inner = id.slice("tool:".length);
+  const prefix = CAPABILITY_NAMESPACE_PREFIXES.find((p) => inner.toLowerCase().startsWith(p));
+  // A bare `tool:tool:` names nothing to suggest, so it stays an ordinary unknown capability.
+  if (!prefix || inner.length === prefix.length) return id;
+  const rest = inner.slice(prefix.length);
+  return undoubleNamespace((prefix === "tool:" ? `tool:${rest.toLowerCase()}` : `${prefix}${rest}`) as Capability);
+}
+
 /**
  * Skill name -> absolute path, for `planSpawn`'s `--skill` flags (R-32).
  *

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 };
 }