follow
Wait, up to a set timeout, for a background job to report new output or reach a terminal state, returning early on whichever occurs first. Use it to block until a job has something new to show.
Instructions
Wait, bounded, for a background job started by run to have something new to report: new output on the selected stream(s), the job reaching a terminal state (exited/killed/failed), or this call's own bound elapsing - whichever happens first. A timeout is a normal, non-error result, never a hang: it means nothing happened within the bound, nothing more. status, output, and tail remain the complete way to check a job's state and output, whether or not follow is ever called - before this call, after it, or instead of it. cursor, if given, only counts output strictly newer than that seq; omit it to wait for output past whatever already exists on the selected stream(s) at the moment of this call - never for output that already existed before this call started, so a bare call never trivially returns on old backlog. stream picks which stream(s) count toward a return: "stdout", "stderr", or "both" (the default) - this selection scopes the underlying subscription itself, not just what the response later shows, so an arrival on a stream you did not select can never end this call early. Output arrival means a newly materialized line on the selected stream; a buffered fragment without a terminator does not wake the call on its own, but becomes a partial event when the selected stream finalizes; terminal state can still settle the call. timeout_ms bounds how long this one call may wait before returning on its own: omitted, it defaults to 45000ms, a value safe to rely on for any caller; an explicit value above the hard ceiling of 3600000ms (one hour) is silently clamped down to it rather than rejected, since that ceiling only bounds this one call's own subscription lifetime and has no other significance. Asking for longer than the default only pays off with a caller whose own setup actually lets one tool call stay outstanding that long - this tool has no way to see that, and claims nothing about it either way. A caller whose own execution context cannot leave a tool call outstanding for the requested duration - a subagent or background-task turn reclaimed or torn down before this call would return - never gets this tool's benefit, the same as any other call that context cannot hold open that long; that is simply how a tool call behaves there, not something this tool detects or works around. If the calling request is cancelled before this call would otherwise settle, everything it holds open (its subscriptions and its timer) is torn down immediately rather than left to run to its own natural bound. This server also caps how many follow calls may be outstanding (subscribed and waiting) at once, across every connection it serves, at 128; a call made once that cap is already reached is REJECTED outright with a tool error - never queued, never silently delayed - so a caller hitting it should back off and retry shortly, or use status/output/tail instead. That cap is enforced process-wide, not per connection or per client, since this server tracks no connection/client identity today - one connection exhausting it can still deny follow to every other connection, though never silently or without bound.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"job_id": "<job_id>"
},
"name": "follow"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Only counts output strictly newer than this seq toward a return. Omit to wait for output past whatever is already present on the selected stream(s) at call time (the job's current head seq for the selected stream(s), computed fresh at call time) - never 0, so a bare call never trivially returns on backlog that already existed. Must be a non-negative integer if provided. | |
| job_id | Yes | The job id returned by a prior run call. | |
| stream | No | Which stream(s) count toward a return. Defaults to "both". This selection scopes the SUBSCRIPTION itself, not just the response - an arrival on a stream you did not select never ends this call early. | |
| timeout_ms | No | How long, in milliseconds, this call may wait before returning on its own. Omitted, defaults to 45000ms, safe to rely on for any caller. An explicit value above the hard ceiling of 3600000ms (one hour) is silently clamped down to it rather than rejected. Asking for longer than the default only pays off with a caller whose own setup actually lets one tool call stay outstanding that long - this tool has no way to see that. |