pi-daddy 0.34.0 → 0.35.0

package/extensions/effort-advice.ts

@@ -0,0 +1,99 @@
+/**
+ * The first decision point that consults an advisor (ADR-0077, roadmap PR 8): how hard a child should think.
+ *
+ * **Why this one.** It is the shape the boundary was designed for. The options are not invented by the advisor —
+ * they are the thinking levels this session's own model reports it supports (`supportedModelEfforts`), so the
+ * advisor picks among things the caller already had, which is the entire permitted verb list. It touches no
+ * capability, no gate and no grant: the worst an advisor can do here is make a child think harder or less hard
+ * than a human would have chosen, and the ledger says it did.
+ *
+ * **Only when the caller said nothing.** An explicit `thinking` on the call is the operator's or the model's own
+ * choice and is never second-guessed; advice fills a blank, it does not overrule. With no advisor, no key, no
+ * answer, a timeout or an unrecognised response, the blank stays blank and the child is spawned exactly as it is
+ * today — which is the property that keeps advisors optional rather than load-bearing.
+ */
+import { supportedModelEfforts } from "../src/kernel/model-preflight.ts";
+import type { Advisor } from "../src/advisors/advisor.ts";
+
+/** What pi's resolved catalogue entry carries that decides which efforts exist. */
+interface ResolvedModel {
+  reasoning: boolean;
+  thinkingLevelMap?: Partial<Record<string, string | null>>;
+}
+
+export const EFFORT_PURPOSE = "child-effort";
+
+export async function adviseEffort(input: {
+  /** The session, read here rather than passed as an advisor: an argument can be severed and nothing notices. */
+  session: { advisorSession: { advisor: Advisor } };
+  /** Absent means the caller chose one; nothing is asked and nothing is recorded. */
+  requested?: string;
+  /**
+   * The model the CHILD will run on, `provider/id`, not the session's.
+   *
+   * Review measured the first version reading the parent session's model while the child was spawned on
+   * `spec.model`: the levels offered then came from a model the child would never use, and pi clamps rather than
+   * refuses, so the effect was a silently shifted effort rather than a loud failure.
+   */
+  model?: string;
+  registry: { find(provider: string, modelId: string): unknown };
+  task: string;
+  agent?: string;
+  signal?: AbortSignal;
+}): Promise<string | undefined> {
+  const advisor = input.session.advisorSession.advisor;
+  const slash = input.model === undefined ? -1 : input.model.indexOf("/");
+  if (input.requested !== undefined || slash <= 0) return input.requested;
+  const resolved = input.registry.find(input.model!.slice(0, slash), input.model!.slice(slash + 1)) as
+    ResolvedModel | undefined;
+  if (!resolved) return undefined;
+  const levels = supportedModelEfforts(resolved);
+  // One option is not a choice, and a model with no reasoning has exactly one. Asking would spend a call and a
+  // ledger line to be told the only thing that could be said.
+  if (levels.length < 2) return undefined;
+
+  const advice = await advisor.ask(
+    EFFORT_PURPOSE,
+    {
+      // The task text is what the decision is actually about, and it is the one thing this package has never
+      // stored (ADR-0021). It is sent to the advisor because an advisor cannot judge a task it cannot see, and it
+      // is NOT recorded: `createAdvisor` writes the question keys and the answer, never the state. An operator who
+      // is not willing to send task text to a third party leaves the advisor off, which is the default.
+      state: { task: input.task, ...(input.agent ? { definition: input.agent } : {}) },
+      questions: {
+        effort: {
+          kind: "choice",
+          instructions:
+            "How much reasoning effort does this task need? Choose the cheapest level that would still do it well.",
+          options: Object.fromEntries(levels.map((level) => [level, effortDescription(level)])),
+        },
+      },
+    },
+    input.signal,
+  );
+  const chosen = advice?.answers.effort;
+  // Belt and braces: `parseAnswer` already refuses a choice outside the options it was given, so this can only
+  // fire if a future decider is written that does not. An effort the model does not support would be refused by
+  // pi in the child, after the spawn, which is a worse place to find out.
+  if (!chosen || chosen.kind !== "choice" || !(levels as readonly string[]).includes(chosen.value)) return undefined;
+  return chosen.value;
+}
+
+function effortDescription(level: string): string {
+  switch (level) {
+    case "off":
+      return "No reasoning. Mechanical work: a rename, a formatting pass, reading one file back.";
+    case "minimal":
+      return "Almost none. A single obvious step with no choice in it.";
+    case "low":
+      return "A little. One decision, or a change confined to one file.";
+    case "medium":
+      return "Ordinary. Several steps, or a change that has to fit existing code.";
+    case "high":
+      return "Substantial. Design choices, or work across several files that must stay consistent.";
+    case "xhigh":
+      return "Very high. A subtle problem where the obvious approach is likely to be wrong.";
+    default:
+      return "The most this model can do. Reserve it for work that has defeated a lesser effort.";
+  }
+}

package/extensions/grants-command.ts

@@ -32,6 +32,8 @@ export interface GrantsCommandContext {
    * sentence from the one the session banner printed. Two spellings of one fact is R-28.
    */
   executor: ExecutorChoice;
+  /** ADR-0077: which advisor is in force, or why none is. Reported because an advisor sends task text out. */
+  advisor: { decider: string; refusal?: string };
   observed: boolean;
   depth: number;
   maxDepth: number;
@@ -89,6 +91,7 @@ export const grantsCommand = {
       governed,
       ownGrant,
       executor,
+      advisor,
       observed,
       depth,
       maxDepth,
@@ -354,6 +357,13 @@ export const grantsCommand = {
       // two facts about what a spawn will be sit together.
       `  executor   ${executor.disclosure}`,
       `  depth      ${depth} of max ${maxDepth}${maxDepth <= 0 ? " (spawning disabled)" : ""}`,
+      // Rule 8's loud half, which review found missing: an operator who upgraded from 0.34.0, or who mistyped the
+      // variable, saw an advisor silently absent and nothing saying why. This is also where an operator sees that
+      // task text leaves the machine, which no other surface says.
+      advisor.decider === "none"
+        ? `  advisor    off${advisor.refusal ? ` — ${advisor.refusal}` : ""}`
+        : `  advisor    ${advisor.decider} — a delegation with no thinking level sends it the task text; ` +
+          `a pruned context handoff also sends session turns`,
       `  ledger     ${ledgerPath || "(not recording — set PI_DADDY_LEDGER)"}`,
       `  approvals  ${sessionApprovals.size} this session, ${valid.size} persisted` +
         `${inheritedApprovals.size > 0 ? `, ${inheritedApprovals.size} inherited` : ""}` +

package/extensions/grants.ts

@@ -374,6 +374,10 @@ export default function (pi: ExtensionAPI) {
           depth: session.depth,
           maxDepth: session.maxDepth,
           ledgerPath: session.ledgerPath,
+          advisor: {
+            decider: session.advisorSession.deciderName,
+            ...(session.advisorSession.settings.refusal ? { refusal: session.advisorSession.settings.refusal } : {}),
+          },
           catalog: session.catalog,
           definitions: session.definitions,
           sessionApprovals: session.sessionApprovals,

package/extensions/pruning-advice.ts

@@ -0,0 +1,88 @@
+/**
+ * The second decision point: which of the parent's turns a `pruned` handoff actually carries (ADR-0077).
+ *
+ * The deterministic rule keeps the last few turns plus older ones naming the given files. That rule is honest and
+ * its recall is unmeasured — it is a proxy for "what matters here", not an answer. An advisor can judge the turns
+ * against the task the child is about to be given, which the rule cannot see.
+ *
+ * **It can only take turns away.** The candidates are exactly what `selectPrunedTurns` produced; the advisor is
+ * asked one boolean per candidate and the ids it kept are handed back. Staging then intersects those ids with the
+ * candidates again, so even a selector that invented an id, returned one from another session, or returned every
+ * id in existence cannot put a turn in front of a child that the rule did not already offer. Narrowing is the only
+ * verb available, which is what makes this advice rather than authority.
+ *
+ * With no advisor, no answer, a timeout or an unrecognised response, nothing is returned and the rule's own
+ * selection stands — the same "identical to today" property the effort decision point has.
+ */
+import { selectPrunedTurns, type ContextRequest } from "../src/kernel/context-handoff.ts";
+import type { Advisor } from "../src/advisors/advisor.ts";
+import type { Question } from "../src/advisors/decider.ts";
+
+export const PRUNING_PURPOSE = "handoff-pruning";
+
+/**
+ * How many candidates may be judged. One question per turn, and a decision a human is waiting on should not carry
+ * an unbounded number of them; beyond this the rule's own selection stands, which is the safe direction.
+ */
+export const MAX_JUDGED_TURNS = 12;
+
+/** Just enough of the parent's session for the rule; the same shape `context-staging` reduces entries to. */
+export interface ParentTurnSource {
+  getEntries(): Array<{ id: string; type: string }>;
+}
+
+export async function advisePruning(input: {
+  session: { advisorSession: { advisor: Advisor }; parentSession?: ParentTurnSource };
+  granted: ContextRequest;
+  task: string;
+  signal?: AbortSignal;
+}): Promise<string[] | undefined> {
+  if (input.granted.mode !== "pruned" || !input.session.parentSession) return undefined;
+  const all = turnsOf(input.session.parentSession);
+  const candidates = selectPrunedTurns(all, {
+    ...(input.granted.turns !== undefined ? { turns: input.granted.turns } : {}),
+    ...(input.granted.files !== undefined ? { files: input.granted.files } : {}),
+  }).kept;
+  // Nothing to narrow, or more than a bounded number to judge: the rule stands and no call is made.
+  if (candidates.length < 2 || candidates.length > MAX_JUDGED_TURNS) return undefined;
+
+  const questions: Record<string, Question> = {};
+  for (const [index, turn] of candidates.entries())
+    questions[`turn${index}`] = {
+      kind: "noul",
+      // Both bounded: the task is embedded once per candidate, so an unbounded task became a request twelve times
+      // its size, on a two-second budget and the operator's key.
+      instructions: `Would a sub-agent doing this task be helped by seeing this part of the parent's session?\n\nTASK: ${input.task.slice(0, 2000)}\n\nPART:\n${turn.text.slice(0, 2000)}`,
+      whenTrue: "It bears on the task: a decision, a constraint, a fact the task depends on.",
+      whenFalse: "It does not: unrelated work, chatter, or something the task already states.",
+    };
+
+  const advice = await input.session.advisorSession.advisor.ask(
+    PRUNING_PURPOSE,
+    // The state is empty: everything the advisor needs is already in the questions, and a question carries the
+    // task and one turn rather than the whole session. Nothing here is recorded — `createAdvisor` writes keys.
+    { state: {}, questions },
+    input.signal,
+  );
+  if (!advice) return undefined;
+  // Every candidate or none. A response missing eleven of twelve answers would otherwise read as "drop eleven",
+  // which is a narrowing nobody asked for rather than the "unrecognised response means no advice" contract.
+  if (candidates.some((_, index) => advice.answers[`turn${index}`]?.kind !== "noul")) return undefined;
+  const kept = candidates
+    .filter((_, index) => (advice.answers[`turn${index}`] as { value: boolean }).value)
+    .map((turn) => turn.id);
+  // An advisor that drops everything is answering a different question from the one that was asked; the rule's
+  // selection stands rather than handing a child a handoff with nothing in it.
+  return kept.length === 0 ? undefined : kept;
+}
+
+function turnsOf(session: ParentTurnSource): Array<{ id: string; text: string }> {
+  try {
+    return session
+      .getEntries()
+      .filter((entry) => entry.type === "message")
+      .map((entry) => ({ id: entry.id, text: JSON.stringify((entry as { message?: unknown }).message ?? entry) }));
+  } catch {
+    return [];
+  }
+}

package/extensions/run-delegation.ts

@@ -12,6 +12,8 @@
  */
 
 import { nativeDelegationContext } from "./delegation-native.ts";
+import { adviseEffort } from "./effort-advice.ts";
+import { advisePruning } from "./pruning-advice.ts";
 import { DELEGATE_SUBJECT, shouldSeekApproval } from "../src/kernel/approval.ts";
 import { planDelegation } from "../src/kernel/delegate.ts";
 import {
@@ -249,6 +251,8 @@ export async function runOneDelegation(
     agent: spec.agent,
     tools: spec.tools,
     model: spec.model ?? defaultModel,
+    // Filled below, once the refusals that doom a delegation are known: asking first shipped the task text for a
+    // child that never starts, which is the ordering this module already fixed for the approval dialog.
     thinking: spec.thinking,
     context: spec.context,
     correlation: spec.workspace
@@ -289,6 +293,28 @@ export async function runOneDelegation(
     Boolean(executorRefusal || modelRefusal),
   );
   executorRefusal ||= nativeRefusal;
+
+  // ADR-0077's first decision point, after the refusal checks for the reason above. Fills a blank from the levels
+  // the CHILD's model reports; never overrules a caller, and yields today's behaviour whenever there is no answer.
+  if (!executorRefusal && !modelRefusal)
+    request.thinking = await adviseEffort({
+      session,
+      requested: spec.thinking,
+      model: spec.model ?? defaultModel,
+      registry: ctx.modelRegistry,
+      task: spec.task,
+      agent: spec.agent,
+      signal,
+    });
+
+  const planContext = await handoffPlanContext({
+    session,
+    base: extra,
+    task: spec.task,
+    blocked: Boolean(executorRefusal || modelRefusal),
+    preview: () => planWithApprovals(session, request, extra, null, signal, preApproved).then((r) => r.plan),
+    ...(signal ? { signal } : {}),
+  });
   let preparedWorkspace: PreparedWorkspace | undefined;
   let approvalOutcome: ApprovalOutcome | undefined;
   let plan: ReturnType<typeof planDelegation>;
@@ -297,7 +323,7 @@ export async function runOneDelegation(
     // Check non-liftable refusals before taking a lease, and take the lease before asking a human. This
     // preserves both anti-race rules: a doomed spawn cannot bank approval, and a conflicting writer starts
     // no child process.
-    const preview = await planWithApprovals(session, request, extra, null, signal, preApproved);
+    const preview = await planWithApprovals(session, request, planContext, null, signal, preApproved);
     plan = preview.plan;
     if (plan.ok || shouldSeekApproval(plan.result)) {
       try {
@@ -311,7 +337,7 @@ export async function runOneDelegation(
           ledgerPath: session.ledgerPath,
         });
         request.correlation = preparedWorkspace.correlation;
-        const gated = await planWithApprovals(session, request, extra, ctx, signal, preApproved);
+        const gated = await planWithApprovals(session, request, planContext, ctx, signal, preApproved);
         plan = gated.plan;
         approvalOutcome = gated.approval;
       } catch (error) {
@@ -326,7 +352,7 @@ export async function runOneDelegation(
     const gated = await planWithApprovals(
       session,
       request,
-      extra,
+      planContext,
       executorRefusal || modelRefusal ? null : ctx,
       signal,
       preApproved,
@@ -409,3 +435,35 @@ export async function runOneDelegation(
     onProgress,
   });
 }
+
+/**
+ * The planner context for one delegation, including a `pruned` handoff narrowed by an advisor (ADR-0077).
+ *
+ * **Exported and taking its own `preview`, so the ordering is forced by a test rather than by a reviewer.** Three
+ * properties live here and each was, at some point in this change's history, true only because somebody had
+ * checked it by hand: an advisor is not asked for a delegation that is already refused; it is not asked until a
+ * plan says the `pruned` handoff actually survived the ceiling, the grant and the gate; and the ids it returns
+ * reach the planner. Reviewers measured all three by mutating the source and finding the suite still green. A
+ * function with a seam is the only version of this that a test can hold.
+ */
+export async function handoffPlanContext(input: {
+  session: Parameters<typeof advisePruning>[0]["session"];
+  base: Record<string, unknown>;
+  task: string;
+  /** A refusal is already certain, so nothing may be asked. */
+  blocked: boolean;
+  /** Plans with no human in the loop; its result decides whether an advisor is consulted at all. */
+  preview: () => Promise<{ handoff?: { mode: string } }>;
+  signal?: AbortSignal;
+}): Promise<Record<string, unknown>> {
+  if (input.blocked) return { ...input.base };
+  const plan = await input.preview();
+  if (plan.handoff?.mode !== "pruned") return { ...input.base };
+  const ids = await advisePruning({
+    session: input.session,
+    granted: plan.handoff as Parameters<typeof advisePruning>[0]["granted"],
+    task: input.task,
+    ...(input.signal ? { signal: input.signal } : {}),
+  });
+  return ids ? { ...input.base, handoffTurnIds: ids } : { ...input.base };
+}

package/extensions/session.ts

@@ -49,8 +49,10 @@ import { republishable } from "./approvals.ts";
 import { storedGrantSessionState } from "./stored-grant-session.ts";
 import { nativeSessionRootFromEnv, type NativeSessionHost } from "../src/executors/native-session-target.ts";
 import { createHandoffStager, type ParentSession } from "./context-staging.ts";
+import { createAdvisorSession, type AdvisorSession } from "./advisor-session.ts";
 import { join } from "node:path";
-import { agentDir } from "../src/kernel/project-paths.ts";
+import { readFileSync, statSync } from "node:fs";
+import { agentDir, projectSettingsPath } from "../src/kernel/project-paths.ts";
 import { ENV_ALLOW_UNRESOLVED_MODELS } from "../src/kernel/model-preflight.ts";
 import { beginExtensionLifecycle, rememberChildPublication, type ReloadLifecycle } from "./reload-environment.ts";
 import { reconcileSessionEnvironment } from "./session-environment.ts";
@@ -87,7 +89,7 @@ import {
   ENV_ACTIVITY_ROOT,
   ENV_ACTIVITY_TASK,
 } from "../src/products/activity-timeline.ts";
-import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE } from "../src/kernel/env-names.ts";
+import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE, ENV_ADVISOR } from "../src/kernel/env-names.ts";
 export { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE } from "../src/kernel/env-names.ts";
 import { adoptLegacyEnvironment } from "../src/kernel/env-names.ts";
 
@@ -157,6 +159,8 @@ export interface GrantsSession extends NativeSessionHost {
    * context handoff (ADR-0078): its file path for `fork`, its message turns for `pruned`.
    */
   parentSession?: ParentSession;
+  /** ADR-0077: the session's advisor, off unless the environment enables one. Never consulted for authority. */
+  advisorSession: AdvisorSession;
   /** Root identity keyed to ctx.sessionManager once session_start supplies it. */
   reloadLifecycle: ReloadLifecycle;
   /** Approval keys approved for this session. In memory only — this dies with the process. */
@@ -296,7 +300,18 @@ export function createGrantsSession(
   const bounds = depthConfig(environment[ENV_DEPTH], environment[ENV_MAX_DEPTH]);
   const { depth, maxDepth } = bounds;
   const emptyCatalog = makeCatalog([]);
+  // ADR-0077. The environment decides whether there is an advisor at all; the project's settings block may only
+  // narrow it. The block IS read — the first version passed `undefined` and every narrowing the release advertised
+  // was dead code reachable only from tests, which review measured: `enabled: false` turned nothing off.
+  //
+  // Read from `storeCwd` for `loadStoredGrantStateSync`'s reason: this factory runs before any hook, so `ctx.cwd`
+  // does not exist yet. Reading a workspace-writable file here is safe precisely because it can only narrow.
+  const advisorSession = createAdvisorSession({
+    block: projectAdvisorBlock(storeCwd),
+    ...(storedLedger ? { ledgerPath: storedLedger } : {}),
+  });
   const session: GrantsSession = {
+    advisorSession,
     adoptedLegacyEnv,
     governed,
     inherited,
@@ -361,12 +376,16 @@ export function createGrantsSession(
       observerExtensionPath: session.observerExtensionPath,
       childEnv: activityChildEnv(session.activity),
       // ADR-0078: composition reads, the kernel decides. Called only for a mode that survived the gate.
-      stageHandoff: (granted) =>
+      // `options` is forwarded, and its absence is why the second decision point was dead in production: a
+      // one-parameter arrow is assignable to a two-parameter type, so the ids reached here and were discarded while
+      // the advisor had already been asked. Review measured it. `test/pruning-advice.test.ts` now goes through this
+      // function rather than calling the stager directly.
+      stageHandoff: (granted, options) =>
         createHandoffStager({
           cwd: session.cwd,
           forkRoot: join(agentDir(), "context-forks"),
           ...(session.parentSession ? { parentSession: session.parentSession } : {}),
-        })(granted),
+        })(granted, options),
       catalog: await session.catalogReady,
       // R-32: where each granted skill lives, so `planSpawn` can pass `--skill` for those and only those.
       // Derived from the catalog's own `source`, so it cannot drift from what was discovered.
@@ -420,3 +439,27 @@ export function createGrantsSession(
   };
   return session;
 }
+
+/**
+ * The `advisor` block of `.pi/pi-daddy/settings.json`, or undefined.
+ *
+ * Unreadable, absent or malformed all yield undefined: this file is the reviewable record, not authority, and the
+ * only thing it can do to an advisor is turn one off. A parse failure therefore costs nothing worth reporting.
+ */
+function projectAdvisorBlock(cwd: string): unknown {
+  // Only when an advisor could exist at all. This runs in every session including every child, before any hook, and
+  // a child can never use the result because `PI_DADDY_ADVISOR` is stripped from it.
+  if (!process.env[ENV_ADVISOR]?.trim()) return undefined;
+  try {
+    const path = projectSettingsPath(cwd);
+    // Bounded and type-checked first: this is the third unbounded session-start read AGENTS.md warns about, and the
+    // only one whose path a governed child holding `tool:write` can replace with a FIFO — which would hang pi
+    // before any hook exists to report it.
+    const stats = statSync(path);
+    if (!stats.isFile() || stats.size > 1024 * 1024) return undefined;
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>).advisor : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",

package/src/advisors/decider.ts

@@ -32,9 +32,13 @@ export type Answer =
 
 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.
+   * What the advisor is told about the situation, composed by the caller.
+   *
+   * **Sent, never recorded.** The task is never STORED (ADR-0021) and that still holds — `createAdvisor` writes the
+   * question keys and the answers and never this object. But an advisor cannot judge a task it cannot see, so a
+   * caller that needs one judged does send it, and the operator's consent for that is the advisor being off by
+   * default. An earlier draft of this paragraph said the raw task "must not be shipped to a third party either",
+   * which the first decision point then did; the rule that survived review is the narrower and true one.
    */
   state: Readonly<Record<string, unknown>>;
   questions: Readonly<Record<string, Question>>;

package/src/advisors/settings.ts

@@ -1,24 +1,34 @@
 /**
  * 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.
+ * **Default off, and only the environment can turn it on.** An advisor sends a description of the caller's
+ * situation to a third party, so enabling one is `PI_DADDY_ADVISOR=jev` plus a key — both outside the workspace,
+ * both stripped from every child.
+ *
+ * 0.34.0 read the enable from `.pi/pi-daddy/settings.json` and that was wrong for the reason `grant-store.ts`
+ * states about the same file: it is writable by any child holding `tool:write`, so it is "the reviewable record of
+ * the decision, not the thing the enforcer reads". A grant lives outside the workspace precisely so a child cannot
+ * widen the next session's ceiling; an advisor switch a child could flip would make the operator's next session
+ * ship its own description to a third party, which is the same self-defeating shape. The settings block may still
+ * NARROW — a shorter timeout, or `enabled: false` to turn an advisor off for one project — and can never turn one
+ * on, choose its model, or lengthen its bound. A model is a destination rather than a narrowing, so `model` in the
+ * block is refused with a message naming `PI_DADDY_ADVISOR_MODEL`, and a timeout is clamped to the default rather
+ * than trusted. Malformed configuration disables the advisor and says so: a typo must not be a way to enable anything.
  *
  * **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.
+ * The key is never in the settings file either, because that 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";
+import { ENV_ADVISOR, ENV_ADVISOR_KEY, ENV_ADVISOR_MODEL } from "../kernel/env-names.ts";
+import { DEFAULT_ADVICE_TIMEOUT_MS } from "./advisor.ts";
+export { ENV_ADVISOR_MODEL } from "../kernel/env-names.ts";
+export { ENV_ADVISOR } from "../kernel/env-names.ts";
 
 export interface AdvisorSettings {
   enabled: boolean;
@@ -41,23 +51,49 @@ export const ADVISOR_OFF: AdvisorSettings = Object.freeze({ enabled: false, deci
  * 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))
+  // The environment decides WHETHER, before the workspace is consulted at all. A settings file that asks for an
+  // advisor nobody enabled is not a configuration error; it is simply a project that would use one if the operator
+  // turned it on, so it is reported rather than refused.
+  const requested = env[ENV_ADVISOR]?.trim();
+  if (!requested) return ADVISOR_OFF;
+  if (requested !== "jev")
+    return { ...ADVISOR_OFF, refusal: `${ENV_ADVISOR}=${requested} names no advisor this release knows` };
+
+  const block = raw === undefined || raw === null ? {} : raw;
+  if (typeof block !== "object" || Array.isArray(block))
     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));
+  const fields = block as Record<string, unknown>;
+  // `model` stays KNOWN so the refusal below can say why it is refused, rather than reporting it as a typo.
+  const unknownKeys = Object.keys(fields).filter((key) => !["enabled", "decider", "model", "timeoutMs"].includes(key));
+  // Key names are echoed back, and this file is workspace-writable: a key containing an escape sequence or a
+  // newline would otherwise forge lines in the `/grants` panel, which is a trust surface. Review measured a forged
+  // `grant tool:*` line. Sanitised and truncated before it reaches any renderer.
   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 has unknown field(s) ${unknownKeys
+        .map((key) => key.replace(/[^\w.-]/g, "?").slice(0, 40))
+        .join(", ")}`,
+    };
+  // A project may switch it OFF; it may never switch it on, which is why `true` is not read. Anything that is not
+  // exactly `true` disables: `"false"`, `0` and `null` used to leave the advisor ON with no word said, which is
+  // rule 8 inverted — the one control this file retains failing open.
+  if (fields.enabled !== undefined && fields.enabled !== true)
+    return { ...ADVISOR_OFF, refusal: "settings.advisor.enabled is not true for this project" };
+  if (fields.decider !== undefined && fields.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" };
+  // **A model is a DESTINATION, not a narrowing.** Letting this workspace-writable file choose it would let a child
+  // holding `tool:write` point the operator's next session at a generative model of its choosing, billed to the
+  // operator's key — the same self-defeating shape this release moved the enable switch to close, one step
+  // sideways. Review measured it. The model comes from the environment or not at all.
+  if ((fields as Record<string, unknown>).model !== undefined)
+    return { ...ADVISOR_OFF, refusal: `settings.advisor.model is not a narrowing; set ${ENV_ADVISOR_MODEL} instead` };
   if (
-    block.timeoutMs !== undefined &&
-    (!Number.isInteger(block.timeoutMs) || (block.timeoutMs as number) < 1 || (block.timeoutMs as number) > 30_000)
+    fields.timeoutMs !== undefined &&
+    (!Number.isInteger(fields.timeoutMs) || (fields.timeoutMs as number) < 1 || (fields.timeoutMs as number) > 30_000)
   )
     return { ...ADVISOR_OFF, refusal: "settings.advisor.timeoutMs must be an integer between 1 and 30000" };
+  const model = env[ENV_ADVISOR_MODEL]?.trim();
   const key = env[ENV_ADVISOR_KEY]?.trim();
   if (!key)
     return {
@@ -67,7 +103,11 @@ export function advisorSettingsFrom(raw: unknown, env: NodeJS.ProcessEnv = proce
   return {
     enabled: true,
     decider: "jev",
-    ...(typeof block.model === "string" ? { model: block.model } : {}),
-    ...(block.timeoutMs !== undefined ? { timeoutMs: block.timeoutMs as number } : {}),
+    ...(model ? { model } : {}),
+    // Clamped, never raised: a longer bound is not a narrowing either, and a child-writable 30s would be a stall on
+    // every delegation.
+    ...(fields.timeoutMs !== undefined
+      ? { timeoutMs: Math.min(fields.timeoutMs as number, DEFAULT_ADVICE_TIMEOUT_MS) }
+      : {}),
   };
 }

package/src/kernel/delegate-types.ts

@@ -90,7 +90,18 @@ export interface DelegationContext {
    * reads nothing. What it returns reaches the child as an appended system prompt or as fork arguments; it can
    * carry no capability, so nothing here can widen a grant.
    */
-  stageHandoff?: (granted: ContextRequest) => {
+  /**
+   * Turn ids a composition-layer selector chose for a `pruned` handoff (ADR-0077's second decision point).
+   *
+   * Composition, because choosing may mean asking an advisor and the kernel does no I/O and knows no advisor. The
+   * ids can only NARROW: staging keeps the intersection with what the deterministic rule already surfaced, so a
+   * selector cannot introduce a turn the rule did not offer, whatever it returns.
+   */
+  handoffTurnIds?: readonly string[];
+  stageHandoff?: (
+    granted: ContextRequest,
+    options?: { keepTurnIds?: readonly string[] },
+  ) => {
     contextPrompt?: string;
     forkFrom?: { sessionPath: string; sessionDir: string; sessionId: string };
     record?: Delegation["handoffRecord"];

package/src/kernel/delegate.ts

@@ -326,7 +326,9 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     handoff.mode !== "none" && result.effective.includes(contextCapability(handoff.mode)) ? handoff : undefined;
   const canSubDelegate = result.effective.includes(DELEGATE_CAPABILITY);
   // Only for a handoff that survived, so a refused mode reads no file and forks no session.
-  const staged = grantedHandoff ? ctx.stageHandoff?.(grantedHandoff) : undefined;
+  const staged = grantedHandoff
+    ? ctx.stageHandoff?.(grantedHandoff, ctx.handoffTurnIds ? { keepTurnIds: ctx.handoffTurnIds } : {})
+    : undefined;
   if (staged?.refusal)
     return denied({ ...empty, requested, result, reason: staged.refusal }, "CONTEXT_REQUEST_INVALID");
   const plan = planSpawn({

package/src/kernel/env-names.ts

@@ -48,6 +48,20 @@ export const ENV_GOVERNANCE = "PI_DADDY_GOVERNANCE";
  * inherited a paid credential its grant never named. Measured in review.
  */
 export const ENV_ADVISOR_KEY = "PI_DADDY_ADVISOR_KEY";
+/**
+ * Which advisor is in force, or absent for none (ADR-0077).
+ *
+ * **The enable lives here rather than in the project settings file, and that is a correction.** 0.34.0 read it from
+ * `.pi/pi-daddy/settings.json`, which `grant-store.ts` is explicit about: that file is writable by any child
+ * holding `tool:write`, so it is "the reviewable record of the decision, not the thing the enforcer reads". A
+ * grant is kept outside the workspace for exactly that reason, and an advisor switch needs the same treatment for a
+ * neighbouring one — a child that could flip it on would make the operator's NEXT session ship its own description
+ * to a third party. The settings file may still narrow (a model, a timeout, or `enabled: false`); it can no longer
+ * turn one on.
+ */
+export const ENV_ADVISOR = "PI_DADDY_ADVISOR";
+/** Overrides the adapter's pinned model. In the environment, never the workspace file: a model is a destination. */
+export const ENV_ADVISOR_MODEL = "PI_DADDY_ADVISOR_MODEL";
 
 /** Every variable that shapes governance. The `childEnv` hook may set none of these. */
 export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
@@ -74,6 +88,8 @@ export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
   ENV_RETAIN_NATIVE_SESSIONS,
   ENV_GOVERNANCE,
   ENV_ADVISOR_KEY,
+  ENV_ADVISOR,
+  ENV_ADVISOR_MODEL,
 ]);
 
 /**