feat: show model-written tool intent in the working indicator (#57)

## Related Issue

No linked issue — directly requested feature; problem explained below.

## Problem

While the agent works, the spinner shows a random rotating verb
("pythinking…", "marinating…") that carries no information about what
the agent is actually doing. Users watching a long turn cannot tell
whether the agent is reading, editing, or running tests without
expanding tool cards.

## What changed

Each tool call now carries a short, model-written intent that the
working indicator shows live.

- Tool schemas sent to providers gain an injected required first
property `i` ("concise intent"). Injection happens on request-only
schema clones — registered tools and their validation schemas are never
mutated. Tools with an exact schema contract (`StructuredOutput`), an
existing `i` property, or a non-object schema root are skipped.
- The runtime strips `i` after JSON parse and before validation, so
hooks, permission prompts, execution, and the persisted transcript all
see clean arguments. The sanitized intent (control characters stripped,
120-char cap) rides the `tool.call.started` event as a new optional
`intent` field.
- The TUI streams the intent into the spinner label from partial
tool-call arguments (the field is first in the schema, so it arrives at
the head of the stream on most wires), falls back to the
`tool.call.started` intent, and clears on every turn/step/result
boundary. Without an intent, the rotating labels behave exactly as
before.
- Gated by the `tool_intent` experimental flag, default on; disable with
`PYTHINKER_CODE_EXPERIMENTAL_TOOL_INTENT=0` or `[experimental]
tool_intent = false`.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/Pythoughts-labs/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [x] I have linked a related issue, or explained the problem above.
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- The working indicator now shows live descriptions of ongoing tool
actions.
  - Tool-call events can include optional intent descriptions.
- Intent display is enabled by default and can be disabled through
experimental configuration or an environment variable.
- Intent text is sanitized, normalized, and limited in length for clear,
safe display.

- **Documentation**
  - Added configuration guidance for controlling tool-intent display.

- **Tests**
- Added coverage for intent display, lifecycle behavior, sanitization,
streaming, and tool-call handling.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

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: eligible tool calls whose input schema accepts the injected field now carry a short model-written intent, streamed live into the spinner label (for example "check failing test…") instead of a rotating placeholder; disable with `PYTHINKER_CODE_EXPERIMENTAL_TOOL_INTENT=0`.

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

@@ -132,6 +132,27 @@ export const THINKING_SPINNER_LABELS = [
 
 export const THINKING_SPINNER_LABEL_INTERVAL_MS = 12_000;
 
+const LIVE_INTENT_MAX_LENGTH = 120;
+// Keep in sync with packages/agent-core/src/loop/tool-intent.ts.
+// oxlint-disable-next-line no-control-regex -- wire text must not retain terminal escape sequences.
+const ANSI_ESCAPE = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\|$))/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 +164,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/constant/streaming.ts

@@ -1,7 +1,7 @@
 // Extracts useful string fields from partially streamed JSON tool args.
 // This is intentionally a preview parser, not a full JSON parser.
 export const STREAMING_ARGS_FIELD_RE =
-  /"(path|file_path|command|pattern|query|url|description|title|name)"\s*:\s*"((?:\\.|[^"\\])*)"/g;
+  /"(i|path|file_path|command|pattern|query|url|description|title|name)"\s*:\s*"((?:\\.|[^"\\])*)"/g;
 
 // Bounds live tool-argument previews; final tool.call payloads remain complete.
 export const STREAMING_ARGS_PREVIEW_MAX_CHARS = 64 * 1024;

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();
@@ -285,7 +287,7 @@ export class SessionEventHandler {
       case 'turn.step.started': this.handleStepBegin(event); break;
       case 'turn.step.interrupted': this.handleStepInterrupted(event); break;
       case 'turn.step.completed': this.handleStepCompleted(event); break;
-      case 'turn.step.retrying': break;
+      case 'turn.step.retrying': setLiveIntent(undefined); break;
       case 'tool.progress': this.handleToolProgress(event); break;
       case 'assistant.delta': this.handleAssistantDelta(event); break;
       case 'hook.result': this.handleHookResult(event); break;
@@ -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;
     }
+    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'];
+    setLiveIntent(typeof intent === 'string' ? intent : undefined);
     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,150 @@
+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';
+
+const SANITIZER_FIXTURES = [
+  ['\u001B[31mred\u001B[0m', 'red'],
+  ['\u001B]0;title\u0007visible', 'visible'],
+  ['\u001B]0;title\u001B\\visible', 'visible'],
+  ['check\n\u0007test', 'check test'],
+] as const;
+
+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.each(SANITIZER_FIXTURES)('sanitizes intent %j', (raw, expected) => {
+    setLiveIntent(raw);
+    expect(formatThinkingSpinnerLabel(0)).toBe(`${expected}…`);
+  });
+
+  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…');
+  });
+
+  it('clears a stale intent when the next tool call has no intent', () => {
+    const driver = new PythinkerTUI({} as never, makeStartupInput());
+    const dispatch = (event: Event): void =>
+      driver.sessionEventHandler.handleEvent(event, vi.fn());
+
+    dispatch({
+      type: 'tool.call.started',
+      agentId: 'main',
+      sessionId: 'session-1',
+      turnId: 1,
+      toolCallId: 'call-1',
+      name: 'echo',
+      args: {},
+      intent: 'check failing test',
+    });
+    dispatch({
+      type: 'tool.call.started',
+      agentId: 'main',
+      sessionId: 'session-1',
+      turnId: 1,
+      toolCallId: 'call-2',
+      name: 'StructuredOutput',
+      args: {},
+    });
+
+    expect(formatThinkingSpinnerLabel(0)).toBe('thinking…');
+  });
+
+  it('clears the live intent when a step retries', () => {
+    const driver = new PythinkerTUI({} as never, makeStartupInput());
+    const dispatch = (event: Event): void =>
+      driver.sessionEventHandler.handleEvent(event, vi.fn());
+
+    dispatch({
+      type: 'tool.call.started',
+      agentId: 'main',
+      sessionId: 'session-1',
+      turnId: 1,
+      toolCallId: 'call-1',
+      name: 'echo',
+      args: {},
+      intent: 'check failing test',
+    });
+    dispatch({
+      type: 'turn.step.retrying',
+      agentId: 'main',
+      sessionId: 'session-1',
+      turnId: 1,
+      step: 1,
+      failedAttempt: 1,
+      nextAttempt: 2,
+      maxAttempts: 3,
+      delayMs: 100,
+      errorName: 'Error',
+      errorMessage: 'retry',
+    });
+
+    expect(formatThinkingSpinnerLabel(0)).toBe('thinking…');
+  });
+});

apps/pythinker-code/test/tui/utils/event-payload.test.ts

@@ -18,6 +18,12 @@ describe('streaming tool argument payload helpers', () => {
     });
   });
 
+  it('parses intent from partial streaming arguments', () => {
+    expect(parseStreamingArgs('{"i":"scan configs","path":"/tmp/x')).toMatchObject({
+      i: 'scan configs',
+    });
+  });
+
   it('caps accumulated streaming preview text', () => {
     const current = 'a'.repeat(STREAMING_ARGS_PREVIEW_MAX_CHARS - 2);
 

docs/configuration/config-files.md

@@ -229,11 +229,12 @@ advisor = "reviewer-model"
 
 ## `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 eligible tool calls whose input schema accepts the injected field 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), eligible tool calls whose input schema accepts the injected field carry 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,
       };