feat: show model-written tool intent in the working indicator

Inject a required first field "i" (concise intent) into tool schemas
sent to providers, gated by the tool_intent experimental flag (default
on). The runtime strips the field before validation, hooks, execution,
and persistence, and carries it on the tool.call.started event. The TUI
shows the intent live in the spinner label, streamed from partial
tool-call arguments, and falls back to the rotating verbs without it.

Author: elkaix

.changeset/tool-intent-indicator.md

@@ -0,0 +1,5 @@
+---
+"@pythoughts/pythinker-code": minor
+---
+
+Show what the agent is doing in the working indicator: each tool call now carries a short model-written intent, streamed live into the spinner label (for example "check failing test…") instead of a random verb; disable with `PYTHINKER_CODE_EXPERIMENTAL_TOOL_INTENT=0`.

apps/pythinker-code/src/tui/constant/rendering.ts

@@ -132,6 +132,26 @@ export const THINKING_SPINNER_LABELS = [
 
 export const THINKING_SPINNER_LABEL_INTERVAL_MS = 12_000;
 
+const LIVE_INTENT_MAX_LENGTH = 120;
+// oxlint-disable-next-line no-control-regex -- wire text must not retain terminal escape sequences.
+const ANSI_ESCAPE = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007]*(?:\u0007|$))/gu;
+const CONTROL_CHARACTER = /\p{Cc}/gu;
+let liveIntent: string | undefined;
+
+export function setLiveIntent(text: string | undefined): void {
+  if (text === undefined) {
+    liveIntent = undefined;
+    return;
+  }
+  const normalized = text
+    .replaceAll(ANSI_ESCAPE, '')
+    .replaceAll(CONTROL_CHARACTER, ' ')
+    .replaceAll(/\s+/gu, ' ')
+    .trim();
+  liveIntent =
+    Array.from(normalized).slice(0, LIVE_INTENT_MAX_LENGTH).join('').trimEnd() || undefined;
+}
+
 /** Rotating thinking label for the given wall-clock moment; falls back to the first label. */
 export function getThinkingSpinnerLabel(nowMs: number = Date.now()): string {
   const index =
@@ -143,5 +163,5 @@ export function getThinkingSpinnerLabel(nowMs: number = Date.now()): string {
 
 /** Thinking label plus an ellipsis, for the thinking block header. */
 export function formatThinkingSpinnerLabel(nowMs: number = Date.now()): string {
-  return `${getThinkingSpinnerLabel(nowMs)}…`;
+  return `${liveIntent ?? getThinkingSpinnerLabel(nowMs)}…`;
 }

apps/pythinker-code/src/tui/controllers/session-event-handler.ts

@@ -44,6 +44,7 @@ import {
   OAUTH_LOGIN_REQUIRED_STARTUP_NOTICE,
 } from '../constant/pythinker-tui';
 import { FAILURE_MARK, STATUS_BULLET, SUCCESS_MARK } from '../constant/symbols';
+import { setLiveIntent } from '../constant/rendering';
 import { buildGoalCompletionMessage } from '../utils/goal-completion';
 import {
   argsRecord,
@@ -166,6 +167,7 @@ export class SessionEventHandler {
   >();
 
   resetRuntimeState(): void {
+    setLiveIntent(undefined);
     this.backgroundTasks.clear();
     this.backgroundTaskTranscriptedTerminal.clear();
     this.subAgentEventHandler.resetRuntimeState();
@@ -361,6 +363,7 @@ export class SessionEventHandler {
   // ---------------------------------------------------------------------------
 
   private handleTurnBegin(_event: TurnStartedEvent): void {
+    setLiveIntent(undefined);
     void _event;
     this.currentTurnHasAssistantText = false;
     // Throughput belongs to the finished turn; clear it so a stale t/s rate
@@ -402,6 +405,7 @@ export class SessionEventHandler {
   }
 
   private handleTurnEnd(event: TurnEndedEvent, sendQueued: (item: QueuedMessage) => void): void {
+    setLiveIntent(undefined);
     this.host.streamingUI.flushNow();
     this.host.dispatchFooter({
       type: 'status.updated',
@@ -423,6 +427,7 @@ export class SessionEventHandler {
   }
 
   private handleStepBegin(event: TurnStepStartedEvent): void {
+    setLiveIntent(undefined);
     this.host.streamingUI.flushNow();
     this.host.streamingUI.setStep(event.step);
     this.host.streamingUI.resetToolUi();
@@ -439,6 +444,7 @@ export class SessionEventHandler {
   }
 
   private handleStepCompleted(event: TurnStepCompletedEvent): void {
+    setLiveIntent(undefined);
     this.host.streamingUI.flushNow();
     this.maybeShowDebugTiming(event);
     if (event.finishReason !== 'max_tokens') return;
@@ -555,6 +561,7 @@ export class SessionEventHandler {
   }
 
   private handleStepInterrupted(event: TurnStepInterruptedEvent): void {
+    setLiveIntent(undefined);
     this.host.streamingUI.flushNow();
     this.host.streamingUI.resetToolUi();
     this.host.streamingUI.finalizeLiveTextBuffers('idle');
@@ -639,6 +646,7 @@ export class SessionEventHandler {
     ) {
       return;
     }
+    if (event.intent !== undefined) setLiveIntent(event.intent);
     const { streamingUI } = this.host;
     streamingUI.flushNow();
     const { turnId, step } = streamingUI.getTurnContext();
@@ -673,6 +681,8 @@ export class SessionEventHandler {
     const { state, streamingUI } = this.host;
     streamingUI.accumulateToolCallDelta(event.toolCallId, event.name, event.argumentsPart);
     const preview = streamingUI.getStreamingToolCallPreview(event.toolCallId);
+    const intent = preview?.args['i'];
+    if (typeof intent === 'string') setLiveIntent(intent);
     if (
       preview !== undefined &&
       preview.name === 'DynamicWorkflow'
@@ -708,6 +718,7 @@ export class SessionEventHandler {
   }
 
   private handleToolResult(event: ToolResultEvent): void {
+    setLiveIntent(undefined);
     const { streamingUI } = this.host;
     streamingUI.flushNow();
     const resultData: ToolResultBlockData = {
@@ -1003,6 +1014,7 @@ export class SessionEventHandler {
   }
 
   private handleSessionError(event: ErrorEvent): void {
+    setLiveIntent(undefined);
     this.host.streamingUI.flushNow();
     this.host.streamingUI.resetToolUi();
     this.host.streamingUI.finalizeLiveTextBuffers('idle');

apps/pythinker-code/src/tui/controllers/streaming-ui.ts

@@ -737,10 +737,12 @@ export class StreamingUIController {
   private flushToolCallPreview(id: string): void {
     const streaming = this._streamingToolCallArguments.get(id);
     if (streaming === undefined) return;
+    const args = parseStreamingArgs(streaming.argumentsText);
+    if (typeof args['i'] === 'string') delete args['i'];
     const toolCall: ToolCallBlockData = {
       id,
       name: streaming.name ?? this._activeToolCalls.get(id)?.name ?? 'Tool',
-      args: parseStreamingArgs(streaming.argumentsText),
+      args,
       streamingArguments: streaming.argumentsText,
       streamingStartedAtMs: streaming.startedAtMs,
       step: this._currentStep,

apps/pythinker-code/test/tui/tool-intent-label.test.ts

@@ -0,0 +1,83 @@
+import type { Event } from '@pythoughts/pythinker-code-sdk';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { DEFAULT_STATUS_LINE_CONFIG } from '#/tui/config';
+import {
+  formatThinkingSpinnerLabel,
+  setLiveIntent,
+} from '#/tui/constant/rendering';
+import { PythinkerTUI, type PythinkerTUIStartupInput } from '#/tui/pythinker-tui';
+
+function makeStartupInput(): PythinkerTUIStartupInput {
+  return {
+    cliOptions: {
+      session: undefined,
+      continue: false,
+      rewindFiles: undefined,
+      yolo: false,
+      auto: false,
+      plan: false,
+      model: undefined,
+      outputFormat: undefined,
+      prompt: undefined,
+      skillsDirs: [],
+    },
+    tuiConfig: {
+      theme: 'dark',
+      layout: 'inline',
+      copyFullResponse: false,
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+      upgrade: { autoInstall: true },
+      statusLine: DEFAULT_STATUS_LINE_CONFIG,
+    },
+    version: '0.0.0-test',
+    workDir: '/tmp/tool-intent-test',
+  };
+}
+
+afterEach(() => {
+  setLiveIntent(undefined);
+});
+
+describe('tool intent thinking label', () => {
+  it('uses the live intent and restores the rotating label when cleared', () => {
+    setLiveIntent('check failing test');
+    expect(formatThinkingSpinnerLabel(0)).toBe('check failing test…');
+
+    setLiveIntent(undefined);
+    expect(formatThinkingSpinnerLabel(0)).toBe('thinking…');
+  });
+
+  it('removes control characters before display', () => {
+    setLiveIntent('\u001B[31mcheck\n\u0007 failing test\u001B[0m');
+    expect(formatThinkingSpinnerLabel(0)).toBe('check failing test…');
+  });
+
+  it('sets intent from a tool delta and clears it on the result', () => {
+    const driver = new PythinkerTUI({} as never, makeStartupInput());
+    const dispatch = (event: Event): void =>
+      driver.sessionEventHandler.handleEvent(event, vi.fn());
+
+    dispatch({
+      type: 'tool.call.delta',
+      agentId: 'main',
+      sessionId: 'session-1',
+      turnId: 1,
+      toolCallId: 'call-1',
+      name: 'echo',
+      argumentsPart: '{"i":"check failing test","text":"hello"}',
+    });
+    expect(formatThinkingSpinnerLabel(0)).toBe('check failing test…');
+
+    dispatch({
+      type: 'tool.result',
+      agentId: 'main',
+      sessionId: 'session-1',
+      turnId: 1,
+      toolCallId: 'call-1',
+      output: 'hello',
+    });
+    expect(formatThinkingSpinnerLabel(0)).toBe('thinking…');
+  });
+});

docs/configuration/config-files.md

@@ -187,11 +187,12 @@ You can also switch models temporarily without touching the config file — by s
 
 ## `experimental`
 
-`experimental` stores persistent overrides for experimental-feature flags. Currently, `micro_compaction` is the only user-facing entry and defaults to `true`; set it to `false` only when you need to disable automatic trimming of older large tool results.
+`experimental` stores persistent overrides for experimental-feature flags.
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `micro_compaction` | `boolean` | `true` | Trim older large tool results from context while preserving recent conversation |
+| `tool_intent` | `boolean` | `true` | Ask the model to state a concise intent with each tool call and show it live in the working indicator; set `false` to return to the rotating label |
 
 ## `services`
 

docs/configuration/env-vars.md

@@ -135,6 +135,7 @@ Switches that control the behavior of subsystems such as telemetry, background t
 | `PYTHINKER_CODE_WORKFLOW_SIZE_GUIDELINE` | Override the advisory Dynamic Workflow size guideline injected into the tool guidance; takes higher priority than `config.toml` | `small`, `medium`, `large`, `unrestricted` |
 | `PYTHINKER_CODE_EXPERIMENTAL_FLAG` | Enable all registered experimental features for this process; `micro_compaction` is already enabled by default | `1`, `true`, `yes`, `on` |
 | `PYTHINKER_CODE_EXPERIMENTAL_MICRO_COMPACTION` | Override [`[experimental].micro_compaction`](./config-files.md#experimental) for this process | Truthy or falsy |
+| `PYTHINKER_CODE_EXPERIMENTAL_TOOL_INTENT` | Override [`[experimental].tool_intent`](./config-files.md#experimental) for this process. When on (the default), each tool call carries a short model-written intent that the working indicator shows live; set a falsy value to turn it off | Truthy or falsy |
 | `PYTHINKER_SHELL_PATH` | Override the Git Bash path on Windows (used when auto-detection fails) | Absolute path |
 | `PYTHINKER_MODEL_MAX_COMPLETION_TOKENS` | Hard cap on `max_completion_tokens` per LLM step; applies to the `pythinker` provider only | Positive integer; `0` or negative disables clamping |
 | `PYTHINKER_MODEL_TEMPERATURE` | Sampling temperature for every request; applies to the `pythinker` provider only (global — independent of `PYTHINKER_MODEL_NAME`) | Number, e.g. `0.3` |

packages/agent-core/src/agent/turn/index.ts

@@ -746,6 +746,7 @@ export class TurnFlow {
         this.agent.config.maxStepsPerTurn ?? loopControl?.maxStepsPerTurn;
       let stopForGoalBudget = false;
       try {
+        const toolIntentEnabled = this.agent.experimentalFlags.enabled('tool_intent');
         const result = await runTurn({
           turnId: String(turnId),
           signal,
@@ -764,6 +765,7 @@ export class TurnFlow {
           log: this.agent.log,
           maxSteps: maxStepsPerTurn,
           maxRetryAttempts: loopControl?.maxRetriesPerStep,
+          toolIntentEnabled,
           recordStepUsage: async (usage) => {
             outputTokens += usage.output;
             try {
@@ -1232,6 +1234,7 @@ function mapLoopEvent(event: LoopEvent, turnId: number): AgentEvent | undefined
         toolCallId: event.toolCallId,
         name: event.name,
         args: event.args,
+        intent: event.intent,
         description: event.description,
         display: event.display,
       };

packages/agent-core/src/flags/registry.ts

@@ -20,6 +20,14 @@ export const FLAG_DEFINITIONS = [
     default: true,
     surface: 'core',
   },
+  {
+    id: 'tool_intent',
+    title: 'Tool intent indicator',
+    description: 'Ask the model to state a concise intent with each tool call and show it in the working indicator.',
+    env: 'PYTHINKER_CODE_EXPERIMENTAL_TOOL_INTENT',
+    default: true,
+    surface: 'core',
+  },
   {
     id: 'vim_mode',
     title: 'Vim mode',

packages/agent-core/src/loop/events.ts

@@ -61,6 +61,7 @@ export interface LoopToolCallEvent {
   readonly toolCallId: string;
   readonly name: string;
   readonly args: unknown;
+  readonly intent?: string | undefined;
   readonly description?: string | undefined;
   readonly display?: ToolInputDisplay | undefined;
 }