Wake a thread when a command prints something (watch_command)

[imqdee]

Problem

watch_pull_request handles one kind of waiting well. The server polls the pull request, wakes the agent only when something happened, and the thread stays Waiting in Working instead of landing in the inbox. Nothing like it exists for anything that is not a pull request.

A real case: a thread opened an Ideas discussion and had to wait for a maintainer's answer before opening its PR. The workaround was an external cron job that runs a gh query every 30 minutes and, only when there is a new comment, sends a message into the thread over the WebSocket API. It works, but T3 Code knows nothing about it. The thread looks done in the inbox while it is really waiting, nobody can see or stop the check from the app, and it outlives the work.

Scheduled tasks start an agent turn on every run, even when nothing changed. Checking a discussion every 30 minutes for a week is about 340 turns to learn about one comment. The same gap shows up for an issue reply, another repository's CI, a deploy finishing, a release being published.

Proposal

A watch on a shell command, owned by the thread and started by its agent, working like the pull request watch:

watch_command { command, everyMinutes, label }   -> { watchId }
unwatch_command { watchId }

The server runs the command every everyMinutes (minimum 1, default 10) on the environment that owns the thread, in its worktree:

One run	What happens
exit 0, stdout that differs from what the agent was last told	The agent is woken with the output, queued after any active turn. The watch keeps going
exit 0, the same stdout as last time	Nothing
exit 0 with empty stdout, or exit 1 with nothing on stderr	Nothing. No model runs, nothing is written
any other exit, timeout	A failure. 8 in a row end the watch with a wake saying why

Exit 1 with nothing on stderr is quiet, so | grep and jq -e gates work while a gh error still counts as a failure. Output too long to deliver ends the watch with a request for a narrower command. A stateless check, such as a comment count, wakes once with its first value and then only when it changes. Runs pause while the thread is working, so wakes do not pile up behind a long turn. After 10 wakes the watch stops and says so, like the pull request watch, so a command whose output changes on every run cannot loop the agent. The discussion case:

gh api graphql -f query='{repository(owner:"pingdotgg",name:"t3code"){discussion(number:19838){comments(last:20){nodes{createdAt author{login} body}}}}}' \
  --jq '.data.repository.discussion.comments.nodes[] | select(.createdAt > "2026-10-15T09:00:00Z") | "\(.author.login): \(.body)"'

While a watch is on, the thread is Waiting and does not auto-settle. The thread details card on web and desktop lists each watch with its command, interval, and a stop control. On mobile, tapping the Waiting status stops them. A watch ends on unwatch_command, on Stop, when the thread is settled or archived, or after 7 days, since unlike a pull request it has no natural end. Ending stops a run in progress. Forks do not copy watches. watch_pull_request stays as it is: it knows check states, its own account's comments, conflicts and the host's rate limits, which a command cannot match cheaply.

Permissions

A watch runs a command later, outside any turn, where no approval prompt sees it. So in a first version only the thread's own agent can start one, through MCP, in Full access and default mode. The mode is checked before every run, and leaving Full access ends the watch. Subagent threads, outside MCP clients and app clients cannot start one. Any client with orchestration:operate can stop one. Limits: 60 second timeout, 5 watches per thread, 4 runs at once per environment, output capped.

How it fits

It is a sibling of the pull request watch, reusing its lifecycle rather than its reactor: a watch record on the thread guarded by its start time, the same queue_after_active wake with a monitor notification, and the same derivePendingBackgroundWork entry, so the Waiting state reaches every client without new status logic. Settle, archive and Stop already clear pull request watches, and they would clear these too. Runs go through processRunner, not terminals.

Alternatives

• A command gate on thread-bound scheduled tasks. [Feature]: Scheduled Prompts #6748 already lists "an optional shell guard that skips a costly no-op run". It fixes the cost, but to match it would also need the Waiting state, and Stop and settle ending it. At that point it is a watch living in the scheduler.
• Generalizing the pull request watch reactor. Its logic is about check states, comment watermarks and host rate limits. Little is shared beyond the lifecycle, which this reuses anyway.

Related

#15057 added watch_pull_request because "every agent runs its own watcher". #16588 wakes a thread when a long command exits, which fits alongside this. #16793 (watch_workflow_run) is one case of this. #16459 and #14072 are the same Waiting state from the user's side.

A working branch is ready if the direction is approved: imqdee/t3code@main...feat/thread-command-watch

[Lenoridev]

Following the maintainer's direction on #21338, bringing the GitHub-specific details here. The proposed watch_command would cover my issue/discussion follow-up workflow; I do not need a separate GitHub watcher if this can handle it.

Beyond new top-level comments, useful changes to detect are:

• Discussion replies: Include replies to comments, so a maintainer responding inside an existing comment thread is detected too.
• Lifecycle events: Include issue and discussion close/reopen transitions, plus a discussion answer being selected. Identify the event in the wake so the agent can distinguish an answer from a closure or redirect.
• Own-account filtering: Ignore comments and replies from the authenticated account, including responses the agent posts through that account. Still detect later replies from others.

The baseline should include these values when the watch starts. An existing answer or closed state should not itself appear as new activity. The command should produce stable output that changes for relevant events; an unchanged check should stay quiet without invoking a model. A wake should include the URL, event, and relevant new content.

These could be conventions for a GitHub check command rather than additional GitHub-specific behavior in the generic watch service. The Waiting state, stop/settle/archive behavior, and expiry proposed here already cover the lifecycle I need.

My intended instruction is: “Watch this discussion for maintainer replies; summarize their response and draft any follow-up here for my review.” Watching alone should not authorize posting replies or starting implementation.

[Lenoridev]

@imqdee, are you still planning to move this implementation forward? Your general watch_command approach would cover the issue/discussion workflow I described above, and I’d like to help get it shipped.

I’d be happy to help update the branch or test the GitHub workflow once maintainers agree on the direction. What help would be most useful to you?

[imqdee]

@Lenoridev yes, still planning to. Thanks for bringing the details over.

Replies, close and reopen, the selected answer and skipping your own account all fit in the command itself, so the watch stays generic. One gap is real though: today the first output of a watch wakes the agent, so a discussion that is already closed or answered would wake it once for nothing. I'll change that so the first run only records a baseline, and every later wake means something changed. That also removes the createdAt filter from the example above.

The branch is about 1000 commits behind main, so it needs a rebase before a PR, including the recent pull request watch lifecycle fixes (#16623, #21155, #21309). @juliusmarminge before I do that, is this a direction you'd take as a PR?

Once it is rebased, testing your GitHub workflow against it would be the most useful help. I'll ping you here with the branch.

[imqdee]

@Lenoridev the rebased branch is up as #22182. The first run now only records a baseline, so an already closed or answered discussion does not wake the agent.

Testing your GitHub flow against it would help most: watching a discussion with replies, close and reopen, a selected answer, and comments from your own account filtered out. The command does the filtering, for example a gh api graphql query over comments(last:5) with their replies, plus closed and answer, then a jq filter dropping your own login. Any case that wakes when it should not, or stays quiet when it should wake, is what I'm after.

@juliusmarminge I went ahead and opened the PR so the implementation can be judged next to the proposal. Sorry for not waiting on a yes. Happy to close it if the direction isn't wanted.

[Lenoridev]

After testing watch_command, I think it could grow into a general system for agent-defined watchers.

Currently, it detects changed output. The next step would be to compare the previous and current output, interpret what changed, and wake the agent only when something relevant happened. An issue watcher could then distinguish "new comment" from "issue closed", much like the PR watcher already distinguishes comments, failed checks, and merge conflicts.

The agent setting up a watch could provide both the command and a small parser describing which changes matter. That would let it watch unfamiliar tools and services without requiring a dedicated T3 integration for each one. The checks would run in the background without keeping a model turn open.

The existing PR watcher could become a built-in specialization of the same system, sharing the underlying worker while retaining its PR-specific knowledge.

Would this be a useful longer-term direction? I'd like to discuss the general approach first, independently of the scope of the current PR.

I've also written a draft architecture spec for anyone who wants more detail.

[imqdee]

Thanks for writing this up. I'd keep the current PR as the small base and see how far command-side filtering goes first. Your test already shows the pattern: a jq step that prints labelled events (closed, answer selected, new reply) gives the agent "what changed" without a built-in parser, and a check that prints nothing stays quiet. A parser in T3 would add a second language for agents to write and for the server to run, so I'd want a case where the command can't express it before adding one. Folding the PR watcher in is a maintainer call. If #22182 lands, real usage would show which events people keep re-implementing, and that would be good evidence for your spec.

[Lenoridev]

I agree that the command itself or a script can do this. My point is that T3 should provide reusable state and delivery handling, so each watcher only needs to define which changes matter.

For example, a discussion watcher should report only new external replies and remember what it has reported across restarts. A script can track that itself, but keeping its state consistent with T3's notifications is work the PR watcher already handles natively.

I would like to make that available to agent-defined watchers. The command would fetch the data, and the comparison logic would identify relevant changes. T3 would save the comparison state and queue any notification together.

I would also prefer to validate this with controlled tests before relying on user reports after release. Users may never report how much script code they needed, or notice a missed event. The PR watcher and discussion workflow already give us concrete cases to compare.

I see this as follow-up work beyond the current PR. Maintainers should decide whether the PR watcher eventually uses the same system.

[imqdee]

Agreed that it's follow-up work, and the restart case is already covered: a watch keeps the hash of what it last delivered, which your run confirmed. The real gap is that a wake carries the whole current output, so the agent or the script works out what is new. The smallest step I'd suggest is an option where T3 keeps the last delivered output, which is capped at 4 KB anyway, and wakes the agent with only the lines that were added. That handles "new external replies" without a parser and stays one option on the same tool. Controlled tests against the PR watcher's cases sound right for it. I'd hold it until maintainers weigh in on #22182, so the follow-up builds on whatever shape lands.