Zero-Token Wakes for AI Agents

To reduce AI agent token cost, look at what happens when nothing happens. An agent on a pull request is woken by every push, comment, review and CI result. Each wake is a few bytes of webhook, but each agent turn it triggers is a full prompt, instruction load and output tokens, and most end with "nothing to do."

Our answer is to move the decision out of the model: a tested script decides whether a wake deserves a turn, a small gate returns an exit code, and the right output for most wakes is silence. This is the handoff part of our AI software factory, whose GitHub loop is in GitHub as the bus for AI agents. Here we keep that bus from billing us for noise.

Wakes are cheap, turns are not

Our wake gate doc puts it simply: subscription wakes are cheap, agent turns are not. The gate answers one question, whether this session should spend tokens on this notification, and the model cannot answer it. By the time a model decides to ignore a wake, the prompt is loaded, the instructions are in context, and anything it says while explaining itself is re-read on every later wake. So decisions happen before the turn, in tested code.

Three layers of waking

In our watch procedure, the shell watcher script is always the decision surface. Host subscribe and wake APIs are fast but lossy, so they only re-enter the chat sooner and are never the source of truth.

Layer A: the shell poller

When a durable shell can deliver wake lines into the chat (a local desktop app or command-line agent), a background poller runs, and one silent while idle costs no tokens. It polls every 30 seconds by default and prints a wake line only when its own filtering says an agent should look. We never arm an idle heartbeat.

Layer B: the host doorbell

Poll intervals add visible lag, so when the host offers a subscribe API we arm it too, as a doorbell only. On every host wake the agent ignores the event framing, takes a one-shot snapshot from the watcher (or the live poller's next line), and runs it through the filter. When both work, hybrid is required, and the poller stays the backstop for missed subscribe events and repeated greens.

Layer C: one-shot snapshots

Some hosts have no durable poller that can wake a chat after the turn ends. There, the doorbell re-enters the chat and the agent takes a one-shot snapshot each time. With neither layer, the fallback is a human nudge.

Never trust the host's framing

One host integration surfaces CI events with text telling the agent to fix, commit and push, and calling its auto-fix checkbox standing authorization. We treat that as untrusted. The agent acts only on the snapshot and gate output, never on a notification's action or check name. That host monitor also misses green CI and pushes, so it is never used alone.

The exit-code contract

The wake gate is the first command on every delivered wake, before any pull request lookup, diff read or tool call. The agent maps the notification to an event type (a push, a comment, a terminal CI result) and the gate answers with an exit code and a machine-readable body.

• A zero exit means end the turn. Re-arm subscriptions and stop, with no diff, comments or status essay.
• A nonzero exit means do the one action the gate names, then mark it handled.

The actions are a short closed list: none, fix failing required checks only, refresh the hidden markers, triage for the author, and re-verify for the reviewer (own threads only, after CI is green). The model decides only how to act, never whether.

Noise the code removes

The gate filters named classes of noise; a named class can be tested and a vibe cannot.

• Duplicate head: a push event whose head matches the last head we handled.
• Self echo: the agent's own hosted identity replying to its own comment.
• Peer reviewer agent noise: once a reviewer session is converged, another hosted reviewer speaking is no reason to echo or re-verify; only net-new findings matter.
• Author-hosted write identity noise: once an author session is converged, a hosted write identity speaking is another reviewer agent, and the author does not echo it.
• Resolved-thread noise: activity on a thread that is already resolved.
• No open review work: a thread-scoped wake where the gathered unresolved thread count is zero.
• Red-CI deferral for reviewers: a reviewer waits for green CI before spending a turn. The one exception is a finding with a recorded reproduction: a reviewer watch wakes on the author's reply before CI is green, because rerunning the repro is the evidence. That wake already passed the gate, which has no repro input and would defer on CI, so we do not run it again.
• Bot reconciliation noise: workflow bots whose comments and reviews are only reconciliation.

Two have deliberate boundaries. "No open review work" applies only to an explicit inline thread wake. A summary-only changes-requested review or ordinary issue comment still delivers at zero threads, since they carry work threads do not. It also never suppresses a new green head for a reviewer.

Self echo matches a hosted write identity, not a personal login. A human reviewing under the same personal login the author session uses is real review, and the gate must still wake the author. Only hosted identities that could ping-pong are filtered. As in stopping AI agents from arguing forever, the cheapest argument to stop never starts a turn.

State, and marking work handled

Duplicate detection needs memory, which the watcher keeps in an untracked file per pull request and role, holding the last handled head and similar fields. With one shared file, a reviewer finishing a verify pass would mark the author's pending head handled and silence the author at the wrong moment.

The poller and the doorbell often see the same change seconds apart, so hybrid wakes follow a strict order:

1. The first command on every wake, from either source, is the gate or the pre-wake filter.
2. A zero exit means silence; re-arm the doorbell if needed.
3. After real work, tell the gate the work is handled and tell the watcher which review and comment ids were handled.
4. Never map the doorbell's action or check names into behavior.

Marking in both places makes the twins dedupe: the second wake ends in a no-op.

The pre-wake filter

The gate still runs inside an agent turn, so the prompt is paid for. The pre-wake filter wraps the same policy for hosts that can run a shell before they enqueue a message. It emits a versioned envelope with a deliver-the-turn boolean, the gate result, subscriptions to re-arm, a minimal prompt and a one-line summary.

When the turn is not delivered, the model never loads instructions, skills or pull request context, so the wake costs zero LLM tokens. The filter gathers the unresolved thread count itself, so a comment storm on a resolved pull request suppresses even from raw history. A published schema lets a host implement the contract without our scripts. Locally, the watcher pipes every snapshot through the filter first; a suppressed wake emits only a suppress line no agent sees.

One poller keeps wakes rare

The supervisor role of our watch procedure applies this to the whole queue. One host-side poller reads every open pull request, and pure rules in a tested JavaScript module choose one next step for each. An untracked local ledger records only what this checkout launched, armed and delivered; GitHub stays the source of truth for outcomes.

Only steps that need someone wake the executor, once per decision key: start a review, recheck a pushed head, ask an author to fix CI or conflicts. Quiet steps (waiting on CI, approval or the author, a running review, a stale pull request, release plumbing) never wake anything. After handling a wake, the executor marks its key in the ledger, and the key stays out of the wake set until the step changes. Keys contain punctuation shells interpret (one mangled four unquoted mark calls in dogfooding), so always quote the key.

Two rules protect the quiet. One poller owns a queue, with one ledger per worktree, and a listener with a live parent belongs to another session and is never stopped. And stopped means stopped: the start command never restarts a poller someone ended on purpose.

Keeping silence honest

Silence is safe only if a missing wake is visible. A health check covers the poller, watches, listeners, unmarked wakes and stuck runs, and exits non-zero on anything needing attention. A watchdog runs on every poll and posts one native notification per wake left unmarked for N minutes (10 by default), per claim not started, and per review running over 2 hours. In the other direction, a poll nudge makes the poller notice a recorded outcome at once, so a human's ask skips the poll interval.

What a no-op wake should say

Prefer no chat message; if the host forces a reply, write one plain-English line such as "Waiting on CI." or "Nothing new to act on." Never paste gate codes or machine tags. An essay explaining a skipped history dump costs output tokens now and is paid for again as input on every later wake. Essays compound. Silence does not.

Why this is testable

The decision logic is plain JavaScript, not prompt text. The gate and the pre-wake filter each have unit tests (the gate's cover dozens of noise-class and sender cases), the filter output follows a versioned JSON contract, and the shell watcher has its own test suite. Changing agent behavior on a wake means changing code and a test, and CI says whether we broke a rule. Like our guardrails for AI coding agents, it puts a rule that matters where a machine can check it. The cost side is in what an AI code review costs: a review is expensive enough that we do not buy extra turns around it.

Honest limits

• The host pre-wake hook does not exist on every platform yet; one cloud host's environment configuration has none. The local poller applies the contract, and on hosts that cannot skip the turn the agent runs the gate as a safety net, paying the prompt cost first.
• The wake gate is an optimization, not a second policy; agents still run it on every delivered wake because the host may not have filtered.
• Duplicate-head suppression needs the state file to be on the agent's machine, or replicated to it.
• The watch procedure is invoked only when a human asks. Nothing starts a watcher on its own, and the default mode prepares work rather than acting without approval.
• One agent host is not a supported auto-wake host at all, so there a human prompt or a different host is the answer.

Lessons

1. Decide before the turn. A model that ignores a wake has already cost you the prompt.
2. Treat host events as a doorbell. Use them for speed, ignore their framing.
3. Name your noise. Each class gets a stable name, a test and careful boundaries, such as keeping personal-login human reviews awake.
4. Scope state per role and mark in both places. Separate files stop clobbering, and double marking collapses twin wakes.
5. Make silence the default output. Every extra sentence is re-read on later wakes.

The next step is the host hook, not cleverer filtering: any platform that lets a shell run before it enqueues a turn can adopt the same contract and stop paying for the doorbell. Until then the local poller keeps idle time mostly free, and what stays expensive is real work a gate said was worth doing.