pi-advisor-flow 0.9.2-dev.5 → 0.10.0

package/src/tools/consultation.ts

@@ -5,10 +5,13 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import {
   advisorEffortRef,
+  advisorFallbackModelRef,
   advisorRedactSecretsRef,
   advisorRef,
+  getAdvisorSettings,
 } from "../config/state.ts";
 import { loadConfig } from "../config/storage.ts";
+import type { AdvisorFollowUpPayload } from "../follow-up.ts";
 import { escapeRepositoryText } from "../git.ts";
 import type { GitContextLevel } from "../git.ts";
 import { collectTextStream, resolveConfiguredModel } from "../model-stream.ts";
@@ -20,6 +23,7 @@ import type { ConsultationContext } from "./consult-context.ts";
 import { parseAutomaticDecision } from "./gate-protocol.ts";
 import {
   advisorModelAccessReason,
+  fallbackSameModelAdvisorNotice,
   sameModelAdvisorDisabled,
   sameModelAdvisorNotice,
 } from "./model-access.ts";
@@ -41,6 +45,17 @@ class AdvisorNoAdviceError extends Error {
   }
 }
 
+export interface AdvisorFollowUpRequest {
+  adviceId: string;
+  payload: AdvisorFollowUpPayload;
+}
+
+export type AdvisorFollowUpCapture = (
+  adviceId: string,
+  payload: AdvisorFollowUpPayload,
+  replacesAdviceId?: string
+) => void;
+
 interface CollectAdvisorResponseOptions {
   ctx: ExtensionContext;
   currentInvocationId?: string;
@@ -53,8 +68,22 @@ interface CollectAdvisorResponseOptions {
   question?: string;
   signal?: AbortSignal;
   systemPrompt: string;
+  followUp?: AdvisorFollowUpRequest;
 }
 
+interface PreparedAdvisorRequest {
+  context?: ConsultationContext;
+  messages: Message[];
+  privacyKey: string;
+  redacted: boolean;
+  systemPrompt: string;
+}
+
+type CollectedAdvisorResponse = Omit<
+  AdvisorConsultationResult,
+  "adviceId" | "trigger"
+> & { followUpPayload: AdvisorFollowUpPayload };
+
 const fileTag = (item: { path: string; text: string }) =>
   `<file path=${JSON.stringify(item.path)}>\n${item.text}\n</file>`;
 
@@ -86,26 +115,79 @@ const advisorImageNotice = (context: ConsultationContext) => {
   return `\n\nImage disclosure: ${disclosure}. Only the images explicitly attached below have pixels available. Other image markers, image paths, and text descriptions are not visual evidence.`;
 };
 
-const collectAdvisorResponse = async (
-  options: CollectAdvisorResponseOptions
+const advisorPrivacyKey = (ctx: ExtensionContext) => {
+  const settings = getAdvisorSettings();
+  return JSON.stringify({
+    agentsMdContext: settings.agentsMdContext,
+    contextMaxChars: settings.contextMaxChars,
+    cwd: ctx.cwd,
+    gitContext: settings.gitContext,
+    gitContextMaxChars: settings.gitContextMaxChars,
+    projectTrusted: ctx.isProjectTrusted(),
+    redactSecrets: settings.redactSecrets,
+    scoutEnabled: settings.scoutEnabled,
+    toolPolicies: settings.toolPolicies,
+    toolResultMaxBytes: settings.toolResultMaxBytes,
+    toolResultMaxLines: settings.toolResultMaxLines,
+    trackedFileContent: settings.trackedFileContent,
+    untrackedContent: settings.untrackedContent,
+  });
+};
+
+export const assertAdvisorFollowUpPrivacy = (
+  payload: AdvisorFollowUpPayload,
+  ctx: ExtensionContext
 ) => {
-  const { ctx, question, signal, systemPrompt } = options;
-  loadConfig(ctx);
-  if (sameModelAdvisorDisabled(ctx)) {
-    throw new Error(sameModelAdvisorNotice);
+  if (payload.privacyKey !== advisorPrivacyKey(ctx)) {
+    throw new Error(
+      "Follow-up consultation unavailable: privacy or disclosure settings changed after the original consultation. Issue a fresh consultation."
+    );
   }
-  const accessReason = advisorModelAccessReason(ctx);
-  if (accessReason) {
-    throw new Error(accessReason);
+};
+
+const prepareFollowUp = (
+  followUp: AdvisorFollowUpRequest,
+  question: string | undefined,
+  ctx: ExtensionContext
+): PreparedAdvisorRequest => {
+  if (!question?.trim()) {
+    throw new Error(
+      "Follow-up consultations require a non-empty question. Issue a fresh consultation if no question is needed."
+    );
   }
-  const resolved = await resolveConfiguredModel(ctx, advisorRef, "Advisor");
+  assertAdvisorFollowUpPrivacy(followUp.payload, ctx);
+  const outboundQuestion =
+    advisorRedactSecretsRef || followUp.payload.redacted
+      ? redactSecrets(question)
+      : question;
+  const messages = structuredClone(followUp.payload.messages);
+  messages.push({
+    content: [
+      {
+        text: `Follow-up focus:\n${outboundQuestion}`,
+        type: "text",
+      },
+    ],
+    role: "user",
+    timestamp: Date.now(),
+  });
+  return {
+    messages,
+    privacyKey: followUp.payload.privacyKey,
+    redacted: advisorRedactSecretsRef || followUp.payload.redacted,
+    systemPrompt: followUp.payload.systemPrompt,
+  };
+};
+
+const prepareFreshRequest = async (
+  options: CollectAdvisorResponseOptions,
+  resolved: Awaited<ReturnType<typeof resolveConfiguredModel>>
+): Promise<PreparedAdvisorRequest> => {
+  const { question } = options;
   const context = await assembleConsultationContext({
     ...options,
     supportsImages: resolved.model.input.includes("image"),
   });
-
-  // Keep the original question available to local UI callers, but never send
-  // its credential-shaped values to the provider when redaction is enabled.
   const outboundQuestion =
     advisorRedactSecretsRef && question !== undefined
       ? redactSecrets(question)
@@ -139,45 +221,227 @@ const collectAdvisorResponse = async (
       timestamp: Date.now(),
     },
   ];
+  return {
+    context,
+    messages,
+    privacyKey: advisorPrivacyKey(options.ctx),
+    redacted: advisorRedactSecretsRef,
+    systemPrompt: options.systemPrompt,
+  };
+};
+
+const combinedFallbackError = (
+  primaryModel: string,
+  primaryError: Error,
+  fallbackModel: string,
+  fallbackError: Error
+) =>
+  new Error(
+    `Advisor model ${primaryModel} failed: ${primaryError.message}. Fallback Advisor model ${fallbackModel} failed: ${fallbackError.message}.`,
+    { cause: fallbackError }
+  );
+
+const advisorContextDetails = (context: ConsultationContext | undefined) => ({
+  agentRulesBytes: context?.projectRules?.bytes || undefined,
+  draftBytes: context?.draftText
+    ? Buffer.byteLength(context.draftText, "utf-8")
+    : undefined,
+  imageBytes:
+    context?.images.reduce(
+      (sum, item) => sum + Buffer.from(item.image.data, "base64").length,
+      0
+    ) || undefined,
+  imageCount: context?.images.length,
+  imageOmissions: context?.imageOmissions || undefined,
+  imagePartsSeen: context?.imagePartsSeen || undefined,
+  preferenceBytes: context?.preferences?.bytes,
+  scout: context?.scout,
+  trackedBytes:
+    context?.tracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
+  untrackedBytes:
+    context?.untracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
+});
 
+const runAdvisorAttempt = async (
+  options: CollectAdvisorResponseOptions,
+  prepared: PreparedAdvisorRequest,
+  resolved: Awaited<ReturnType<typeof resolveConfiguredModel>>,
+  modelRef: string
+): Promise<CollectedAdvisorResponse> => {
   const streamed = await collectTextStream(resolved, {
-    messages,
+    messages: structuredClone(prepared.messages),
     onChunk: options.onChunk,
     reasoning: advisorEffortRef,
-    signal,
-    systemPrompt,
+    signal: options.signal,
+    systemPrompt: prepared.systemPrompt,
   });
-  const markdown = streamed.text;
+  const { text: markdown } = streamed;
   if (!markdown.trim()) {
     throw new AdvisorNoAdviceError();
   }
-  const response: Omit<AdvisorConsultationResult, "adviceId" | "trigger"> = {
-    agentRulesBytes: context.projectRules?.bytes || undefined,
-    draftBytes: context.draftText
-      ? Buffer.byteLength(context.draftText, "utf-8")
-      : undefined,
-    imageBytes:
-      context.images.reduce(
-        (sum, item) => sum + Buffer.from(item.image.data, "base64").length,
-        0
-      ) || undefined,
-    imageCount: context.images.length,
-    imageOmissions: context.imageOmissions || undefined,
-    imagePartsSeen: context.imagePartsSeen || undefined,
+  return {
+    ...advisorContextDetails(prepared.context),
+    followUp: Boolean(options.followUp),
+    followUpPayload: {
+      depth: options.followUp ? options.followUp.payload.depth + 1 : 0,
+      messages: structuredClone(prepared.messages),
+      model: modelRef,
+      privacyKey: prepared.privacyKey,
+      redacted: prepared.redacted,
+      systemPrompt: prepared.systemPrompt,
+    },
     markdown,
-    model: advisorRef,
-    preferenceBytes: context.preferences?.bytes,
+    model: modelRef,
     thinkingText: streamed.thinking,
-    trackedBytes:
-      context.tracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
-    untrackedBytes:
-      context.untracked.reduce((sum, item) => sum + item.bytes, 0) || undefined,
     usage: streamed.usage,
   };
-  if (context.scout) {
-    response.scout = context.scout;
+};
+
+const runFallbackAdvisorAttempt = async (
+  options: CollectAdvisorResponseOptions,
+  primaryModel: string,
+  primaryError: Error,
+  prepared: PreparedAdvisorRequest | undefined
+): Promise<CollectedAdvisorResponse> => {
+  const { ctx } = options;
+  let request = prepared;
+  if (!advisorFallbackModelRef) {
+    throw primaryError;
+  }
+  const fallbackModel = advisorFallbackModelRef;
+  if (fallbackModel === primaryModel) {
+    throw combinedFallbackError(
+      primaryModel,
+      primaryError,
+      fallbackModel,
+      new Error("fallback is the same model as the primary Advisor")
+    );
+  }
+  if (sameModelAdvisorDisabled(ctx, ctx.model, fallbackModel)) {
+    throw combinedFallbackError(
+      primaryModel,
+      primaryError,
+      fallbackModel,
+      new Error(fallbackSameModelAdvisorNotice)
+    );
+  }
+  const fallbackAccessReason = advisorModelAccessReason(ctx);
+  if (fallbackAccessReason) {
+    throw combinedFallbackError(
+      primaryModel,
+      primaryError,
+      fallbackModel,
+      new Error(fallbackAccessReason)
+    );
+  }
+  let resolvedFallback: Awaited<ReturnType<typeof resolveConfiguredModel>>;
+  try {
+    resolvedFallback = await resolveConfiguredModel(
+      ctx,
+      fallbackModel,
+      "Advisor fallback"
+    );
+  } catch (error) {
+    throw combinedFallbackError(
+      primaryModel,
+      primaryError,
+      fallbackModel,
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+  if (!request) {
+    try {
+      request = options.followUp
+        ? prepareFollowUp(options.followUp, options.question, options.ctx)
+        : await prepareFreshRequest(options, resolvedFallback);
+    } catch (error) {
+      throw combinedFallbackError(
+        primaryModel,
+        primaryError,
+        fallbackModel,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+  try {
+    return await runAdvisorAttempt(
+      options,
+      request,
+      resolvedFallback,
+      fallbackModel
+    );
+  } catch (error) {
+    if (options.signal?.aborted) {
+      throw error;
+    }
+    throw combinedFallbackError(
+      primaryModel,
+      primaryError,
+      fallbackModel,
+      error instanceof Error ? error : new Error(String(error))
+    );
   }
-  return response;
+};
+
+const collectAdvisorResponse = async (
+  options: CollectAdvisorResponseOptions
+): Promise<CollectedAdvisorResponse> => {
+  const { ctx, signal } = options;
+  loadConfig(ctx);
+  const primaryModel = options.followUp?.payload.model ?? advisorRef;
+  if (sameModelAdvisorDisabled(ctx, ctx.model, primaryModel)) {
+    throw new Error(
+      primaryModel === advisorRef
+        ? sameModelAdvisorNotice
+        : fallbackSameModelAdvisorNotice
+    );
+  }
+  const accessReason = advisorModelAccessReason(ctx);
+  if (accessReason) {
+    throw new Error(accessReason);
+  }
+
+  let primaryError: Error | undefined;
+  let prepared: PreparedAdvisorRequest | undefined;
+  let resolvedPrimary:
+    | Awaited<ReturnType<typeof resolveConfiguredModel>>
+    | undefined;
+  try {
+    resolvedPrimary = await resolveConfiguredModel(
+      ctx,
+      primaryModel,
+      "Advisor"
+    );
+  } catch (error) {
+    primaryError = error instanceof Error ? error : new Error(String(error));
+  }
+  if (resolvedPrimary) {
+    prepared = options.followUp
+      ? prepareFollowUp(options.followUp, options.question, options.ctx)
+      : await prepareFreshRequest(options, resolvedPrimary);
+    try {
+      return await runAdvisorAttempt(
+        options,
+        prepared,
+        resolvedPrimary,
+        primaryModel
+      );
+    } catch (error) {
+      primaryError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+  if (!primaryError) {
+    throw new Error("Advisor request failed before an error was recorded.");
+  }
+  if (signal?.aborted) {
+    throw primaryError;
+  }
+  return runFallbackAdvisorAttempt(
+    options,
+    primaryModel,
+    primaryError,
+    prepared
+  );
 };
 
 export const consultAdvisor = async (
@@ -191,12 +455,15 @@ export const consultAdvisor = async (
   includeUntracked?: string[],
   includeTracked?: string[],
   onScout?: (event: ScoutLifecycleEvent) => void,
-  currentInvocationId?: string
+  currentInvocationId?: string,
+  followUp?: AdvisorFollowUpRequest,
+  onFollowUpPayload?: AdvisorFollowUpCapture
 ): Promise<AdvisorConsultationResult> => {
   const result = await collectAdvisorResponse({
     ctx,
     currentInvocationId,
     draft,
+    followUp,
     gitContext,
     includeTracked,
     includeUntracked,
@@ -206,7 +473,10 @@ export const consultAdvisor = async (
     signal,
     systemPrompt: ADVISOR_SYSTEM,
   });
-  return { ...result, adviceId: randomUUID(), trigger };
+  const adviceId = randomUUID();
+  const { followUpPayload, ...publicResult } = result;
+  onFollowUpPayload?.(adviceId, followUpPayload, followUp?.adviceId);
+  return { ...publicResult, adviceId, trigger };
 };
 
 export const runAdvisorGate = async (

package/src/tools/model-access.ts

@@ -41,17 +41,21 @@ export const advisorModelAccess = (
 
 export const sameModelAdvisorDisabled = (
   ctx: Pick<ExtensionContext, "model">,
-  model: { id: string; provider: string } | undefined = ctx.model
+  model: { id: string; provider: string } | undefined = ctx.model,
+  advisorModelRef: string | undefined = advisorRef
 ): boolean => {
-  if (!(advisorDisableSameModelRef && advisorRef && model)) {
+  const selectedAdvisorRef = advisorModelRef ?? advisorRef;
+  if (!(advisorDisableSameModelRef && selectedAdvisorRef && model)) {
     return false;
   }
-  const [provider, id] = splitRef(advisorRef);
+  const [provider, id] = splitRef(selectedAdvisorRef);
   return provider === model.provider && id === model.id;
 };
 
 export const sameModelAdvisorNotice =
   "Advisor disabled: executor and advisor are the same model.";
+export const fallbackSameModelAdvisorNotice =
+  "Advisor fallback skipped: executor and fallback Advisor are the same model.";
 
 export const advisorModelIsAllowed = (
   ctx: Pick<ExtensionContext, "model">

package/src/tools/register-ask-advisor.ts

@@ -11,6 +11,7 @@ import {
   isSimpleMode,
 } from "../config/state.ts";
 import { loadConfig } from "../config/storage.ts";
+import type { AdvisorFollowUpPayload } from "../follow-up.ts";
 import { notifyHerdrAdvisorFailure } from "../herdr.ts";
 import {
   ADVISOR_STREAM_UPDATE_INTERVAL_MS,
@@ -21,10 +22,12 @@ import {
   advisorUsageForPi,
   snapshotAdvisorUsage,
 } from "../usage.ts";
+import { assertAdvisorFollowUpPrivacy } from "./consultation.ts";
 import { notifyLocalFailure, updateAdvisorUsageStatus } from "./gate-policy.ts";
 import { normalizeScreeningQuestion, screeningSkipText } from "./jev-filter.ts";
 import {
   advisorModelAccessReason,
+  fallbackSameModelAdvisorNotice,
   sameModelAdvisorDisabled,
   sameModelAdvisorNotice,
 } from "./model-access.ts";
@@ -47,6 +50,65 @@ const assertAdvisorModelAccess = (ctx: ExtensionContext) => {
   }
 };
 
+interface AskAdvisorParams {
+  draft?: string;
+  followUpTo?: string;
+  force?: boolean;
+  gitContext?: "none" | "summary" | "full";
+  includeTrackedFiles?: string[];
+  includeUntracked?: string[];
+  question?: string;
+}
+
+const resolveFollowUp = (
+  params: AskAdvisorParams,
+  session: ToolRegistrationContext["session"]
+): { adviceId: string; payload: AdvisorFollowUpPayload } | undefined => {
+  if (!params.followUpTo) {
+    return undefined;
+  }
+  if (
+    !params.question?.trim() ||
+    params.draft !== undefined ||
+    params.gitContext !== undefined ||
+    params.includeTrackedFiles?.length ||
+    params.includeUntracked?.length
+  ) {
+    throw new Error(
+      "Follow-up consultations accept only followUpTo and a non-empty question. Issue a fresh consultation for new context or attachments."
+    );
+  }
+  const cached = session.followUpFor(params.followUpTo);
+  if (!cached.payload) {
+    throw new Error(
+      `Follow-up unavailable for adviceId ${params.followUpTo}: ${cached.reason ?? "the cached payload is unavailable"}. Issue a fresh consultation.`
+    );
+  }
+  return { adviceId: params.followUpTo, payload: cached.payload };
+};
+
+const sameModelNoticeFor = (modelRef: string | undefined) =>
+  (modelRef ?? advisorRef) === advisorRef
+    ? sameModelAdvisorNotice
+    : fallbackSameModelAdvisorNotice;
+
+const skippedSameModelResult = (
+  id: string,
+  notice: string,
+  reservedCalls: Set<string>,
+  session: ToolRegistrationContext["session"]
+) => {
+  session.releaseCall(id);
+  reservedCalls.delete(id);
+  return {
+    content: [{ text: notice, type: "text" as const }],
+    details: {
+      skipReason: notice,
+      text: notice,
+    },
+  };
+};
+
 const claimTrackedHandoff = (
   session: ToolRegistrationContext["session"],
   includeTrackedFiles: string[] | undefined
@@ -76,23 +138,25 @@ export const registerAskAdvisorTool = ({
 }: ToolRegistrationContext): void => {
   pi.registerTool({
     description:
-      "Consult the on-demand Advisor model for strategic guidance. Call with an empty object for a contextual review; attach an optional draft for concrete plan or completion review. If the Advisor explicitly names a missing file, you may make a sequential follow-up call with includeTrackedFiles when enabled and relevant.",
+      "Consult the on-demand Advisor model for strategic guidance. Call with an empty object for a contextual review; attach an optional draft for concrete plan or completion review. Use followUpTo with a new question to continue one cached consultation without rebuilding its redacted context. If the Advisor explicitly names a missing file, you may make a sequential fresh consultation with includeTrackedFiles when enabled and relevant.",
     async execute(_id, params, signal, onUpdate, ctx) {
-      const skipSameModel = () => {
-        session.releaseCall(_id);
-        reservedCalls.delete(_id);
-        return {
-          content: [{ text: sameModelAdvisorNotice, type: "text" as const }],
-          details: {
-            skipReason: sameModelAdvisorNotice,
-            text: sameModelAdvisorNotice,
-          },
-        };
-      };
+      let followUp:
+        | { adviceId: string; payload: AdvisorFollowUpPayload }
+        | undefined;
       try {
         loadConfig(ctx);
-        if (sameModelAdvisorDisabled(ctx)) {
-          return skipSameModel();
+        followUp = resolveFollowUp(params, session);
+        if (followUp) {
+          assertAdvisorFollowUpPrivacy(followUp.payload, ctx);
+        }
+        const modelRef = followUp?.payload.model;
+        if (sameModelAdvisorDisabled(ctx, ctx.model, modelRef)) {
+          return skippedSameModelResult(
+            _id,
+            sameModelNoticeFor(modelRef),
+            reservedCalls,
+            session
+          );
         }
         assertAdvisorModelAccess(ctx);
       } catch (error) {
@@ -148,8 +212,13 @@ export const registerAskAdvisorTool = ({
             },
           };
         }
-        if (sameModelAdvisorDisabled(ctx)) {
-          return skipSameModel();
+        if (sameModelAdvisorDisabled(ctx, ctx.model, followUp?.payload.model)) {
+          return skippedSameModelResult(
+            _id,
+            sameModelNoticeFor(followUp?.payload.model),
+            reservedCalls,
+            session
+          );
         }
         if (
           !simpleMode &&
@@ -191,7 +260,8 @@ export const registerAskAdvisorTool = ({
               coalescedUpdate.update({
                 content: [{ text: tx, type: "text" }],
                 details: {
-                  advisor: advisorRef,
+                  advisor: followUp?.payload.model ?? advisorRef,
+                  followUp: Boolean(followUp),
                   question: resolveAdvisorRequest(params.question),
                   scout: scoutDetails,
                   text: tx,
@@ -209,13 +279,17 @@ export const registerAskAdvisorTool = ({
               coalescedUpdate.update({
                 content: [{ text: scoutDetails.text ?? "", type: "text" }],
                 details: {
-                  advisor: advisorRef,
+                  advisor: followUp?.payload.model ?? advisorRef,
+                  followUp: Boolean(followUp),
                   question: resolveAdvisorRequest(params.question),
                   scout: scoutDetails,
                 },
               });
             },
-            _id
+            _id,
+            followUp,
+            (adviceId, payload, replacesAdviceId) =>
+              session.captureFollowUp(adviceId, payload, replacesAdviceId)
           );
           flushUpdate();
           session.issueAdvice(
@@ -228,6 +302,7 @@ export const registerAskAdvisorTool = ({
           session.recordInvocation({
             cost: advisorUsageCost(result.usage),
             executionEffect: "continued",
+            followUp: result.followUp,
             kind: "markdown",
             model: result.model,
             trigger: "executor-requested",
@@ -241,6 +316,7 @@ export const registerAskAdvisorTool = ({
             advisor: result.model,
             agentRulesBytes: result.agentRulesBytes,
             draftBytes: result.draftBytes,
+            followUp: result.followUp,
             imageBytes: result.imageBytes,
             imageCount: result.imageCount,
             imageOmissions: result.imageOmissions,
@@ -259,7 +335,7 @@ export const registerAskAdvisorTool = ({
           const response: AgentToolResult<AdvisorToolDetails> = {
             content: [
               {
-                text: `Advisor (${result.model})\n\n${result.markdown}`,
+                text: `${result.followUp ? "Advisor follow-up" : "Advisor"} (${result.model})\n\n${result.markdown}`,
                 type: "text",
               },
             ],
@@ -280,7 +356,7 @@ export const registerAskAdvisorTool = ({
             executionEffect: "continued",
             failure: "provider-error",
             kind: "markdown",
-            model: advisorRef,
+            model: followUp?.payload.model ?? advisorRef,
             trigger: "executor-requested",
           });
           updateAdvisorUsageStatus(ctx, session);
@@ -303,6 +379,12 @@ export const registerAskAdvisorTool = ({
             "Concise untrusted draft for plan or completion review; claims are not verification evidence.",
         })
       ),
+      followUpTo: Type.Optional(
+        Type.String({
+          description:
+            "Opaque adviceId from a prior successful consultation. Requires a new non-empty question and reuses that consultation's redacted payload; do not combine with draft, Git context, or file attachments.",
+        })
+      ),
       force: Type.Optional(
         Type.Boolean({
           description:
@@ -342,12 +424,16 @@ export const registerAskAdvisorTool = ({
       ),
     }),
     promptGuidelines: [
-      "Call ask_advisor with an empty object for general consultation. For a plan or completion review, include a concise draft naming work, validation, and remaining risks; its claims are not evidence. If the Advisor explicitly says it cannot review a specifically named file, you may make a sequential follow-up call with includeTrackedFiles when the file is relevant, permitted, and worth the shared call budget; do not infer paths or retry automatically.",
+      "Call ask_advisor with an empty object for general consultation. For a plan or completion review, include a concise draft naming work, validation, and remaining risks; its claims are not evidence. To drill into an existing answer, pass its adviceId as followUpTo with a new question and no draft, Git context, or attachments. If the Advisor explicitly says it cannot review a specifically named file, you may make a sequential follow-up call with includeTrackedFiles when the file is relevant, permitted, and worth the shared call budget; do not infer paths or retry automatically.",
     ],
     promptSnippet:
       "Consult the Advisor using its existing context; attach a draft for plan or completion review",
     renderCall(args, theme) {
-      return renderAdvisorCallBox(args.question?.trim(), theme);
+      return renderAdvisorCallBox(
+        args.question?.trim(),
+        theme,
+        Boolean(args.followUpTo)
+      );
     },
     renderResult(result, options, theme, context) {
       // SAFETY: this tool's execute() only returns AdvisorToolDetails-shaped details.