Scheduled tasks: skip a run with a gate command and pass its output to the prompt

[Guria]

Note

🤖 Claude Opus 5.5 responding on behalf of Guria

Before submitting

• I searched existing issues and discussions. Feature: scheduled tasks run a pre-model precheck and skip the model turn when nothing changed #20258 asked for the same skip behavior and was redirected to Ideas.
• I am describing a concrete problem or use case.

Area

apps/server (scheduled tasks), contracts, the scheduled task editor on web and mobile, and the schedule_task MCP tool.

Problem or use case

Every time-based scheduled run starts an agent turn, even when there is nothing to do. To skip one today, the prompt has to say "if nothing changed, stop". That still pays for a turn and leaves a no-op turn in the thread.

Many checks are cheap for a script and expensive for a model: a new comment on a discussion, a red CI run in another repository, new rows in a queue, a time-of-day window (#26121), free memory (#32205). #19879 puts a number on it. Polling a discussion every 30 minutes for a week is about 340 turns to learn about one comment.

Webhook tasks already have both pieces this needs. filters skip a delivery without a turn, logged as filtered, and {{body.path}} templates put request data into the prompt. Interval, fixed-time and one-time tasks have neither.

Proposed solution

An optional gate command on interval, fixed-time and one-time tasks. When the task is due, the server runs it on the task's environment before it starts the turn.

Gate result	Run
exit 0	Starts. Stdout goes into the prompt.
exit 1, empty stderr	Skipped. No thread, no turn.
any other exit, or timeout	Skipped, recorded as a gate failure with the stderr tail.

Details, checked against ScheduledTaskService.runTask:

• Next run. After a run the service computes nextRunAt from the stored schedule. A skip goes through the same path, so waiting for the next execution needs no new scheduling logic.
• Context. Stdout is available as {{gate}} in the prompt through the webhook template renderer, and is appended in a labelled block when the prompt doesn't use it. Capped at something like 16 KiB.
• Working directory. The project root for tasks that launch a new thread, since a worktree workspace is created at launch, after the gate. The bound thread's workspace for continue and fresh_session tasks.
• State between runs lives in the script, as a cursor file or a timestamp. The server does not diff output, which keeps this much smaller than Wake a thread when a command prints something (`watch_command`) #19879.
• Recording skips. lastRunStatus is a closed never | running | succeeded | failed list, and clients decode the task list with ForwardCompatibleArray, so a new status value would make the task disappear on shipped clients. A skip leaves lastRunStatus and runCount alone and writes new optional fields such as lastGateAt, lastGateResult: "skipped" | "failed" and lastGateError. The task list shows the last gate result, so a gate that never passes is visible.
• Run now runs the gate too, so it doubles as a test.

Example: a task that summarizes new comments on a discussion.

cursor=~/.cache/t3-gate-19879
since=$(cat "$cursor" 2>/dev/null || echo 1970-01-01T00:00:00Z)
now=$(date -u +%FT%TZ)
out=$(gh api graphql \
  -f query='{repository(owner:"pingdotgg",name:"t3code"){discussion(number:19879){comments(last:20){nodes{createdAt author{login} body}}}}}' \
  --jq ".data.repository.discussion.comments.nodes[] | select(.createdAt > \"$since\") | \"\(.author.login): \(.body)\"") || exit 2
[ -n "$out" ] || exit 1
echo "$now" > "$cursor"
printf '%s\n' "$out"

A gh error exits 2 and shows up as a gate failure. No new comments exits 1 and skips quietly.

Permissions

Saving a task already requires orchestration:operate, and a full-access task already runs agent commands with no approval prompt. Accepting a gate only on full-access tasks adds no new capability. The server rechecks the mode before each gate run. Managed policy gets a scheduledTaskGates switch next to webhookTasks. Limits: a 60 second timeout and a cap on concurrent gate runs per environment.

Alternatives considered

• watch_command (Wake a thread when a command prints something (`watch_command`) #19879). Thread-owned, with a Waiting state and its own lifecycle. A gate reuses the scheduler, editor and cadence that exist, and covers tasks that start a new thread each run. The two fit together: a watch tells a thread when something happens, a gate runs a job only when there is work.
• Active time window ([Feature]: Active time window for interval scheduled tasks #26121). Covers time of day only. [ "$(date +%H)" -ge 8 ] && [ "$(date +%H)" -lt 19 ] is a valid gate, but a window is easier to set in the editor, so both can exist.
• A guard in the prompt. Still a turn per tick.

Related

#20258, #19879, #26121, #32205, and #31997, where a gate would belong in the file-based task config.