Agent SDK reference - TypeScript changedagent-sdk/typescript
Upstream edited this page at 11 Oct 2026 22:40 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 11 Oct 2026 23:07 UTC.
Upstream edited
Recorded here
Lines+26added
Lines−4removed
From line
2,186
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits113to this page, all time
The whole hunk
from line 2186, old and new numbered
/
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 2186
21862186 kind: "task-notification";
21872187 subkind?: "scheduled-trigger" | "peer-send-message";
21882188 fireReason?: string;
2189 runId?: string;
21892190 }
21902191 | { kind: "coordinator" }
21912192 | { kind: "auto-continuation" }
from line 2214
22132214
22142215`fireReason` says why a `scheduled-trigger` notification fired, as a short lowercase token such as `scheduled`, `manual`, `retry`, `catch_up`, or `api`. Anthropic servers set it on a [routine](/docs/en/routines)'s deliveries, and your application sets it when it declares a scheduled run. It's absent when neither sent one. Requires TypeScript Agent SDK v0.3.280 or later.
22152216
2217A background task can run more than once under the same `task_id`, such as when Claude [resumes a subagent](/docs/en/agent-sdk/subagents#resume-subagents). Each run has its own [`run_id`](#sdktaskstartedmessage). When a run's notification reaches your session as a user message, `runId` on that message's `task-notification` origin holds the same value. A notification can arrive after the task's next run has started, and it still carries the earlier run's ID. To tell which run a turn belongs to, compare `runId`, not `task_id`. Requires TypeScript Agent SDK v0.3.292 or later.
2218
22162219#### Declare a scheduled run
22172220
22182221If your application runs prompts on its own schedule, declare each run so Claude Code frames the turn to the model as a scheduled task rather than as live input from the user. Start the session with `CLAUDE_CODE_HOST_SCHEDULED_RUN` set to `1` in [`env`](#options), then send the run's [`SDKUserMessage`](#sdkusermessage) with `origin: { kind: "task-notification", subkind: "scheduled-trigger", fireReason: "scheduled" }` and without `isSynthetic`. Claude Code ignores the declaration in a process started without that variable. It also ignores it in a process whose environment carries [`CLAUDECODE`](/docs/en/env-vars) or `CLAUDE_CODE_CHILD_SESSION`. Claude Code keeps `fireReason` only when the value is 1 to 32 lowercase letters or underscores. Requires TypeScript Agent SDK v0.3.280 or later.
from line 5225
52225225
52235226### `SDKTaskNotificationMessage`
52245227
5225Notification when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, [Monitor](#monitor) watches, and background subagents. For the `ambient` field, see [`SDKTaskStartedMessage`](#sdktaskstartedmessage), which defines it and its version requirement.
5228Notification when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, [Monitor](#monitor) watches, and background subagents. For the `run_id` and `ambient` fields, see [`SDKTaskStartedMessage`](#sdktaskstartedmessage), which defines them and their version requirements.
52265229
52275230```typescript theme={null}
52285231type SDKTaskNotificationMessage = {
from line 5232
52295232 type: "system";
52305233 subtype: "task_notification";
52315234 task_id: string;
5235 run_id?: string;
52325236 tool_use_id?: string;
52335237 status: "completed" | "failed" | "stopped";
52345238 reason?: "worker_restart";
from line 5285
52815285 hook_id: string;
52825286 hook_name: string;
52835287 hook_event: string;
5284 uuid: UUID;
5285 session_id: string;
5286};
5287```
5288
5289### `SDKHookProgressMessage`
5290
5291Emitted while a hook is running, with stdout/stderr output.
5292
5293```typescript theme={null}
5294type SDKHookProgressMessage = {
5295 type: "system";
5296 subtype: "hook_progress";
5297 hook_id: string;
5298 hook_name: string;
5299 hook_event: string;
5300 stdout: string;
5301 stderr: string;
5302 output: string;
5303 uuid: UUID;
5304 session_id: string;
5305};
5306```
5307
5308### `SDKHookResponseMessage`
5309
5310Emitted when a hook finishes executing.
5311
5312```typescript theme={null}
5313type SDKHookResponseMessage = {
5314 type: "system";
5315 subtype: "hook_response";
5316 hook_id: string;
5317 hook_name: string;
5318 hook_event: string;
5319 output: s
5288 uuid:
No line in this hunk matches that.