Team step entry check

  • Desktop app
  • All plans
View as Markdown

What it does

A team step can carry an Entry check: a shell command the runner executes in the workspace before the step's agent is even launched, every time the step is entered (first visit, loop-back, resume after a restart, each parallel branch before any of them starts). Exit code 0 starts the step. Any other exit code, a cut-off or a command that cannot start never starts it: no agent is launched and no model turn is spent, whatever the step's instructions say. It is the twin of the check command on the other side of the step: the check command measures the work once it is done, the entry check decides whether the step may run at all. This is where an operational kill switch belongs (test ! -f .automation-halted, a script reading a repo variable), instead of a "stop if the flag is set" line in the instructions that an agent may not follow.

Where to find it

Teams window > select a team > click an agent step > properties panel > Entry check (optional), right above Check command. On the canvas, a step with an entry check shows a door badge next to its shield badge. The results show on the run's timeline (Entry check of <step> passed / failed) and, when the run is blocked, on the run box of the sidebar and on the phone's run card.

How to use it

  1. Type the command in Entry check. The example placeholder is test ! -f .automation-halted: create that file to halt every team, delete it to let them run again.
  2. Pick what a failure does under If the check fails: Block the run (default) stops the run as blocked, with the command's exit code and its error output shown, consoles of the earlier steps kept; lift the condition, then re-enter the step or run the team again. Skip this step and continue at another one leaves the step out and sends the run to the step you pick, with the handoff the step was going to receive and the failure added to its risks.
  3. Save. The two cut-off settings below the check command (Silence before cut-off, Total budget) apply to the entry check too and appear as soon as either command exists; a cut-off counts as a failure.

A parallel step that fails its entry check sends the whole run to its designated step (or blocks it) before any branch starts. A step skipped twice in a row without any step starting in between blocks the run, so two skipping steps cannot chase each other.

Settings

None. The three fields live on the step: entryCheckCommand, entryCheckPolicy ("block" by default, or "skip"), entryCheckSkipTo (the step to continue at, required by "skip"). The step's checkIdleTimeoutSec (120 s) and checkMaxTimeoutSec (3600 s) cut it off like the check command.

Agent tools (MCP)

  • teams_save: the three fields on an agent node; nodePatches: [{ id, entryCheckCommand: "..." }] adds one to an existing step, null removes it. A "skip" policy without a usable entryCheckSkipTo (missing, the step itself, Start or a group) is a blocking validation error.
  • capabilities_get({topic: "teams"}): the entryCheck section describes exactly what the runner does, and the blocked status explains a run stopped by it.
  • backlog_get: a run blocked by an entry check reports status: "blocked"; team_cancel_run ends it, team_finalize_run refuses it. Inside the run, team_read_timeline lists each check as an entry-check event and team_read_notes carries the failure.
  • The fields are frozen while a run of the team is alive, like the check command.

Providers

All providers, no difference: the command runs on the desktop, in the platform shell (sh on macOS and Linux, cmd on Windows), before any agent CLI is involved.

Mobile

Nothing to set on the phone: team steps are edited on the desktop, like the check command. A run blocked by an entry check shows its reason (the command, the exit code and its output) on the run card, and Run again works once the condition is lifted.

Limits

  • The command runs in the run's workspace (the project root, or the ticket's worktree), never in a step's own checkout.
  • It writes no routing flag and the agent is not told about it: it runs before there is an agent.
  • A remote SSH project runs the command on the desktop, not on the host.
  • Since 2026-10-16.

Common questions

  • Can I stop a team before a step even starts, without trusting the agent to read a "stop" instruction? Yes, with an Entry check on the step: the runner runs it before the step's agent is launched, and a failure never starts the step.
  • Does a refused step cost tokens or cycles? No: no agent is launched (zero model turns) and no cycle is counted. The timeline shows the check with its verdict and output.
  • What is the difference with the check command? The check command runs when the agent signals completion and writes a routing flag from its exit code; the entry check runs before the agent exists and either blocks the run or skips the step.
  • My run is blocked by an entry check. How do I resume it? Fix what the command checks, then re-enter the step from the run box or run the team again. An agent can also end it with team_cancel_run.

Related

  • Agent Teams: the team editor, the check command and the run box.
  • Team run callback: the agent that started the run is mailed when an entry check blocks it.
  • Backlog Task Board: the ticket a blocked run came from stays free to start a new run once the run is cancelled.