Format Task tool calls

Author: benchristel

.changeset/easy-lemons-follow.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/format-claude-stream": patch
+---
+
+Task tool calls are now formatted nicely instead of the raw JSON being dumped.

src/core/events/task-tool-call.ts

@@ -0,0 +1,33 @@
+import {Colorizer} from "../ports/colorizer.ts";
+import {ClaudeIOEvent} from "./claude-io-event.type.ts";
+
+interface ConstructorParams {
+    toolUseId: string;
+    subagentType: string;
+    description: string;
+    prompt: string;
+}
+
+export class TaskToolCall implements ClaudeIOEvent {
+    toolUseId: string;
+    subagentType: string;
+    description: string;
+    prompt: string;
+
+    constructor({
+        toolUseId,
+        subagentType,
+        description,
+        prompt,
+    }: ConstructorParams) {
+        this.toolUseId = toolUseId;
+        this.subagentType = subagentType;
+        this.description = description;
+        this.prompt = prompt;
+    }
+
+    format(colorizer: Colorizer): string {
+        let headline = `Task (${this.subagentType}): ${this.description}`;
+        return [colorizer.importantAction(headline), this.prompt].join("\n");
+    }
+}

src/core/interpreter.test.ts

@@ -13,6 +13,7 @@ import {MarkupColorizer} from "./ports/markup-colorizer.ts";
 import {Interpreter} from "./interpreter.ts";
 import {ToolUseSuccess} from "./events/tool-use-success.ts";
 import {ClaudeIOEvent} from "./events/claude-io-event.type.js";
+import {TaskToolCall} from "./events/task-tool-call.ts";
 
 describe("Interpreter", () => {
     it("outputs a generic tool call event", async () => {
@@ -308,4 +309,40 @@ describe("Interpreter", () => {
             "$ echo hello\nYou don't have permission.\n",
         );
     });
+
+    it("formats a task tool call", async () => {
+        const outputFake = new OutputFake();
+        const interpreter = new Interpreter(outputFake, new NullColorizer());
+
+        await interpreter.process(
+            new TaskToolCall({
+                toolUseId: "1",
+                subagentType: "Explore",
+                description: "look around",
+                prompt: "a prompt",
+            }),
+        );
+
+        expect(outputFake.value()).toBe(
+            "Task (Explore): look around\na prompt\n",
+        );
+    });
+
+    it("colorizes a task tool call", async () => {
+        const outputFake = new OutputFake();
+        const interpreter = new Interpreter(outputFake, new MarkupColorizer());
+
+        await interpreter.process(
+            new TaskToolCall({
+                toolUseId: "1",
+                subagentType: "Explore",
+                description: "look around",
+                prompt: "a prompt",
+            }),
+        );
+
+        expect(outputFake.value()).toBe(
+            "[[importantAction Task (Explore): look around]]\na prompt\n",
+        );
+    });
 });

src/formats/parse-events.ts

@@ -18,6 +18,7 @@ import {UnreachableCodeError} from "../lib/unreachable-code-error.ts";
 import {UnrecognizedJsonEvent} from "../core/events/unrecognized-json-event.ts";
 import {ToolUseSuccess} from "../core/events/tool-use-success.ts";
 import {ToolUseError} from "../core/events/tool-use-error.ts";
+import {TaskToolCall} from "../core/events/task-tool-call.ts";
 
 export function parseEvents(data: unknown): ClaudeIOEvent[] {
     const parsed = StreamJsonLine.safeParse(data);
@@ -101,6 +102,13 @@ function parseToolCallEvent(
                 toolCall.input.pattern,
                 toolCall.input.path,
             );
+        case "Task":
+            return new TaskToolCall({
+                toolUseId: toolCall.id,
+                subagentType: toolCall.input.subagent_type,
+                description: toolCall.input.description,
+                prompt: toolCall.input.prompt,
+            });
         default:
             throw new UnreachableCodeError(toolCall);
     }

src/formats/testcases/task-tool-call.ts

@@ -0,0 +1,52 @@
+import {ClaudeIOEvent} from "../../core/events/claude-io-event.type.ts";
+import {TaskToolCall} from "../../core/events/task-tool-call.ts";
+
+export const data = {
+    type: "assistant",
+    message: {
+        model: "claude-opus-4-6",
+        id: "msg_019QCmPhUXrRHQCn4cUFr72U",
+        type: "message",
+        role: "assistant",
+        content: [
+            {
+                type: "tool_use",
+                id: "toolu_011C9YydUfQk5v4YnCdp4zUo",
+                name: "Task",
+                input: {
+                    subagent_type: "Explore",
+                    description: "Explore CLI and version context",
+                    prompt: "this is the prompt",
+                },
+                caller: {type: "direct"},
+            },
+        ],
+        stop_reason: null,
+        stop_sequence: null,
+        usage: {
+            input_tokens: 1,
+            cache_creation_input_tokens: 990,
+            cache_read_input_tokens: 22524,
+            cache_creation: {
+                ephemeral_5m_input_tokens: 990,
+                ephemeral_1h_input_tokens: 0,
+            },
+            output_tokens: 1,
+            service_tier: "standard",
+            inference_geo: "not_available",
+        },
+        context_management: null,
+    },
+    parent_tool_use_id: null,
+    session_id: "918dfbf3-6251-4f36-b837-36d96efd3303",
+    uuid: "45fcb4b7-527c-4449-b05f-51eba96f25f4",
+};
+
+export const expected: ClaudeIOEvent[] = [
+    new TaskToolCall({
+        toolUseId: "toolu_011C9YydUfQk5v4YnCdp4zUo",
+        subagentType: "Explore",
+        description: "Explore CLI and version context",
+        prompt: "this is the prompt",
+    }),
+];

src/formats/tool-calls.ts

@@ -35,6 +35,16 @@ export const GrepToolCall = z.looseObject({
     }),
 });
 
+export const TaskToolCall = z.looseObject({
+    name: z.literal("Task"),
+    id: z.string(),
+    input: z.looseObject({
+        subagent_type: z.string(),
+        description: z.string(),
+        prompt: z.string(),
+    }),
+});
+
 export const UnrecognizedToolCall = z.looseObject({
     name: z.string(),
     id: z.string(),
@@ -46,4 +56,5 @@ export const ToolCall = z.discriminatedUnion("name", [
     EditToolCall,
     GrepToolCall,
     ReadToolCall,
+    TaskToolCall,
 ]);