coder
diff --git a/‎docs/hooks/tools.mdx‎
Lines changed: 9 additions & 0 deletions b/‎docs/hooks/tools.mdx‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎src/browser/features/Tools/AdvisorToolCall.test.tsx‎
Lines changed: 20 additions & 0 deletions b/‎src/browser/features/Tools/AdvisorToolCall.test.tsx‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎src/browser/features/Tools/AdvisorToolCall.tsx‎
Lines changed: 19 additions & 1 deletion b/‎src/browser/features/Tools/AdvisorToolCall.tsx‎
Lines changed: 19 additions & 1 deletion
diff --git a/‎src/common/constants/advisor.ts‎
Lines changed: 10 additions & 2 deletions b/‎src/common/constants/advisor.ts‎
Lines changed: 10 additions & 2 deletions
diff --git a/‎src/common/utils/tools/toolDefinitions.test.ts‎
Lines changed: 14 additions & 0 deletions b/‎src/common/utils/tools/toolDefinitions.test.ts‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎src/common/utils/tools/toolDefinitions.ts‎
Lines changed: 5 additions & 1 deletion b/‎src/common/utils/tools/toolDefinitions.ts‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎src/common/utils/tools/tools.ts‎
Lines changed: 16 additions & 0 deletions b/‎src/common/utils/tools/tools.ts‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎src/node/services/agentSkills/builtInSkillContent.generated.ts‎
Lines changed: 9 additions & 0 deletions b/‎src/node/services/agentSkills/builtInSkillContent.generated.ts‎
Lines changed: 9 additions & 0 deletions
@@ -217,6 +217,15 @@ If a value is too large for the environment, it may be omitted (not set). Mux al
 
 {/* BEGIN TOOL_HOOK_ENV_VARS */}
 
+<details>
+<summary>advisor (1)</summary>
+
+| Env var                   | JSON path  | Type   | Description |
+| ------------------------- | ---------- | ------ | ----------- |
+| `MUX_TOOL_INPUT_QUESTION` | `question` | string | —           |
+
+</details>
+
 <details>
 <summary>agent_report (2)</summary>
 
 
@@ -111,6 +111,26 @@ describe("AdvisorToolCall", () => {
     expect(timers[0]?.dataset.active).toBe("true");
   });
 
+  test("renders the advisor question when present", () => {
+    useAdvisorToolLivePhaseMock.mockReturnValue(undefined);
+
+    const view = renderAdvisorToolCall({
+      args: { question: "  Should we split the refactor into smaller commits?  " },
+      status: "completed",
+      result: {
+        type: "advice",
+        advice: "Prefer the smaller diff so reviewers can verify it quickly.",
+        advisorModel: "openai:gpt-4.1-mini",
+        remainingUses: 1,
+      },
+    });
+
+    fireEvent.click(view.getByText("advisor"));
+
+    expect(view.getByText("Question")).toBeTruthy();
+    expect(view.getByText("Should we split the refactor into smaller commits?")).toBeTruthy();
+  });
+
   test("continues rendering completed advice results", () => {
     useAdvisorToolLivePhaseMock.mockReturnValue(undefined);
 
 
@@ -87,6 +87,16 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0;
 }
 
+function getAdvisorQuestion(args: Record<string, unknown>): string | undefined {
+  const rawQuestion = args.question;
+  if (rawQuestion == null || typeof rawQuestion !== "string") {
+    return undefined;
+  }
+
+  const question = rawQuestion.trim();
+  return question.length > 0 ? question : undefined;
+}
+
 function isRemainingUses(value: unknown): value is number | null {
   return value === null || (typeof value === "number" && Number.isInteger(value) && value >= 0);
 }
@@ -203,7 +213,7 @@ const AdvisorMetadata: React.FC<{ advisorModel: string; reasoningLevel?: string
 };
 
 export const AdvisorToolCall: React.FC<AdvisorToolCallProps> = ({
-  args: _args,
+  args,
   result,
   status,
   workspaceId,
@@ -213,6 +223,7 @@ export const AdvisorToolCall: React.FC<AdvisorToolCallProps> = ({
   const { expanded, toggleExpanded } = useToolExpansion();
   const toolStatus = isToolStatus(status) ? status : "pending";
   const livePhase = useAdvisorToolLivePhase(workspaceId, toolCallId);
+  const question = getAdvisorQuestion(args);
   const advisorResult = isAdvisorToolResult(result) ? result : null;
   const hasUnrecognizedResult = result !== undefined && result !== null && advisorResult === null;
   const detailsText =
@@ -255,6 +266,13 @@ export const AdvisorToolCall: React.FC<AdvisorToolCallProps> = ({
 
       {expanded && (
         <ToolDetails text={detailsText}>
+          {question && (
+            <DetailSection>
+              <DetailLabel>Question</DetailLabel>
+              <DetailContent className="text-secondary px-2 py-1.5">{question}</DetailContent>
+            </DetailSection>
+          )}
+
           {advisorResult?.type === "advice" && (
             <>
               <AdvisorMetadata
 
@@ -1,6 +1,12 @@
 /** Default per-turn usage cap for the experimental advisor tool. */
 export const ADVISOR_DEFAULT_MAX_USES_PER_TURN = 3;
 
+/** Tail-biased truncation budget for same-step commentary included in advisor handoffs. */
+export const ADVISOR_HANDOFF_MAX_TEXT_CHARS = 4000;
+
+/** Tail-biased truncation budget for same-step reasoning included in advisor handoffs. */
+export const ADVISOR_HANDOFF_MAX_REASONING_CHARS = 4000;
+
 /**
  * Shared guidance for when the advisor tool is appropriate.
  * Reused by the tool description now and future system-prompt wiring later.
@@ -12,7 +18,8 @@ export const ADVISOR_USAGE_GUIDANCE =
 /** Description shown to the model when the advisor tool is registered. */
 export const ADVISOR_TOOL_DESCRIPTION =
   "Ask a stronger model for strategic advice based on the live conversation transcript. " +
-  ADVISOR_USAGE_GUIDANCE;
+  ADVISOR_USAGE_GUIDANCE +
+  " When you call this tool, pass a brief `question` summarizing the decision or ambiguity you need help with.";
 
 /**
  * System prompt for the nested advisor model call.
@@ -40,4 +47,5 @@ Do not narrate tool use, file inspection, or implementation steps as your own ac
 You may suggest user-facing wording when helpful, but keep the response addressed to the calling assistant.
 
 If the current direction already looks sound, confirm it briefly and explain why.
-Keep the response concise and pointed.`;
+Keep the response concise and pointed.
+The final user message may contain a structured advisor handoff summarizing the immediate consultation request and same-step context.`;
@@ -247,6 +247,20 @@ describe("TOOL_DEFINITIONS", () => {
     );
   });
 
+  it("accepts an optional advisor question and encourages passing one", () => {
+    expect(TOOL_DEFINITIONS.advisor.schema.safeParse({}).success).toBe(true);
+    expect(TOOL_DEFINITIONS.advisor.schema.safeParse({ question: null }).success).toBe(true);
+
+    const parsed = TOOL_DEFINITIONS.advisor.schema.safeParse({
+      question: "Should we split this refactor into smaller commits?",
+    });
+
+    expect(parsed.success).toBe(true);
+    if (parsed.success) {
+      expect(parsed.data.question).toBe("Should we split this refactor into smaller commits?");
+    }
+  });
+
   it("encourages compact task briefs and best-of delegation discipline", () => {
     expect(TOOL_DEFINITIONS.task.description).toContain("compact task brief");
     expect(TOOL_DEFINITIONS.task.description).toContain("plan file");
 
@@ -153,7 +153,11 @@ export const AskUserQuestionToolResultSchema = z.union([
 // advisor (nested strategic guidance)
 // -----------------------------------------------------------------------------
 
-export const AdvisorToolInputSchema = z.object({}).strict();
+export const AdvisorToolInputSchema = z
+  .object({
+    question: z.string().min(1).max(500).nullish(),
+  })
+  .strict();
 
 const AdvisorToolAdviceResultSchema = z
   .object({
 
@@ -68,6 +68,20 @@ export interface ToolModelUsageEvent {
   timestamp: number;
 }
 
+export interface AdvisorToolCallSnapshot {
+  toolCallId: string;
+  toolName: "advisor";
+  input: Record<string, unknown>;
+  stepText: string;
+  stepReasoning: string;
+}
+
+export interface AdvisorStepCaptureRef {
+  currentStepText: string;
+  currentStepReasoning: string;
+  frozenSnapshotsByToolCallId: Map<string, AdvisorToolCallSnapshot>;
+}
+
 /**
  * Configuration for tools that need runtime context
  */
@@ -145,6 +159,8 @@ export interface ToolConfiguration {
     maxOutputTokens?: number;
     /** Returns the live conversation transcript up to the current tool call */
     getTranscriptSnapshot: () => ModelMessage[];
+    /** Returns the frozen same-step capture snapshot for a specific advisor tool call, if available. */
+    takeToolCallSnapshot: (toolCallId: string) => AdvisorToolCallSnapshot | undefined;
     /** Creates a LanguageModel from a model string (delegates to providerModelFactory) */
     createModel: (modelString: string) => Promise<LanguageModel>;
     /** The abort signal from the parent stream */
 
@@ -4025,6 +4025,15 @@ export const BUILTIN_SKILL_FILES: Record<string, Record<string, string>> = {
       "{/* BEGIN TOOL_HOOK_ENV_VARS */}",
       "",
       "<details>",
+      "<summary>advisor (1)</summary>",
+      "",
+      "| Env var                   | JSON path  | Type   | Description |",
+      "| ------------------------- | ---------- | ------ | ----------- |",
+      "| `MUX_TOOL_INPUT_QUESTION` | `question` | string | —           |",
+      "",
+      "</details>",
+      "",
+      "<details>",
       "<summary>agent_report (2)</summary>",
       "",
       "| Env var                          | JSON path        | Type   | Description |",