@ian-pascoe/pi-advisor 0.4.0 → 0.5.0

package/src/advisor-observer.ts

@@ -3,8 +3,14 @@ import * as piAi from "@earendil-works/pi-ai";
 import type { Context, ImageContent } from "@earendil-works/pi-ai";
 import * as piSdk from "@earendil-works/pi-coding-agent";
 import type { AgentSession, AgentSessionRuntime } from "@earendil-works/pi-coding-agent";
-import { Type, type Static } from "typebox";
+import { Type } from "typebox";
 import { Value } from "typebox/value";
+import {
+  advisorFindingSchema,
+  type AdvisorFinding,
+  type AdvisorObserverState,
+  type AdvisorSeverity,
+} from "./advisor-contract.js";
 import type { AdvisorConfig } from "./advisor-settings.js";
 import {
   createAdvisorSession,
@@ -15,29 +21,14 @@ import {
 
 /** Delivery authority supplied by the native session owner. */
 export type AdvisorMode = "interactive" | "headless-root" | "owned-child";
-export type AdvisorSeverity = "nit" | "concern" | "blocker";
 /** Owner-supplied recreation inputs and native UI/delivery surfaces. */
 export interface AdvisorObserverOptions {
   resourceInputs?: AdvisorResourceInputs;
-  onIntervention?: (finding: {
-    severity: AdvisorSeverity;
-    message: string;
-  }) => void | Promise<void>;
+  onIntervention?: (finding: AdvisorFinding) => void | Promise<void>;
   onError?: (message: string) => void;
+  /** Called after `status` state or backlog may have changed. */
+  onStateChange?: () => void;
 }
-const severitySchema = Type.Union([
-  Type.Literal("nit"),
-  Type.Literal("concern"),
-  Type.Literal("blocker"),
-]);
-const findingSchema = Type.Object(
-  {
-    severity: severitySchema,
-    message: Type.String({ minLength: 1, maxLength: 4000 }),
-  },
-  { additionalProperties: false },
-);
-type Finding = Static<typeof findingSchema>;
 const legacyReportSchema = Type.Object(
   {
     severity: Type.Union([Type.Literal("none"), Type.Literal("concern"), Type.Literal("blocker")]),
@@ -48,7 +39,7 @@ const legacyReportSchema = Type.Object(
 const adviceMessageSchema = Type.Object({
   role: Type.Literal("custom"),
   customType: Type.Literal("pi-advisor"),
-  details: findingSchema,
+  details: advisorFindingSchema,
 });
 const pendingQueuesSchema = Type.Object({
   agent: Type.Object({ steeringQueue: Type.Object({ messages: Type.Array(Type.Unknown()) }) }),
@@ -56,7 +47,7 @@ const pendingQueuesSchema = Type.Object({
 });
 
 // oxlint-disable-next-line anti-slop/no-unknown-parameters -- SAFETY: Pi has no selective queue-removal API. Validate its native queue data and remove only exact owned finding identities, never unrelated messages or journal entries.
-function retractFindings(session: unknown, findings: ReadonlySet<Finding>): void {
+function retractFindings(session: unknown, findings: ReadonlySet<AdvisorFinding>): void {
   if (!findings.size) return;
   if (!Value.Check(pendingQueuesSchema, session))
     throw new Error("Unsupported Advisor SDK: native pending-message queues are unavailable");
@@ -86,7 +77,7 @@ interface OperationBase {
 }
 interface Review extends OperationBase {
   kind: "review";
-  findings?: Finding[];
+  findings?: AdvisorFinding[];
 }
 interface Consultation extends OperationBase {
   kind: "consultation";
@@ -114,8 +105,8 @@ const severityRank = { nit: 1, concern: 2, blocker: 3 } as const satisfies Recor
 >;
 
 /** Keep report order while replacing same-message findings with their highest severity. */
-function selectFindings(findings: readonly Finding[], limit: number): Finding[] {
-  const distinct = new Map<string, Finding>();
+function selectFindings(findings: readonly AdvisorFinding[], limit: number): AdvisorFinding[] {
+  const distinct = new Map<string, AdvisorFinding>();
   for (const finding of findings) {
     const key = normalized(finding.message);
     const previous = distinct.get(key);
@@ -168,7 +159,7 @@ export class AdvisorObserver {
   private snapshot: Context | undefined;
   private supplied: Context | undefined;
   private suppliedBoundary: ReturnType<typeof observationBoundary> | undefined;
-  private readonly pendingFindings = new Map<Finding, Review>();
+  private readonly pendingFindings = new Map<AdvisorFinding, Review>();
   private completed = 0;
   private reviewed = 0;
   private running: Promise<void> | undefined;
@@ -181,7 +172,7 @@ export class AdvisorObserver {
   private error: string | undefined;
   private closed = false;
   private disposing: Promise<void> | undefined;
-  private deferred: Finding[] = [];
+  private deferred: AdvisorFinding[] = [];
   private readonly delivered = new Map<string, number>();
   private lastConcern = -3;
   private unsafeEnding = false;
@@ -252,6 +243,7 @@ export class AdvisorObserver {
         this.unsafeEnding = true;
       this.completed++;
       this.start();
+      this.changed();
       if (this.config.catchUpThreshold !== "off")
         await this.wait(this.config.catchUpThreshold, signal);
       // Selection/branch changes may occur during that awaited barrier.
@@ -276,16 +268,17 @@ export class AdvisorObserver {
         (rate) => rate.input > 0 || rate.output > 0 || rate.cacheRead > 0 || rate.cacheWrite > 0,
       );
     const knownCost = stats && (stats.cost > 0 || (stats.tokens.total > 0 && priced));
+    const state: AdvisorObserverState = !this.config.enabled
+      ? "disabled"
+      : this.error
+        ? "paused"
+        : this.consulting
+          ? "consulting"
+          : this.running
+            ? "reviewing"
+            : "armed";
     return {
-      state: !this.config.enabled
-        ? "disabled"
-        : this.error
-          ? "paused"
-          : this.consulting
-            ? "consulting"
-            : this.running
-              ? "reviewing"
-              : "armed",
+      state,
       backlog: this.completed - this.reviewed,
       effectiveModel,
       effectiveThinkingLevel:
@@ -303,8 +296,17 @@ export class AdvisorObserver {
     };
   }
 
+  /** Status observers are UI; their failures must not disturb review work. */
+  private changed(): void {
+    try {
+      this.options.onStateChange?.();
+    } catch {
+      // A stale UI cannot be updated; `/advisor status` remains authoritative.
+    }
+  }
   private fail(message: string): void {
     this.error = message;
+    this.changed();
     try {
       this.options.onError?.(message);
     } catch (cause) {
@@ -324,7 +326,7 @@ export class AdvisorObserver {
       if (
         entry.type === "custom_message" &&
         entry.customType === "pi-advisor" &&
-        Value.Check(findingSchema, entry.details)
+        Value.Check(advisorFindingSchema, entry.details)
       ) {
         const key = normalized(entry.details.message);
         this.delivered.set(
@@ -339,7 +341,7 @@ export class AdvisorObserver {
     this.lastConcern = this.completed - (turnsSinceConcern ?? 3);
   }
   private retractInvalidFindings(): void {
-    const stale = new Set<Finding>();
+    const stale = new Set<AdvisorFinding>();
     for (const [finding, review] of this.pendingFindings) {
       if (!this.current(review)) {
         stale.add(finding);
@@ -400,8 +402,10 @@ export class AdvisorObserver {
         this.active = undefined;
         if (!this.error) this.start();
         this.scheduleCorrection();
+        this.changed();
       });
     this.running = operation;
+    this.changed();
   }
 
   private async review(review: Review): Promise<void> {
@@ -454,7 +458,7 @@ export class AdvisorObserver {
       const runtimeEpoch = operation.epoch;
       const reportSchema = Type.Object(
         {
-          findings: Type.Array(findingSchema, {
+          findings: Type.Array(advisorFindingSchema, {
             maxItems: 32,
             description: `Up to ${this.config.maxFindingsPerReview} distinct findings in priority order; use an empty array when there are none`,
           }),
@@ -651,6 +655,7 @@ export class AdvisorObserver {
     };
     this.active = consultation;
     this.consulting = true;
+    this.changed();
     let callerCancelled = false;
     const cancelFromCaller = () => {
       callerCancelled = true;
@@ -697,6 +702,7 @@ export class AdvisorObserver {
       }
       if (this.active === consultation) this.active = undefined;
       this.consulting = false;
+      this.changed();
     }
   }
 
@@ -737,7 +743,7 @@ export class AdvisorObserver {
     }
   }
 
-  private async deliver(findings: readonly Finding[], review: Review): Promise<void> {
+  private async deliver(findings: readonly AdvisorFinding[], review: Review): Promise<void> {
     const fresh = findings.filter((finding) => {
       const deliveredRank = this.delivered.get(normalized(finding.message)) ?? 0;
       return severityRank[finding.severity] > deliveredRank;
@@ -906,6 +912,7 @@ export class AdvisorObserver {
       this.runtime = undefined;
       this.closeRuntime(runtime);
     }
+    this.changed();
   }
   /** Owner cancellation invalidates private work without touching observed execution. */
   async abort(): Promise<void> {

package/src/advisor-rendering.ts

@@ -0,0 +1,368 @@
+import {
+  getMarkdownTheme,
+  keyHint,
+  type MessageRenderOptions,
+  type Theme,
+  type ThemeColor,
+} from "@earendil-works/pi-coding-agent";
+import { Box, Container, Markdown, Text, type Component } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+import {
+  advisorFindingSchema,
+  advisorSeveritySchema,
+  advisorStateSchema,
+  type AdvisorSeverity,
+  type AdvisorState,
+} from "./advisor-contract.js";
+import {
+  advisorAppliedChangeSchema,
+  advisorOptionKeys,
+  advisorOptionsSchema,
+  advisorSettingSourceSchema,
+  type AdvisorOptions,
+} from "./advisor-settings.js";
+
+/** Theme operations used by Advisor transcript and footer renderers. */
+export type AdvisorRenderTheme = Pick<Theme, "fg" | "bg" | "bold">;
+
+const severityStyle = {
+  nit: { symbol: "·", color: "muted" },
+  concern: { symbol: "▲", color: "warning" },
+  blocker: { symbol: "✖", color: "error" },
+} as const satisfies Record<AdvisorSeverity, { symbol: string; color: ThemeColor }>;
+const collapsedNitLines = 4;
+
+const nullableString = Type.Union([Type.String(), Type.Null()]);
+/** The minimum every historical status entry recorded. */
+const minimalStatusSchema = Type.Object({
+  state: advisorStateSchema,
+  error: Type.Optional(nullableString),
+});
+const statusSchema = Type.Object({
+  state: advisorStateSchema,
+  changes: Type.Optional(Type.Array(advisorAppliedChangeSchema)),
+  settings: Type.Optional(advisorOptionsSchema),
+  sources: Type.Optional(Type.Record(Type.String(), advisorSettingSourceSchema)),
+  backlog: Type.Optional(Type.Number()),
+  effectiveModel: Type.Optional(nullableString),
+  effectiveThinkingLevel: Type.Optional(nullableString),
+  usage: Type.Optional(Type.Union([Type.Object({ total: Type.Number() }), Type.Null()])),
+  cost: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
+  unavailableTools: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Null()])),
+  children: Type.Optional(
+    Type.Array(
+      Type.Object({
+        agentId: Type.String(),
+        state: Type.Optional(advisorStateSchema),
+        backlog: Type.Optional(Type.Number()),
+      }),
+    ),
+  ),
+  error: Type.Optional(nullableString),
+  lastError: Type.Optional(nullableString),
+});
+/** Data recorded in a `pi-advisor-status` entry. */
+export type AdvisorStatusEntry = Static<typeof statusSchema>;
+const stateBadge = {
+  disabled: { symbol: "○", color: "dim" },
+  private: { symbol: "○", color: "dim" },
+  armed: { symbol: "●", color: "success" },
+  reviewing: { symbol: "●", color: "accent" },
+  consulting: { symbol: "●", color: "accent" },
+  paused: { symbol: "●", color: "error" },
+} as const satisfies Record<AdvisorState, { symbol: string; color: ThemeColor }>;
+const promptPreviewWidth = 40;
+
+function expandHint(theme: Pick<Theme, "fg">): string {
+  return theme.fg("dim", `… ${keyHint("app.tools.expand", "to expand")}`);
+}
+
+/** Render at most `limit` lines of a child, then an expansion hint. */
+class Clipped implements Component {
+  constructor(
+    private readonly child: Component,
+    private readonly limit: number,
+    private readonly hint: string,
+  ) {}
+  render(width: number): string[] {
+    const lines = this.child.render(width);
+    return lines.length <= this.limit ? lines : [...lines.slice(0, this.limit), this.hint];
+  }
+  invalidate(): void {
+    this.child.invalidate();
+  }
+}
+
+/** Severity-styled, attributed Intervention; invalid details fall back to Pi's renderer. */
+export function renderAdvisorIntervention(
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Journaled custom-message details are validated by the finding schema below.
+  details: unknown,
+  options: MessageRenderOptions,
+  theme: AdvisorRenderTheme,
+  agentId?: string,
+): Component | undefined {
+  if (!Value.Check(advisorFindingSchema, details)) return undefined;
+  const style = severityStyle[details.severity];
+  const heading = joinDefined(
+    [
+      theme.fg(style.color, theme.bold(`${style.symbol} Advisor ${details.severity}`)),
+      agentId ? theme.fg("accent", `↳ ${agentId}`) : undefined,
+    ],
+    "  ",
+  );
+  const body: Component = new Markdown(details.message, 0, 0, getMarkdownTheme());
+  const container = new Container();
+  container.addChild(new Text(heading, 0, 0));
+  container.addChild(
+    details.severity === "nit" && !options.expanded
+      ? new Clipped(body, collapsedNitLines, expandHint(theme))
+      : body,
+  );
+  const box = new Box(options.outputPad, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(container);
+  return box;
+}
+
+const childFindingSchema = Type.Object({
+  agentId: Type.String(),
+  severity: advisorSeveritySchema,
+  message: Type.String(),
+});
+const childStateSchema = Type.Object({
+  agentId: Type.String(),
+  state: advisorStateSchema,
+  error: Type.Optional(Type.String()),
+});
+
+/** A Child Agent's Intervention or pause, attributed to that child. */
+export function renderAdvisorChildEntry(
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Journaled entry data is validated below; anything else renders raw.
+  data: unknown,
+  expanded: boolean,
+  theme: AdvisorRenderTheme,
+): Component {
+  if (Value.Check(childFindingSchema, data)) {
+    const finding = { severity: data.severity, message: data.message };
+    const rendered = renderAdvisorIntervention(
+      finding,
+      { expanded, outputPad: 0 },
+      theme,
+      data.agentId,
+    );
+    if (rendered) return rendered;
+  }
+  if (Value.Check(childStateSchema, data)) {
+    const line = `Advisor ↳ ${data.agentId} ${data.state}${data.error ? `: ${data.error}` : ""}`;
+    return new Text(data.error ? theme.fg("error", `✖ ${line}`) : theme.fg("dim", line), 0, 0);
+  }
+  return new Text(`Advisor for Child Agent\n${JSON.stringify(data, null, 2)}`, 0, 0);
+}
+
+const collapsedAnswerLines = 8;
+
+/** `advisor_ask` call: the question, first line only while collapsed. */
+export function renderAdvisorAskCall(
+  args: { message: string },
+  expanded: boolean,
+  theme: AdvisorRenderTheme,
+): Component {
+  const question = expanded ? args.message : (args.message.split("\n", 1)[0] ?? "");
+  return new Text(`${theme.fg("toolTitle", theme.bold("Ask Advisor"))} ${question}`, 0, 0);
+}
+
+/** `advisor_ask` result: a Markdown answer, previewed while collapsed. */
+export function renderAdvisorAskResult(
+  answer: string,
+  options: { expanded: boolean; isPartial: boolean; isError: boolean },
+  theme: AdvisorRenderTheme,
+): Component {
+  if (options.isPartial) return new Text(theme.fg("dim", "Consulting…"), 0, 0);
+  if (options.isError) return new Text(theme.fg("error", answer), 0, 0);
+  const body = new Markdown(answer, 0, 0, getMarkdownTheme());
+  return options.expanded ? body : new Clipped(body, collapsedAnswerLines, expandHint(theme));
+}
+
+function formatTokens(total: number): string {
+  if (total < 1_000) return String(total);
+  if (total < 1_000_000) return `${(total / 1_000).toFixed(1)}k`;
+  return `${(total / 1_000_000).toFixed(1)}M`;
+}
+
+function formatCost(cost: number | null | undefined): string {
+  if (cost === null || cost === undefined) return "cost unknown";
+  return `cost $${cost.toFixed(cost < 0.01 ? 4 : 2)}`;
+}
+
+/** Human-readable option value; an absent value inherits. */
+export function formatAdvisorOption(options: AdvisorOptions, key: keyof AdvisorOptions): string {
+  switch (key) {
+    case "prompt": {
+      if (options.prompt === undefined) return "inherit";
+      const first = options.prompt.split("\n", 1)[0] ?? "";
+      const preview =
+        first.length > promptPreviewWidth ? `${first.slice(0, promptPreviewWidth - 1)}…` : first;
+      return `${preview} (${options.prompt.length} chars)`;
+    }
+    case "allowedTools":
+      if (options.allowedTools === undefined) return "inherit";
+      return options.allowedTools.length ? options.allowedTools.join(", ") : "none";
+    case "reviewTimeoutMs":
+      if (options.reviewTimeoutMs === undefined) return "inherit";
+      return options.reviewTimeoutMs < 1_000
+        ? `${options.reviewTimeoutMs}ms`
+        : `${options.reviewTimeoutMs / 1_000}s`;
+    default: {
+      const value = options[key];
+      return value === undefined ? "inherit" : String(value);
+    }
+  }
+}
+
+function badge(state: AdvisorState, theme: AdvisorRenderTheme): string {
+  const style = stateBadge[state];
+  return theme.fg(style.color, `${style.symbol} ${state}`);
+}
+
+function joinDefined(parts: ReadonlyArray<string | undefined>, separator: string): string {
+  return parts.filter((part) => part !== undefined).join(separator);
+}
+
+function stateLine(entry: AdvisorStatusEntry, theme: AdvisorRenderTheme): string {
+  const inherited = entry.settings && entry.settings.model === undefined;
+  return joinDefined(
+    [
+      `${theme.bold("Advisor")} ${badge(entry.state, theme)}`,
+      entry.effectiveModel
+        ? `${entry.effectiveModel}${inherited ? theme.fg("dim", " (inherited)") : ""}`
+        : undefined,
+      entry.effectiveThinkingLevel ?? undefined,
+      entry.backlog ? `backlog ${entry.backlog}` : undefined,
+    ],
+    theme.fg("dim", " · "),
+  );
+}
+
+/** Live state line plus any error, as shown at the top of the settings menu. */
+export function advisorStatusHeadline(
+  entry: AdvisorStatusEntry,
+  theme: AdvisorRenderTheme,
+): string[] {
+  const error = entry.error ?? entry.lastError;
+  return [stateLine(entry, theme), ...(error ? [theme.fg("error", `✖ ${error}`)] : [])];
+}
+
+function summaryLines(entry: AdvisorStatusEntry, theme: AdvisorRenderTheme): string[] {
+  const lines: string[] = [];
+  for (const { scope, key, options } of entry.changes ?? []) {
+    lines.push(
+      `${theme.fg("success", "✓")} ${key} → ${formatAdvisorOption(options, key)} ${theme.fg("dim", `[${scope}]`)}`,
+    );
+  }
+  lines.push(stateLine(entry, theme));
+  const children = entry.children?.length ?? 0;
+  const activity = joinDefined(
+    [
+      entry.usage ? `tokens ${formatTokens(entry.usage.total)}` : undefined,
+      entry.usage ? formatCost(entry.cost) : undefined,
+      children ? `${children} ${children === 1 ? "child" : "children"}` : undefined,
+    ],
+    " · ",
+  );
+  if (activity) lines.push(theme.fg("muted", activity));
+  if (entry.unavailableTools?.length)
+    lines.push(theme.fg("warning", `⚠ unavailable tools: ${entry.unavailableTools.join(", ")}`));
+  const error = entry.error ?? entry.lastError;
+  if (error) lines.push(theme.fg("error", `✖ ${error}`));
+  return lines;
+}
+
+function detailLines(entry: AdvisorStatusEntry, theme: AdvisorRenderTheme): string[] {
+  const lines: string[] = [];
+  if (entry.settings) {
+    const settings = entry.settings;
+    const width = Math.max(...advisorOptionKeys.map((key) => key.length));
+    lines.push("");
+    for (const key of advisorOptionKeys) {
+      const source = entry.sources?.[key] ?? "default";
+      lines.push(
+        `  ${key.padEnd(width)}  ${formatAdvisorOption(settings, key)}  ${theme.fg(source === "default" ? "dim" : "accent", `[${source}]`)}`,
+      );
+    }
+  }
+  if (entry.children?.length) lines.push("");
+  for (const child of entry.children ?? [])
+    lines.push(
+      joinDefined(
+        [
+          `  ${theme.fg("accent", `↳ ${child.agentId}`)}`,
+          child.state ? badge(child.state, theme) : undefined,
+          child.backlog ? `backlog ${child.backlog}` : undefined,
+        ],
+        "  ",
+      ),
+    );
+  return lines;
+}
+
+/** Drop top-level fields that no longer match, so older entries keep what they can show. */
+function salvageStatus(data: Static<typeof minimalStatusSchema>): AdvisorStatusEntry {
+  // Runtime copy keeps every recorded field; only mismatching ones are removed below.
+  const candidate = structuredClone(data);
+  for (const issue of Value.Errors(statusSchema, candidate)) {
+    const field = issue.instancePath.split("/")[1];
+    if (field && field !== "state") Reflect.deleteProperty(candidate, field);
+  }
+  return Value.Check(statusSchema, candidate)
+    ? candidate
+    : { state: data.state, error: data.error ?? null };
+}
+
+/** Status snapshot: a compact summary, with every setting and child when expanded. */
+export function renderAdvisorStatus(
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Journaled entry data is validated below; older shapes keep their state and error, anything else renders raw.
+  data: unknown,
+  expanded: boolean,
+  theme: AdvisorRenderTheme,
+): Component {
+  if (!Value.Check(minimalStatusSchema, data))
+    return new Text(`Advisor\n${JSON.stringify(data, null, 2)}`, 0, 0);
+  const entry = salvageStatus(data);
+  const lines = summaryLines(entry, theme);
+  const details = detailLines(entry, theme);
+  if (expanded) lines.push(...details);
+  else if (details.length) lines.push(expandHint(theme));
+  return new Text(lines.join("\n"), 0, 0);
+}
+
+/** The live fields the footer summarizes for one watched agent. */
+export interface AdvisorActivity {
+  state: AdvisorState;
+  backlog: number;
+}
+
+function count(amount: number, what: string): string {
+  return `${amount} ${amount === 1 ? "child" : "children"} ${what}`;
+}
+
+/** Compact footer status; `undefined` clears it. Pause reasons stay in `/advisor status`. */
+export function advisorFooterText(
+  root: AdvisorActivity | undefined,
+  children: readonly AdvisorActivity[],
+  theme: Pick<Theme, "fg">,
+): string | undefined {
+  if (!root || root.state === "disabled" || root.state === "private") return undefined;
+  if (root.state === "paused") return theme.fg("error", "advisor: paused");
+  const parts: string[] = [];
+  if (root.state === "reviewing" || root.state === "consulting") {
+    parts.push(root.state);
+    if (root.backlog > 0) parts.push(`backlog ${root.backlog}`);
+  }
+  // Consultations come only from the main agent, so a child segment shows Reviews and pauses.
+  const busy = children.filter((child) => child.state === "reviewing").length;
+  const paused = children.filter((child) => child.state === "paused").length;
+  if (busy) parts.push(count(busy, "reviewing"));
+  if (paused) parts.push(theme.fg("error", count(paused, "paused")));
+  if (!parts.length) return theme.fg("dim", "advisor");
+  return theme.fg("accent", `advisor: ${parts.join(" · ")}`);
+}

package/src/advisor-settings.ts

@@ -7,7 +7,8 @@ import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 
 const positiveInteger = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
-const optionsSchema = Type.Object(
+/** Authored Advisor options; every key is optional so absent values inherit. */
+export const advisorOptionsSchema = Type.Object(
   {
     enabled: Type.Optional(Type.Boolean()),
     includeSubagents: Type.Optional(Type.Boolean()),
@@ -36,15 +37,26 @@ const optionsSchema = Type.Object(
   { additionalProperties: false },
 );
 
-export const advisorOptionKeys = Object.keys(optionsSchema.properties);
+export const advisorOptionKeys = Object.keys(advisorOptionsSchema.properties).map(advisorOptionKey);
 
 /** Authored options; absent values inherit rather than disabling their setting. */
-export type AdvisorOptions = Static<typeof optionsSchema>;
+export type AdvisorOptions = Static<typeof advisorOptionsSchema>;
 /** Fully defaulted options; absent model/thinking follows the Observed Agent. */
 export type AdvisorConfig = Required<Omit<AdvisorOptions, "model" | "thinkingLevel">> &
   Pick<AdvisorOptions, "model" | "thinkingLevel">;
+/** Native settings/session layer an authored change is written to. */
+export const advisorSettingScopeSchema = Type.Union([
+  Type.Literal("session"),
+  Type.Literal("global"),
+  Type.Literal("project"),
+]);
+export type AdvisorSettingScope = Static<typeof advisorSettingScopeSchema>;
 /** Native settings/session layer supplying an effective option. */
-export type AdvisorSettingSource = "default" | "global" | "project" | "session";
+export const advisorSettingSourceSchema = Type.Union([
+  Type.Literal("default"),
+  advisorSettingScopeSchema,
+]);
+export type AdvisorSettingSource = Static<typeof advisorSettingSourceSchema>;
 
 const defaults = {
   enabled: false,
@@ -62,7 +74,7 @@ const defaults = {
 const sessionSchema = Type.Object(
   {
     version: Type.Literal(1),
-    overrides: optionsSchema,
+    overrides: advisorOptionsSchema,
   },
   { additionalProperties: false },
 );
@@ -70,8 +82,8 @@ const sessionSchema = Type.Object(
 // oxlint-disable-next-line anti-slop/no-unknown-parameters -- SAFETY: Native settings contain arbitrary authored JSON; this schema validates it before use. SDK command tests exercise the boundary.
 export function parseAdvisorOptions(value: unknown, source: AdvisorSettingSource): AdvisorOptions {
   if (value === undefined) return {};
-  if (!Value.Check(optionsSchema, value)) {
-    const issue = Value.Errors(optionsSchema, value)[0];
+  if (!Value.Check(advisorOptionsSchema, value)) {
+    const issue = Value.Errors(advisorOptionsSchema, value)[0];
     throw new Error(
       `Invalid ${source} Advisor settings${issue?.instancePath ?? ""}: ${issue?.message ?? "invalid options"}`,
     );
@@ -81,7 +93,7 @@ export function parseAdvisorOptions(value: unknown, source: AdvisorSettingSource
 
 /** Reject inherited or unknown property names before applying an authored change. */
 export function advisorOptionKey(input: string): keyof AdvisorOptions {
-  if (!Value.Check(Type.KeyOf(optionsSchema), input))
+  if (!Value.Check(Type.KeyOf(advisorOptionsSchema), input))
     throw new Error(`Unknown Advisor option: ${input}`);
   return input;
 }
@@ -100,8 +112,15 @@ export function readAdvisorOverrides(manager: Pick<SessionManager, "getBranch">)
 export type AdvisorLayers = { global: AdvisorOptions | Error; project: AdvisorOptions | Error };
 /** A validated authored mutation, independent of its persistence scope. */
 export type AdvisorChange =
-  | { action: "set"; patch: AdvisorOptions }
+  | { action: "set"; key: keyof AdvisorOptions; patch: AdvisorOptions }
   | { action: "inherit"; key: keyof AdvisorOptions };
+/** An applied change as recorded for confirmation; `options` is empty when the key inherits. */
+export const advisorAppliedChangeSchema = Type.Object({
+  scope: advisorSettingScopeSchema,
+  key: Type.KeyOf(advisorOptionsSchema),
+  options: advisorOptionsSchema,
+});
+export type AdvisorAppliedChange = Static<typeof advisorAppliedChangeSchema>;
 
 /** Read Pi's stored layers, preserving configuration failures until corrected. */
 export function readAdvisorLayers(manager: SettingsManager): AdvisorLayers {
@@ -142,10 +161,7 @@ export function readAdvisorSettings(
   ];
   const settings: AdvisorConfig = structuredClone(defaults);
   const sources: Record<string, AdvisorSettingSource> = Object.fromEntries(
-    Object.keys(optionsSchema.properties).map((key): [string, AdvisorSettingSource] => [
-      key,
-      "default",
-    ]),
+    advisorOptionKeys.map((key): [string, AdvisorSettingSource] => [key, "default"]),
   );
   for (const [source, layer] of layers) {
     Object.assign(settings, layer);