fix: address review feedback on tool intent

Author: elkaix

.changeset/tool-intent-indicator.md

@@ -2,4 +2,4 @@
 "@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`.
+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 random verb; disable with `PYTHINKER_CODE_EXPERIMENTAL_TOOL_INTENT=0`.

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

@@ -646,7 +646,7 @@ export class SessionEventHandler {
     ) {
       return;
     }
-    if (event.intent !== undefined) setLiveIntent(event.intent);
+    setLiveIntent(event.intent);
     const { streamingUI } = this.host;
     streamingUI.flushNow();
     const { turnId, step } = streamingUI.getTurnContext();
@@ -682,7 +682,7 @@ export class SessionEventHandler {
     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);
+    setLiveIntent(typeof intent === 'string' ? intent : undefined);
     if (
       preview !== undefined &&
       preview.name === 'DynamicWorkflow'

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

@@ -80,4 +80,32 @@ describe('tool intent thinking label', () => {
     });
     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…');
+  });
 });

docs/configuration/config-files.md

@@ -234,7 +234,7 @@ advisor = "reviewer-model"
 | 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 |
+| `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,7 +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_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/loop/tool-intent.ts

@@ -6,7 +6,7 @@ export const INTENT_MAX_LENGTH = 120;
 export const INTENT_OMIT_TOOLS: ReadonlySet<string> = new Set(['StructuredOutput']);
 
 // oxlint-disable-next-line no-control-regex -- model-authored terminal text must not retain escape sequences.
-const ANSI_ESCAPE = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007]*(?:\u0007|$))/gu;
+const ANSI_ESCAPE = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\|$))/gu;
 const CONTROL_CHARACTER = /\p{Cc}/gu;
 
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
@@ -35,7 +35,7 @@ export function injectIntentIntoTools(tools: readonly ExecutableTool[]): Executa
           [INTENT_FIELD]: { type: 'string', description: 'concise intent' },
           ...properties,
         },
-        required: [INTENT_FIELD, ...required],
+        required: [INTENT_FIELD, ...required.filter((entry) => entry !== INTENT_FIELD)],
       },
       resolveExecution: tool.resolveExecution.bind(tool),
     };

packages/agent-core/test/loop/tool-intent.test.ts

@@ -50,6 +50,18 @@ describe('tool intent schema injection', () => {
     expect(injected?.parameters['required']).toEqual([INTENT_FIELD, 'value']);
   });
 
+  it('does not duplicate intent in required', () => {
+    const tool = makeTool('test', {
+      type: 'object',
+      properties: { value: { type: 'string' } },
+      required: [INTENT_FIELD],
+    });
+
+    const [injected] = injectIntentIntoTools([tool]);
+
+    expect(injected?.parameters['required']).toEqual([INTENT_FIELD]);
+  });
+
   it('returns omitted tools unchanged', () => {
     const omittedTools = INTENT_OMIT_TOOLS as Set<string>;
     omittedTools.add('omitted');
@@ -104,6 +116,12 @@ describe('tool intent sanitization', () => {
     expect(sanitizeIntent('\u001B[31mcheck\n\u0007 failing\u001B[0m')).toBe('check failing');
   });
 
+  it('preserves visible text after an ST-terminated OSC hyperlink', () => {
+    expect(sanitizeIntent('\u001B]8;;https://example.com\u001B\\click\u001B]8;;\u001B\\ done')).toBe(
+      'click done',
+    );
+  });
+
   it('caps the result by code points', () => {
     const sanitized = sanitizeIntent('🙂'.repeat(INTENT_MAX_LENGTH + 1));
     expect(Array.from(sanitized ?? '')).toHaveLength(INTENT_MAX_LENGTH);