pi-delegation-policy 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.22.0 - 2026-10-21
+
+### Added
+
+- One ephemeral configuration-change notice on the next user turn after an effective configuration
+  change, whether a `/delegate` save or an edit of the global defaults that reaches the session. It
+  lists the values that changed since the configuration the model was last shown: intensity,
+  preference, ordinary roles, Visual Design, thinking policies, Advisor entries, mode and launch, the
+  ContextShunt mode, and the reader role, toggle and answer limit. The ContextShunt enforcement
+  tuning (`limits`, `exceptionPatterns`, `delegationHintPatterns`) is left out on purpose: it changes
+  how much the shunt preserves or compacts, not the assignments the model follows. The notice exists
+  only in the requests of that turn, never in the conversation, and stays identical across their
+  retries. With both axes off by configuration it reports one line,
+  `Delegation and Advisor disabled by this policy.`, and then injects nothing; an Advisor left on but
+  unusable is not reported as disabled.
+- The reference is the configuration the model was actually shown. Changes made before a turn are
+  grouped, a reversion reports nothing, an edit that leaves effective values unchanged reports
+  nothing, and a change made while a turn is running waits for the next turn. The notice is consumed
+  when the run ends with its last recorded outcome completed, read from the final `agent_end`, so a
+  retried error that then succeeds consumes it while an error or abort reported before that point
+  leaves the change pending. Residual: an abort or a thrown error after the last successful response,
+  which the host reports through no later public event, can still consume it. Session starts,
+  reloads, forks and tree moves set the reference silently, and a prompt another extension sends with
+  `sendUserMessage` neither receives nor consumes the notice.
+
+### Compatibility and verification
+
+- No configuration, schema or dependency change. The notice uses public Pi `0.87.1` events,
+  is converted to user text by the host like any custom message and identifies itself as an extension
+  notice; it is not system policy and changes no model, permission or authority. The extension writes
+  no notice text to session history or its local log. This does not limit request retention by the
+  provider or other authorized host components. The existing local JSONL log keeps its fields.
+- Covered against the registered hooks with a synthetic host: grouping and reversion, no-op saves,
+  retries, a mid-turn change, a completed turn followed by a failed continuation, error and abort, an
+  unknown run outcome, the accepted abort/throw window after a completed response, the both-off
+  notice, an extension-sent prompt, session and tree resets, global changes, the Advisor context mode,
+  and the real host conversion and payload repair. No real-provider run was performed. The synthetic
+  host encodes Pi `0.87.1`'s event order instead of exercising a host process, so a future host that
+  reordered `input` and `before_agent_start` would not be detected.
+
+## 0.21.1 - 2026-10-19
+
+### Fixed
+
+- Accept valid Advisor replies in fork context. Preflight now uses the public executor wrapper to bind the same task that the host executes, while the emitted question and strict result identity checks remain unchanged. Version 0.21.0 discarded successful fork replies because the task digests differed.
+- Explain Advisor launch failures instead of returning only `Advisor failed`. Messages distinguish missing launch prerequisites, preflight failures, timeouts, mismatched result identity, and unusable answers. If the host supplies no safely displayable cause, the message says so; raw errors, prompts, paths, and secrets are never copied into replies or the local log.
+
+### Compatibility and verification
+
+- No configuration or schema migration. Pi `0.87.1+` and the exact `pi-subagents` `0.76.1` executor requirement are unchanged. Reload after upgrading.
+- The regression is covered against a synthetic host matching the installed executor, including rejection of a genuinely mismatched digest. A real-provider fork check remains pending after installation.
+
 ## 0.21.0 - 2026-10-19
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@ general subagent runner. Only explicit tools can request reader work or Advisor
 the authorized host executor; hooks never launch children.
 
 > **Docs:** [yivas.github.io/pi-delegation-policy](https://yivas.github.io/pi-delegation-policy/).
-> Version **0.21.0** requires Pi `0.87.1` or later (`>=0.87.1`); it re-applies its marked policy block in the final provider payload.
+> Version **0.22.0** requires Pi `0.87.1` or later (`>=0.87.1`); it re-applies its marked policy block in the final provider payload.
 > Version `0.14.1` supports Pi `0.84.3` or later (`>=0.84.3`).
 >
 > Independent Advisor mode and its companion file are available from version `0.17.0`.
@@ -15,7 +15,7 @@ the authorized host executor; hooks never launch children.
 ## Install
 
 ```bash
-pi install npm:pi-delegation-policy@0.21.0
+pi install npm:pi-delegation-policy@0.22.0
 # restart Pi, or run /reload
 ```
 
@@ -33,7 +33,7 @@ to inheritance later.
 
 | Intensity      | What the guidance asks                                                                                                                                                                                                                                                                                                                                  |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `off`          | No execution-delegation guidance. An independently enabled Advisor still injects its own section; with both off nothing is injected.                                                                                                                                                                                                                    |
+| `off`          | No execution-delegation guidance. An independently enabled Advisor still injects its own section; with both off no policy block is injected.                                                                                                                                                                                                            |
 | `normal`       | Delegate substantial, separable work only when the expected benefit clearly outweighs briefing, supervision, review, and integration. Borderline work stays with the main agent.                                                                                                                                                                        |
 | `aggressive`   | Delegate suitable substantial, separable, independently checkable work by default when objective and acceptance criteria are clear.                                                                                                                                                                                                                     |
 | `orchestrator` | Delegate all transferable execution before it begins whenever an enabled capable role and an authorized launcher exist, regardless of size: small lookups, reading, detailed planning, edits, tests, writing, detailed review, and integration mechanics. Direct work needs a briefly stated exception, and final acceptance stays with the main agent. |
@@ -105,7 +105,7 @@ Local timeouts and cancellation do not cap external generation, retries or cost.
 | `off`             | Inject no Advisor guidance and keep the saved model and thinking policy.                                   |
 | `with-delegation` | Consult only while delegation is active and an Advisor is configured. Default when the key is absent.      |
 
-`D:OFF A:ON` shows consultation-only guidance; `D:OFF A:OFF` shows nothing injected. `/delegate reset`
+`D:OFF A:ON` shows consultation-only guidance; `D:OFF A:OFF` means neither axis injects a policy block. `/delegate reset`
 turns both off for the branch; `/delegate off` leaves an independently enabled Advisor active.
 
 Errors are reported per axis. Each entry validates independently: `A:ON` means all valid, `A:PART` means one of two valid
@@ -190,6 +190,49 @@ example `advisor-mode=with-delegation (global); A:OFF` and `thinking-advisor=uns
 `D:OFF`, `D:NORM`, `D:AGG`, and `D:ORCH` describe delegation; `A:OFF`, `A:ON`, `A:PART`, and `A:ERR` describe
 Advisor. None of them proves that a launch happened or that another system followed the guidance.
 
+### Configuration change notice
+
+Available from `0.22.0`. The declared Pi peer remains
+`>=0.87.1`; the notice hooks and conversion are verified against `0.87.1` with a synthetic harness,
+not a full host process or later host versions.
+
+After an effective configuration change — a `/delegate` save, or an edit of the global defaults that
+changes effective values — the next user turn carries one extension-owned notice in the request
+context. It lists the values that changed since the configuration the model was last shown:
+intensity, preference, ordinary roles, Visual Design, thinking policies, Advisor entries, mode and
+launch, the ContextShunt mode, and the reader role, toggle and answer limit. The ContextShunt
+enforcement tuning (`limits`, `exceptionPatterns`, `delegationHintPatterns`) is left out on purpose:
+it changes how much the shunt preserves or compacts, not the assignments the model follows. The
+notice is not system policy and never enters the conversation: it exists only in the requests of
+that turn, identical across their retries, and it disappears with the turn.
+
+The reference is the configuration the model was actually shown, so changes made before a turn are
+grouped, a reversion before the turn reports nothing, and an edit that leaves effective values
+unchanged reports nothing. Opening or cancelling the editor writes nothing and reports nothing. A
+change made while a turn is already running reaches the policy immediately and is reported on the
+next turn; a revision that has not been shown is never consumed by an earlier turn.
+
+Consumption happens when the run ends and its last recorded outcome is a completed response: the
+extension reads the last assistant message of the final `agent_end` and keeps the presented revision
+only when that response completed. An error the host retries and that then succeeds counts as
+completed, so the notice is consumed there. An error or an abort reported before that point leaves
+the change pending, and the next user turn reports it again. Residual: an abort or a thrown error
+after the last successful response, which the host reports through no later public event, can still
+consume the notice; no public signal separates that window.
+
+With delegation off and Advisor off by configuration, one notice says `Delegation and Advisor
+disabled by this policy.` and nothing further is injected while both stay off. An Advisor left on but
+unusable is not reported as disabled, because the configuration did not disable it. Every notice is
+scoped to this extension and revokes no other instruction, permission, or authority. Session starts,
+reloads, forks and tree navigation set the reference silently, so no notice appears at startup.
+The extension writes no notice text to session history or its local log, so compaction summaries
+and branches cannot inherit one from stored history. This does not limit the provider's or other
+authorized host components' request retention. A prompt another extension sends with
+`sendUserMessage` is not a user turn: it neither receives nor consumes the notice. The notice reports configuration, not availability: an unusable model keeps its value in the
+list and the policy block that would assign it may simply be absent, so nothing in the notice
+presents that model as usable. For new work, the notice points the model at the current valid
+assignments and thinking rules in this policy rather than earlier settings in the conversation.
+
 ## ContextShunt
 
 ContextShunt is a separate opt-in layer, off by default. `observe` records what enforcement would

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",

package/src/advisor-executor.ts

@@ -3,11 +3,16 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   AgentLaunch,
+  LAUNCH_PREFLIGHT_TIMEOUT_MS,
+  LAUNCH_TERMINAL_TIMEOUT_MS,
   type AgentLaunchDefinition,
   type AgentLaunchDependencies,
+  type AgentLaunchFailure,
   type AgentLaunchHost,
   type AgentLaunchRequest,
   type AgentLaunchResult,
+  type AgentLaunchTerminalField,
+  type AgentLaunchTerminalStatus,
 } from "./agent-launch.ts";
 import type { AdvisorContext } from "./prompt.ts";
 import type { AdvisorSetting, ThinkingLevelName } from "./types.ts";
@@ -49,6 +54,115 @@ export function advisorThinking(setting: AdvisorSetting, model: Model<Api>): Thi
   return supported.includes("high") ? "high" : supported[0]!;
 }
 
+type AdvisorFailureResult = Exclude<AgentLaunchResult<string>, { kind: "completed" }>;
+
+function terminalFieldText(field: AgentLaunchTerminalField | undefined): string {
+  switch (field) {
+    case "agent":
+      return "agent profile";
+    case "model":
+      return "model";
+    case "thinking":
+      return "thinking level";
+    case "launchContractDigest":
+      return "launch contract digest";
+    default:
+      return "terminal metadata";
+  }
+}
+
+function hostStatusText(status: AgentLaunchTerminalStatus | undefined): string {
+  switch (status) {
+    case "invalid_request":
+      return "The host rejected the launch as an invalid request. Retry once; if it repeats, check the question and the packaged Advisor profile.";
+    case "unavailable_context":
+      return "The host could not supply the requested context. Call again with brief for a fresh consultation.";
+    case "duplicate_node":
+      return "The host treated this launch as a duplicate. Retry once.";
+    case "turn_budget_exhausted":
+      return "The host ended the Advisor run at its turn limit before answering. Retry once with a narrower question.";
+    case "tool_budget_exhausted":
+      return "The host ended the Advisor run at its tool limit before answering. Retry once with a narrower question.";
+    case "structured_output_failed":
+      return "The host ended the Advisor run while collecting its structured result. Retry once; if it repeats, inspect host diagnostics and check the compatibility of the installed pi-delegation-policy and pi-subagents 0.76.1 build.";
+    case "acceptance_failed":
+      return "The host ended the Advisor run at its acceptance check. Retry once; if it repeats, inspect host diagnostics and check the compatibility of the installed pi-delegation-policy and pi-subagents 0.76.1 build.";
+    case "failed":
+      return "The host ended the Advisor run with status failed and supplied no safe detail. Retry once; if it repeats, check the installed pi-subagents version.";
+    default:
+      return "The host ended the Advisor run and supplied no safe detail. Retry once; if it repeats, check the installed pi-subagents version.";
+  }
+}
+
+function unavailableFailureText(reason: AgentLaunchFailure | undefined): string {
+  const preflightSeconds = LAUNCH_PREFLIGHT_TIMEOUT_MS / 1000;
+  switch (reason?.code) {
+    case "fork-task-normalizer-unavailable":
+      return "Fork launch is unavailable: the installed pi-subagents does not export wrapForkTask, so a fork task cannot be bound to the child. Retrying or supplying a brief will not switch this session to fresh; install the compatible pi-subagents 0.76.1 build and reload the session.";
+    case "modules-unavailable":
+      return "Advisor launch is unavailable: the pi-subagents 0.76.1 exports this extension requires were not found. Install the compatible pi-subagents 0.76.1 build, then reload the session.";
+    case "preflight-unavailable":
+      return "Advisor preflight returned no launch contract. Retry once; if it repeats, check the compatible pi-subagents 0.76.1 build and the packaged Advisor profile.";
+    case "preflight-timeout":
+      return `Advisor preflight did not finish within ${preflightSeconds} seconds. Retry once; if it repeats, check the installed pi-subagents version.`;
+    case "contract-rejected":
+      return "Advisor launch contract was rejected: preflight did not confirm the required profile, model, thinking, and tool set. Inspect host diagnostics and check the installed package versions and profile; no child was launched.";
+    case "request-start-timeout":
+      return `The host did not start the Advisor within ${preflightSeconds} seconds. Retry once; if it repeats, check the installed pi-subagents version.`;
+    case "request-emit-failed":
+      return "The host could not set up or send the Advisor launch event. Reload the session, then retry; if it repeats, check the installed extension against the compatible pi-subagents 0.76.1 build.";
+    case "host-session-missing":
+      return "Advisor unavailable: the host supplied no session identity.";
+    case "fork-not-allowed":
+      return "This launch cannot use fork context: the packaged profile does not allow it, and a brief does not change that. Check the installed package version and reload the session.";
+    case "launch-closed":
+      return "Advisor launch is closed for this session. Reload the session, then retry.";
+    case "host-terminal-status":
+      return hostStatusText(reason.status);
+    case "host-status-unrecognized":
+      return "The host ended the Advisor run with a status this extension does not recognize and supplied no safe detail. Retry once; if it repeats, check the installed pi-subagents version.";
+    default:
+      return "Advisor launch failed without a classified cause, and the host supplied no safe detail. Retry once; if it repeats, check the installed pi-subagents version.";
+  }
+}
+
+function failedFailureText(reason: AgentLaunchFailure | undefined): string {
+  switch (reason?.code) {
+    case "terminal-metadata-mismatch":
+      return `The host returned an Advisor reply whose ${terminalFieldText(reason.field)} did not match the preflight contract, so the reply was discarded. Retry once; if it repeats, report the mismatch.`;
+    case "terminal-result-invalid":
+      return "The host reported completion without a usable text answer, so the result was discarded. Retry once; if it repeats, inspect host diagnostics and check the compatibility of the extension with the installed pi-subagents 0.76.1 build.";
+    case "host-terminal-status":
+      return hostStatusText(reason.status);
+    case "host-status-unrecognized":
+      return "The host ended the Advisor run with a status this extension does not recognize and supplied no safe detail. Retry once; if it repeats, check the installed pi-subagents version.";
+    default:
+      return "The Advisor run failed and the host supplied no safe detail. Retry once; if it repeats, check the installed pi-subagents version.";
+  }
+}
+
+/**
+ * Bounded English cause for a failed Advisor launch. It renders only closed reason codes and
+ * admitted protocol metadata, so host error text, prompts, URLs, paths and secrets never reach the
+ * transcript or the local log.
+ */
+export function advisorFailureText(result: AdvisorFailureResult): string {
+  switch (result.kind) {
+    case "unavailable-context":
+      return "Fork unavailable. Call again with brief for a fresh consultation.";
+    case "busy":
+      return "Advisor busy: another consultation group is already in flight.";
+    case "cancelled":
+      return "Advisor cancelled before replying. Call again when ready.";
+    case "timed-out":
+      return `Advisor did not reply within ${LAUNCH_TERMINAL_TIMEOUT_MS / 1000} seconds. Inspect host diagnostics before retrying; cancellation does not guarantee that external generation or cost has stopped.`;
+    case "unavailable":
+      return unavailableFailureText(result.reason);
+    case "failed":
+      return failedFailureText(result.reason);
+  }
+}
+
 /**
  * One pending call per tool: an advisor group launches one child per configured advisor. The
  * independent reader may hold its own pending call, so together they can own three children.

package/src/agent-launch.ts

@@ -60,6 +60,43 @@ export type AgentLaunchJsonSchema = Readonly<Record<string, unknown>>;
 type AgentLaunchContract = Readonly<Record<string, unknown>>;
 export type AgentLaunchPreflight = (input: unknown) => Promise<unknown>;
 
+/** Terminal metadata the strict path binds; only these names may reach a consumer. */
+export type AgentLaunchTerminalField = "agent" | "model" | "thinking" | "launchContractDigest";
+/** Statuses the admitted delegation protocol can report for a terminal response. */
+export type AgentLaunchTerminalStatus =
+  | "invalid_request"
+  | "unavailable_context"
+  | "duplicate_node"
+  | "turn_budget_exhausted"
+  | "tool_budget_exhausted"
+  | "structured_output_failed"
+  | "acceptance_failed"
+  | "failed";
+export type AgentLaunchFailureCode =
+  | "launch-closed"
+  | "fork-not-allowed"
+  | "host-session-missing"
+  | "modules-unavailable"
+  | "fork-task-normalizer-unavailable"
+  | "preflight-unavailable"
+  | "preflight-timeout"
+  | "contract-rejected"
+  | "request-start-timeout"
+  | "request-emit-failed"
+  | "terminal-metadata-mismatch"
+  | "terminal-result-invalid"
+  | "host-terminal-status"
+  | "host-status-unrecognized";
+/**
+ * Facts a consumer may render for a failed launch. Closed literals only: no host payload text,
+ * prompt, URL, path or provider message ever enters this type.
+ */
+export type AgentLaunchFailure = Readonly<{
+  code: AgentLaunchFailureCode;
+  field?: AgentLaunchTerminalField;
+  status?: AgentLaunchTerminalStatus;
+}>;
+
 export type AgentLaunchModules = Readonly<{
   resolveSubagentLaunchContract: AgentLaunchPreflight;
   /**
@@ -72,16 +109,22 @@ export type AgentLaunchModules = Readonly<{
   startedEvent: string;
   responseEvent: string;
   cancelEvent: string;
+  /**
+   * The public `wrapForkTask` export from `pi-subagents/shared-types`. The executor wraps a fork
+   * task before hashing the launch binding, so the preflight must hash the same wrapped task or
+   * its digest can never match the terminal one. Absent on builds without that export.
+   */
+  normalizeForkTask?: (task: string) => string;
 }>;
 
 export type AgentLaunchResult<Value> =
   | { kind: "completed"; value: Value }
-  | { kind: "unavailable" }
-  | { kind: "unavailable-context" }
+  | { kind: "unavailable"; reason?: AgentLaunchFailure }
+  | { kind: "unavailable-context"; reason?: AgentLaunchFailure }
   | { kind: "busy" }
   | { kind: "cancelled" }
   | { kind: "timed-out" }
-  | { kind: "failed" };
+  | { kind: "failed"; reason?: AgentLaunchFailure };
 
 export type AgentLaunchResultExpectation<Request, Value> =
   | Readonly<{
@@ -192,8 +235,9 @@ export function createDefaultAgentLaunchLoader(
       loadModule("pi-subagents/preflight"),
       loadModule("pi-subagents/delegation"),
       loadModule("pi-subagents/child-tool-plan"),
+      loadForkTaskNormalizer(loadModule),
     ])
-      .then(([preflight, delegation, childToolPlan]) => {
+      .then(([preflight, delegation, childToolPlan, normalizeForkTask]) => {
         if (!isRecord(preflight) || !isRecord(delegation) || !isRecord(childToolPlan)) {
           return undefined;
         }
@@ -239,11 +283,33 @@ export function createDefaultAgentLaunchLoader(
           startedEvent,
           responseEvent,
           cancelEvent,
+          ...(normalizeForkTask ? { normalizeForkTask } : {}),
         };
       })
       .catch(() => undefined);
 }
 
+/**
+ * The public `wrapForkTask` export, loaded on its own: `pi-subagents` wraps a fork task before it
+ * hashes the launch binding, so the preflight needs the same wrapper to bind the same digest. A
+ * build without the export only loses fork launches, so its absence never disables the modules the
+ * fresh path uses.
+ */
+function loadForkTaskNormalizer(
+  loadModule: DynamicModuleLoader,
+): Promise<((task: string) => string) | undefined> {
+  return loadModule("pi-subagents/shared-types")
+    .then((module) => {
+      if (!isRecord(module) || typeof module.wrapForkTask !== "function") return undefined;
+      const wrapForkTask = module.wrapForkTask;
+      return (task: string): string => {
+        const wrapped: unknown = wrapForkTask(task);
+        return typeof wrapped === "string" ? wrapped : "";
+      };
+    })
+    .catch(() => undefined);
+}
+
 /**
  * The permission runtime entry the host added, when the public probe reports exactly one extra path
  * after the prompt runtime and that path is the pinned scoped package. Any other shape, a probe that
@@ -313,13 +379,14 @@ function createPreflightInput<Request extends AgentLaunchRequest, Value>(
   host: AgentLaunchHost,
   requestId: string,
   definition: AgentLaunchDefinition<Request, Value>,
+  task: string,
 ): Record<string, unknown> {
   return {
     agent: definition.agentName,
     cwd: host.cwd,
     parentSessionId: host.sessionId,
-    task: definition.buildTask(request),
-    context: definition.allowFork ? (request.context ?? "fresh") : "fresh",
+    task,
+    context: launchContext(request, definition),
     model: `${request.model.provider}/${request.model.id}`,
     thinking: request.model.thinking,
     availableModels: request.availableModels,
@@ -370,7 +437,7 @@ function validateLaunchContract<Request extends AgentLaunchRequest, Value>(
     const resolvedModel = modelName(request.model);
     if (
       !isLowerHexDigest(contract.launchContractDigest) ||
-      contract.context !== (definition.allowFork ? (request.context ?? "fresh") : "fresh") ||
+      contract.context !== launchContext(request, definition) ||
       // The contract used to carry `modelCandidates`, pinned here as exactly `[resolvedModel]`.
       // `pi-subagents` 0.68.0 removed it along with `fallbackModels` and every same-launch model
       // switch ("each launch uses one resolved model instead of switching models automatically"),
@@ -456,10 +523,35 @@ function validateLaunchContract<Request extends AgentLaunchRequest, Value>(
   }
 }
 
+function launchContext<Request extends AgentLaunchRequest, Value>(
+  request: Request,
+  definition: AgentLaunchDefinition<Request, Value>,
+): "fresh" | "fork" {
+  return definition.allowFork ? (request.context ?? "fresh") : "fresh";
+}
+
+/**
+ * The wrapped task the executor hashes for a fork, or `undefined` when no usable public wrapper is
+ * loaded. The request keeps the raw task: the host wraps it again on its own side.
+ */
+function preflightForkTask(
+  task: string,
+  normalizeForkTask: ((task: string) => string) | undefined,
+): string | undefined {
+  if (!normalizeForkTask) return undefined;
+  try {
+    const normalized = normalizeForkTask(task);
+    return typeof normalized === "string" && normalized.length > 0 ? normalized : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function requestPayload<Request extends AgentLaunchRequest, Value>(
   active: ActiveRun<Value>,
   request: Request,
   definition: AgentLaunchDefinition<Request, Value>,
+  task: string,
 ): Record<string, unknown> {
   return {
     requestId: active.requestId,
@@ -467,8 +559,8 @@ function requestPayload<Request extends AgentLaunchRequest, Value>(
     nodeId: active.nodeId,
     agent: definition.agentName,
     cwd: active.host.cwd,
-    task: definition.buildTask(request),
-    context: definition.allowFork ? (request.context ?? "fresh") : "fresh",
+    task,
+    context: launchContext(request, definition),
     model: `${request.model.provider}/${request.model.id}`,
     thinking: request.model.thinking,
     timeoutMs: LAUNCH_TERMINAL_TIMEOUT_MS,
@@ -523,11 +615,14 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
     signal?: AbortSignal,
   ): Promise<AgentLaunchResult<Value>> {
     if (this.closed || (request.context === "fork" && !this.definition.allowFork))
-      return Promise.resolve({ kind: "unavailable" });
+      return Promise.resolve({
+        kind: "unavailable",
+        reason: { code: this.closed ? "launch-closed" : "fork-not-allowed" },
+      });
     if (this.active) return Promise.resolve({ kind: "busy" });
     // Without a host session the preflight could not bind required extensions; launch nothing.
     if (typeof host.sessionId !== "string" || !host.sessionId.trim()) {
-      return Promise.resolve({ kind: "unavailable" });
+      return Promise.resolve({ kind: "unavailable", reason: { code: "host-session-missing" } });
     }
     return new Promise((resolveResult) => {
       const active: ActiveRun<Value> = {
@@ -556,7 +651,7 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
       };
       this.active = active;
       active.preflightTimer = this.setTimer(
-        () => active.settle({ kind: "unavailable" }),
+        () => active.settle({ kind: "unavailable", reason: { code: "preflight-timeout" } }),
         LAUNCH_PREFLIGHT_TIMEOUT_MS,
       );
       if (signal) {
@@ -609,22 +704,48 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
     }
     if (!this.isLive(active)) return;
     if (!modules) {
-      active.settle({ kind: "unavailable" });
+      active.settle({ kind: "unavailable", reason: { code: "modules-unavailable" } });
       return;
     }
     active.modules = modules;
 
+    const task = this.definition.buildTask(request);
+    let preflightTask = task;
+    if (launchContext(request, this.definition) === "fork") {
+      const normalized = preflightForkTask(task, modules.normalizeForkTask);
+      if (normalized === undefined) {
+        active.settle({
+          kind: "unavailable",
+          reason: { code: "fork-task-normalizer-unavailable" },
+        });
+        return;
+      }
+      preflightTask = normalized;
+    }
+
     let resolved: unknown;
     try {
       resolved = await modules.resolveSubagentLaunchContract(
-        createPreflightInput(request, active.host, active.requestId, this.definition),
+        createPreflightInput(
+          request,
+          active.host,
+          active.requestId,
+          this.definition,
+          preflightTask,
+        ),
       );
     } catch {
       resolved = undefined;
     }
     if (!this.isLive(active)) return;
+    // A thrown or empty preflight never described a contract; only a returned nonempty value can be
+    // rejected as a contract that failed the strict checks below.
+    if (resolved === undefined || resolved === null) {
+      active.settle({ kind: "unavailable", reason: { code: "preflight-unavailable" } });
+      return;
+    }
     if (!validateLaunchContract(resolved, request, active, this.definition, modules)) {
-      active.settle({ kind: "unavailable" });
+      active.settle({ kind: "unavailable", reason: { code: "contract-rejected" } });
       return;
     }
 
@@ -643,17 +764,17 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
       active.requestSent = true;
       this.clearPreflightTimer(active);
       active.startTimer = this.setTimer(
-        () => this.cancelActive(active, "unavailable"),
+        () => this.cancelActive(active, "unavailable", { code: "request-start-timeout" }),
         LAUNCH_PREFLIGHT_TIMEOUT_MS,
       );
       active.host.events.emit(
         modules.requestEvent,
-        requestPayload(active, request, this.definition),
+        requestPayload(active, request, this.definition, task),
       );
       if (!this.isLive(active)) return;
     } catch {
       if (!active.settled) {
-        active.settle({ kind: "unavailable" });
+        active.settle({ kind: "unavailable", reason: { code: "request-emit-failed" } });
         this.emitCancel(active);
       }
     }
@@ -687,21 +808,23 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
     );
   }
 
-  private terminalMetadataMatches(
+  private terminalMetadataMismatch(
     payload: Record<string, unknown>,
     contract: AgentLaunchContract,
     request: Request,
     requireAll: boolean,
-  ): boolean {
-    const expected = {
-      agent: this.definition.agentName,
-      model: contract.model,
-      thinking: request.model.thinking,
-      launchContractDigest: contract.launchContractDigest,
-    };
-    return Object.entries(expected).every(([key, value]) =>
-      requireAll ? payload[key] === value : !(key in payload) || payload[key] === value,
-    );
+  ): AgentLaunchTerminalField | undefined {
+    const expected: ReadonlyArray<readonly [AgentLaunchTerminalField, unknown]> = [
+      ["agent", this.definition.agentName],
+      ["model", contract.model],
+      ["thinking", request.model.thinking],
+      ["launchContractDigest", contract.launchContractDigest],
+    ];
+    for (const [field, value] of expected) {
+      if (!requireAll && !(field in payload)) continue;
+      if (payload[field] !== value) return field;
+    }
+    return undefined;
   }
 
   private onResponse(
@@ -719,34 +842,46 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
 
     if (!active.started) {
       if (!earlyUnavailable) return;
+      const mismatch = this.terminalMetadataMismatch(payload, contract, request, false);
       active.settle(
-        this.terminalMetadataMatches(payload, contract, request, false)
+        mismatch === undefined
           ? {
               kind:
                 status === "unavailable_context" && this.definition.allowFork
                   ? "unavailable-context"
                   : "unavailable",
+              reason: { code: "host-terminal-status", status },
             }
-          : { kind: "failed" },
+          : { kind: "failed", reason: { code: "terminal-metadata-mismatch", field: mismatch } },
       );
       return;
     }
 
     if (status === "completed") {
-      if (!this.terminalMetadataMatches(payload, contract, request, true)) {
-        active.settle({ kind: "failed" });
+      const mismatch = this.terminalMetadataMismatch(payload, contract, request, true);
+      if (mismatch !== undefined) {
+        active.settle({
+          kind: "failed",
+          reason: { code: "terminal-metadata-mismatch", field: mismatch },
+        });
         return;
       }
       const completed = completedValue(payload.result, this.definition.result);
       active.settle(
-        completed.ok ? { kind: "completed", value: completed.value } : { kind: "failed" },
+        completed.ok
+          ? { kind: "completed", value: completed.value }
+          : { kind: "failed", reason: { code: "terminal-result-invalid" } },
       );
       return;
     }
 
     if (typeof status !== "string") return;
-    if (!this.terminalMetadataMatches(payload, contract, request, false)) {
-      active.settle({ kind: "failed" });
+    const mismatch = this.terminalMetadataMismatch(payload, contract, request, false);
+    if (mismatch !== undefined) {
+      active.settle({
+        kind: "failed",
+        reason: { code: "terminal-metadata-mismatch", field: mismatch },
+      });
       return;
     }
     if (status === "cancelled" || status === "interrupted") {
@@ -767,6 +902,7 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
           status === "unavailable_context" && this.definition.allowFork
             ? "unavailable-context"
             : "unavailable",
+        reason: { code: "host-terminal-status", status },
       });
       return;
     }
@@ -777,8 +913,10 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
       status === "acceptance_failed" ||
       status === "failed"
     ) {
-      active.settle({ kind: "failed" });
+      active.settle({ kind: "failed", reason: { code: "host-terminal-status", status } });
+      return;
     }
+    active.settle({ kind: "failed", reason: { code: "host-status-unrecognized" } });
   }
 
   private emitCancel(active: ActiveRun<Value>): void {
@@ -798,9 +936,10 @@ export class AgentLaunch<Request extends AgentLaunchRequest, Value> {
   private cancelActive(
     active: ActiveRun<Value>,
     result: "cancelled" | "unavailable" | "timed-out",
+    reason?: AgentLaunchFailure,
   ): void {
     if (active.settled) return;
-    active.settle({ kind: result });
+    active.settle(reason ? { kind: result, reason } : { kind: result });
     this.emitCancel(active);
   }
 

package/src/config-notice.ts

@@ -0,0 +1,211 @@
+import type { ContextWithSystemEvent } from "@earendil-works/pi-coding-agent";
+import {
+  ROLE_LABELS,
+  type AdvisorLaunch,
+  type AdvisorMode,
+  type ContextShuntMode,
+  type EffectiveDelegateState,
+  type Intensity,
+  type ModelRef,
+  type ModelRole,
+  type OrdinaryRoleSetting,
+  type Preference,
+  type ThinkingPolicy,
+} from "./types.ts";
+
+/** Custom message type of the notice. The host keeps it on the request copy only. */
+export const CONFIG_NOTICE_TYPE = "pi-delegation-policy.config-notice";
+/** The scope belongs to this policy, never to any other instruction or authority. */
+export const BOTH_OFF_LINE = "Delegation and Advisor disabled by this policy.";
+
+export type ConfigNoticeMessage = ContextWithSystemEvent["messages"][number];
+
+/**
+ * An ordinary role has three effective states, and they must stay apart: not configured is an error
+ * while delegation is on, explicitly disabled is a valid partial policy, and a model reference
+ * delegates. The effective state of Visual Design only distinguishes present from absent, so it
+ * never carries `unset`.
+ */
+type RoleText = { kind: "unset" } | { kind: "disabled" } | { kind: "model"; reference: string };
+/** `level:<level>`, `range:<min>..<max>`, or `null` when the role has no thinking policy. */
+type ThinkingText = string | null;
+
+/**
+ * Deterministic view of the effective configuration that the notice compares. Derived status stays
+ * out: model availability, credentials, diagnostics, value provenance and the Advisor context mode
+ * cannot produce a notice, and neither can the rendered policy text.
+ */
+export type NoticeProjection = {
+  intensity: Intensity;
+  preference: Preference;
+  roles: Record<ModelRole, RoleText>;
+  uiDesign: RoleText;
+  thinking: Record<ModelRole | "uiDesign", ThinkingText>;
+  advisors: Array<{ model: string; thinking: ThinkingText }>;
+  advisorMode: AdvisorMode;
+  advisorLaunch: AdvisorLaunch;
+  context: {
+    mode: ContextShuntMode;
+    readerEnabled: boolean;
+    readerRole: ModelRole;
+    answerMaxBytes: number;
+  };
+};
+
+function thinkingText(policy: ThinkingPolicy | undefined): ThinkingText {
+  if (!policy) return null;
+  return "level" in policy ? `level:${policy.level}` : `range:${policy.min}..${policy.max}`;
+}
+
+function ordinaryRoleText(setting: OrdinaryRoleSetting | undefined): RoleText {
+  if (setting === null) return { kind: "disabled" };
+  if (!setting) return { kind: "unset" };
+  return { kind: "model", reference: `${setting.provider}/${setting.model}` };
+}
+
+function optionalRoleText(setting: ModelRef | undefined): RoleText {
+  if (!setting) return { kind: "disabled" };
+  return { kind: "model", reference: `${setting.provider}/${setting.model}` };
+}
+
+export function projectNoticeConfig(effective: EffectiveDelegateState): NoticeProjection {
+  return {
+    intensity: effective.intensity,
+    preference: effective.preference,
+    roles: {
+      small: ordinaryRoleText(effective.small),
+      medium: ordinaryRoleText(effective.medium),
+      large: ordinaryRoleText(effective.large),
+    },
+    uiDesign: optionalRoleText(effective.uiDesign),
+    thinking: {
+      small: thinkingText(effective.thinking.small),
+      medium: thinkingText(effective.thinking.medium),
+      large: thinkingText(effective.thinking.large),
+      uiDesign: thinkingText(effective.thinking.uiDesign),
+    },
+    advisors: effective.advisors.map((advisor) => ({
+      model: `${advisor.provider}/${advisor.model}`,
+      thinking: thinkingText(advisor.thinking),
+    })),
+    advisorMode: effective.advisorMode,
+    advisorLaunch: effective.advisorLaunch,
+    // The configured mode keeps an intensity edit from fabricating a second change.
+    context: {
+      mode: effective.contextShunt.configuredMode,
+      readerEnabled: effective.contextShunt.readerEnabled,
+      readerRole: effective.contextShunt.readerRole,
+      answerMaxBytes: effective.contextShunt.answerMaxBytes,
+    },
+  };
+}
+
+type NoticeField = { label: string; value: string };
+
+const TEXT_ROLES: readonly (ModelRole | "uiDesign")[] = ["small", "medium", "large", "uiDesign"];
+
+function roleValue(text: RoleText): string {
+  if (text.kind === "model") return text.reference;
+  return text.kind === "disabled" ? "disabled" : "not configured";
+}
+
+function advisorModelValue(model: string | undefined): string {
+  return model ?? "none";
+}
+
+function thinkingValue(text: ThinkingText | undefined): string {
+  if (text === null || text === undefined) return "unset";
+  return text.startsWith("level:")
+    ? `fixed ${text.slice("level:".length)}`
+    : `range ${text.slice("range:".length)}`;
+}
+
+/**
+ * Fields in one canonical order. Advisor count is taken from both projections so a removed Advisor
+ * still reports its own two fields.
+ */
+function projectionFields(projection: NoticeProjection, advisorCount: number): NoticeField[] {
+  return [
+    { label: "Delegation intensity", value: projection.intensity },
+    { label: "Model preference", value: projection.preference },
+    ...TEXT_ROLES.map((role) => ({
+      label: `${ROLE_LABELS[role]} model`,
+      value: roleValue(role === "uiDesign" ? projection.uiDesign : projection.roles[role]),
+    })),
+    ...TEXT_ROLES.map((role) => ({
+      label: `${ROLE_LABELS[role]} thinking`,
+      value: thinkingValue(projection.thinking[role]),
+    })),
+    { label: "Advisor mode", value: projection.advisorMode },
+    { label: "Advisor launch", value: projection.advisorLaunch },
+    ...Array.from({ length: advisorCount }, (_, index) => {
+      const advisor = projection.advisors[index];
+      return [
+        { label: `Advisor ${index + 1} model`, value: advisorModelValue(advisor?.model) },
+        { label: `Advisor ${index + 1} thinking`, value: thinkingValue(advisor?.thinking) },
+      ];
+    }).flat(),
+    { label: "Context protection", value: projection.context.mode },
+    {
+      label: "Context reader",
+      value: projection.context.readerEnabled ? "enabled" : "disabled",
+    },
+    { label: "Context reader role", value: projection.context.readerRole },
+    {
+      label: "Context reader answer limit",
+      value: `${projection.context.answerMaxBytes} bytes`,
+    },
+  ];
+}
+
+/** One `- label: previous -> current` line per changed field, in the canonical field order. */
+export function changedValueLines(previous: NoticeProjection, current: NoticeProjection): string[] {
+  const advisorCount = Math.max(previous.advisors.length, current.advisors.length);
+  const before = projectionFields(previous, advisorCount);
+  const after = projectionFields(current, advisorCount);
+  return after.flatMap((field, index) => {
+    const previousValue = before[index]!.value;
+    return previousValue === field.value
+      ? []
+      : [`- ${field.label}: ${previousValue} -> ${field.value}`];
+  });
+}
+
+/**
+ * Lines the notice reports for one observed change. While both axes are already off a value edit
+ * changes nothing the model can act on, so only the transition into that state speaks, once.
+ */
+export function noticeLines(change: {
+  previous: NoticeProjection;
+  current: NoticeProjection;
+  previouslyOff: boolean;
+  currentlyOff: boolean;
+}): string[] {
+  const lines = changedValueLines(change.previous, change.current);
+  if (!lines.length || !change.currentlyOff) return lines;
+  return change.previouslyOff ? [] : [`- ${BOTH_OFF_LINE}`];
+}
+
+export function renderConfigNotice(lines: string[]): string {
+  return [
+    "<delegation_config_notice>",
+    "<!-- pi-delegation-policy:notice -->",
+    "This notice comes from the pi-delegation-policy extension, not from the user.",
+    "The /delegate configuration changed before this turn:",
+    ...lines,
+    "The delegation policy in the system prompt, when present, states the values in force for the present request.",
+    "For new work, follow the current valid assignments and thinking rules in this policy, not earlier settings in the conversation.",
+    "This notice only records what changed in this extension's configuration and revokes no other instruction, permission, or authority.",
+    "</delegation_config_notice>",
+  ].join("\n");
+}
+
+export function createConfigNotice(lines: string[], timestamp: number): ConfigNoticeMessage {
+  return {
+    role: "custom",
+    customType: CONFIG_NOTICE_TYPE,
+    content: renderConfigNotice(lines),
+    display: false,
+    timestamp,
+  };
+}

package/src/index.ts

@@ -1,7 +1,10 @@
 import type {
+  AgentActivityOutcome,
+  AgentEndEvent,
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,
+  InputSource,
 } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
@@ -12,8 +15,20 @@ import {
   parseSessionState,
   type GuardedAppendResult,
 } from "./config.ts";
-import { AdvisorExecutor, advisorThinking, ADVISOR_AGENT_NAME } from "./advisor-executor.ts";
+import {
+  AdvisorExecutor,
+  advisorFailureText,
+  advisorThinking,
+  ADVISOR_AGENT_NAME,
+} from "./advisor-executor.ts";
 import { AdvisorLog } from "./advisor-log.ts";
+import {
+  createConfigNotice,
+  noticeLines,
+  projectNoticeConfig,
+  type ConfigNoticeMessage,
+  type NoticeProjection,
+} from "./config-notice.ts";
 import { ContextShuntAdapter } from "./context-shunt-adapter.ts";
 import { ContextShuntExecutor } from "./context-shunt-executor.ts";
 import {
@@ -171,6 +186,28 @@ function isContextShuntDisabled(state: RuntimeState): boolean {
     state.effective.contextShunt.suspended
   );
 }
+function bothAxesOff(state: RuntimeState): boolean {
+  return state.effective.intensity === "off" && !isAdvisorEnabled(state.effective);
+}
+/** What the model has been told: the configuration shown by the last consumed notice. */
+type ConfigReference = { projection: NoticeProjection; axesOff: boolean };
+/**
+ * The host decides a turn's outcome from the last assistant message, and reports `completed` for
+ * every stop reason except an abort or an error. The same rule keeps the notice's consume rule
+ * aligned with the host's own notion of a finished turn.
+ */
+function endOutcome(messages: AgentEndEvent["messages"]): AgentActivityOutcome | undefined {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message?.role !== "assistant") continue;
+    return message.stopReason === "aborted"
+      ? "aborted"
+      : message.stopReason === "error"
+        ? "error"
+        : "completed";
+  }
+  return undefined;
+}
 function synchronizeContextShunt(shunt: ContextShuntAdapter, state: RuntimeState): void {
   if (isContextShuntDisabled(state)) shunt.clearPending();
 }
@@ -379,6 +416,58 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
       readerEpoch += 1;
       executor.cancel();
     };
+    // The notice follows the user's turns, not host turns. `input` reports where the next prompt
+    // comes from, `before_agent_start` opens one run per fresh prompt, and the comparison runs on
+    // that user turn's first request. A change made while a turn is already running updates the
+    // policy as usual and is reported on the next user turn, so no request carries a notice that
+    // contradicts the policy of the same request.
+    let configBaseline: ConfigReference | undefined;
+    let inputSource: InputSource | undefined;
+    let userTurn = 0;
+    let runToken = 0;
+    let diffedTurn: number | undefined;
+    let runOutcome: AgentActivityOutcome | undefined;
+    let presentedNotice:
+      { runToken: number; reference: ConfigReference; message: ConfigNoticeMessage } | undefined;
+    const startConfigBaseline = (state: RuntimeState): void => {
+      configBaseline = {
+        projection: projectNoticeConfig(state.effective),
+        axesOff: bothAxesOff(state),
+      };
+      userTurn = 0;
+      runToken = 0;
+      diffedTurn = undefined;
+      runOutcome = undefined;
+      presentedNotice = undefined;
+    };
+    const configNotice = (state: RuntimeState): ConfigNoticeMessage | undefined => {
+      if (diffedTurn !== userTurn) {
+        diffedTurn = userTurn;
+        presentedNotice = undefined;
+        const current: ConfigReference = {
+          projection: projectNoticeConfig(state.effective),
+          axesOff: bothAxesOff(state),
+        };
+        // Every session start and tree move sets a baseline. Only an unreadable configuration
+        // defers it to this first successful refresh, which then reports nothing.
+        if (configBaseline === undefined) configBaseline = current;
+        else {
+          const lines = noticeLines({
+            previous: configBaseline.projection,
+            current: current.projection,
+            previouslyOff: configBaseline.axesOff,
+            currentlyOff: current.axesOff,
+          });
+          if (lines.length)
+            presentedNotice = {
+              runToken,
+              reference: current,
+              message: createConfigNotice(lines, Date.now()),
+            };
+        }
+      }
+      return presentedNotice?.runToken === runToken ? presentedNotice.message : undefined;
+    };
     const rememberRuntime = (state: RuntimeState): RuntimeState => {
       if (
         readerAuthorization(latestRuntime)?.fingerprint !== readerAuthorization(state)?.fingerprint
@@ -497,9 +586,7 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
                 `${result.model} [${result.context}]:\n${
                   result.result.kind === "completed"
                     ? result.result.value
-                    : result.result.kind === "unavailable-context"
-                      ? "Fork unavailable. Call again with brief for a fresh consultation."
-                      : `Advisor ${result.result.kind}.`
+                    : advisorFailureText(result.result)
                 }`,
             )
             .join("\n\n") +
@@ -799,7 +886,7 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
     });
     pi.on("session_start", async (_event, ctx) => {
       advisorContext = undefined;
-      await refreshRuntime(ctx);
+      startConfigBaseline(await refreshRuntime(ctx));
     });
     pi.on("session_tree", async (_event, ctx) => {
       readerEpoch += 1;
@@ -807,7 +894,30 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
       advisorExecutor.rotate();
       shunt.clearPending();
       advisorContext = undefined;
-      await refreshRuntime(ctx);
+      startConfigBaseline(await refreshRuntime(ctx));
+    });
+    pi.on("input", async (event) => {
+      // The host emits this for every submitted input immediately before the prompt it belongs to,
+      // and `before_agent_start` follows only for a fresh prompt. Attribution therefore depends on
+      // that order, which Pi 0.87.1 keeps for every path that reaches it; a host that emitted the
+      // anchor first would leave the previous source in place, so the notice would follow the
+      // earlier prompt instead of skipping an extension one. No public signal can detect that
+      // change, so it stays a documented residual.
+      inputSource = event.source;
+    });
+    pi.on("before_agent_start", async () => {
+      const source = inputSource;
+      inputSource = undefined;
+      runToken += 1;
+      runOutcome = undefined;
+      // Commands, input interception and tool iterations never reach this event, and the host
+      // emits it once per fresh prompt. A prompt an extension sends is not the user's turn, so it
+      // neither receives nor consumes a notice waiting for the user.
+      if (source === "extension") {
+        diffedTurn = userTurn;
+        return;
+      }
+      userTurn += 1;
     });
     pi.on("context_with_system", async (event, ctx) => {
       const state = await refreshRuntime(ctx);
@@ -819,7 +929,7 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
         typeof systemMessage.content !== "string"
       )
         return undefined;
-
+      const notice = configNotice(state);
       const ownedPolicyBlock =
         /(?:\n\n)?<delegation_policy>\n<!-- pi-delegation-policy:owned -->[\s\S]*?<\/delegation_policy>/g;
       let replacedPolicy = false;
@@ -853,15 +963,35 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
             ...(sections && Object.keys(sections).length > 0 ? { sections } : {}),
           },
           ...event.messages.slice(1),
+          // Appended last, never inside the system block: a tool call stays adjacent to its result,
+          // the stored transcript prefix of the request is unchanged, and the host already sends
+          // user-role text after a tool result for its own custom messages.
+          ...(notice ? [notice] : []),
         ],
       };
     });
+    pi.on("agent_settled", async () => {
+      // The notice is consumed when the last outcome the run reported was a completed response:
+      // `agent_end` reports one outcome per low-level run, and this event marks the end of the whole
+      // run, emitted once in the host's `finally` after retries, compaction and queued continuations.
+      // A completed settle boundary can still be followed by another request, or by an aborted one,
+      // so the last recorded outcome decides and an unknown one never consumes. Accepted residual:
+      // an abort or a throw after the last completed response, which the host reports through no
+      // later public event, leaves that `completed` standing and consumes the notice.
+      if (runOutcome !== "completed" || presentedNotice?.runToken !== runToken) return;
+      // The revision the model received, not the live one: a change made after that request stays
+      // pending for the next turn.
+      configBaseline = presentedNotice.reference;
+    });
     pi.on("before_provider_request", async (event, ctx) => {
       const state = await refreshProviderRuntime(ctx);
       if (!state) return event.payload;
       return updateProviderPolicy(event.payload, renderPolicy(ctx, state));
     });
-    pi.on("agent_end", async () => {
+    pi.on("agent_end", async (event) => {
+      // The event carries the messages of this low-level run; a run that reports none has no
+      // outcome to trust, and an unknown outcome never consumes a notice.
+      runOutcome = endOutcome(event.messages ?? []);
       shunt.clearConsumed();
     });
     pi.on("tool_call", async (event) => {
@@ -920,6 +1050,9 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
     pi.on("session_shutdown", async (_event, ctx) => {
       readerEpoch += 1;
       latestRuntime = undefined;
+      configBaseline = undefined;
+      presentedNotice = undefined;
+      runOutcome = undefined;
       executor.close();
       advisorExecutor.close();
       await advisorLog.close();