Skip to content

Planning Gate

The planning gate makes the agent agree an approach with the reviewer before it commits to a task. Instead of letting the agent charge into unfamiliar or multi-step work and reviewing the damage afterward, the reviewer can hold the agent up front until it brings a plan.

This is a different kind of intervention from a block. A block stops a specific action the agent tried to take. The gate stops the agent before it starts real work on a task, and holds it until the direction is sound.

How the hold works

When a task is gated:

  1. The reviewer places a planning hold on the agent. Real work is blocked – the agent can't run the tools that would let it start executing.
  2. Whitelisted tools stay available. Whatever tools are on your whitelist are never blocked – even during a hold – so the agent can use them to get its bearings, along with message_adversary to talk to the reviewer.
  3. The agent orients – gets a rough sense of where things live and how it would tackle the task – then sends the reviewer a plan via message_adversary: how it intends to approach the work, and the reads, research, and tools it expects to use.
  4. The reviewer grades the direction, not the depth. It's looking for a sound approach and a reasonable sense of the terrain, not finished research. It can push back and ask the agent to reconsider.
  5. When the direction is sound, the reviewer issues a release and the hold lifts. The agent proceeds with real work.

The gate is not sign-off on the eventual result. Once the agent starts working, its tool calls, writes, and stop attempt are reviewed as normal – the plan approval and the work review are separate gates.

Two ways to gate

Always-on, per task

Set planning_gate: true in your settings (in defaults or a profile). With the gate on, the reviewer decides per prompt whether the task warrants planning first – it gates tasks that are multi-step, on unfamiliar ground, or ambiguous in approach, and lets straightforward asks through without a hold. It gates sparingly, not on every message.

defaults:
  planning_gate: true

The gate is off by default.

On demand

Even with the gate off, you can hold a single task on demand:

/z plan Refactor the auth middleware to support API keys

Everything after plan is the task. This places a planning hold immediately for that task and notifies the reviewer, regardless of the profile's planning_gate setting. The agent then orients and brings a plan, exactly as above, and works the task once the reviewer releases it.

If the agent is already blocked when you run /z plan, clear the existing block first with /z unblock.

The read guard is a separate, independent control that refuses oversized unbounded reads – if a file is over the configured ceiling and the agent tries to read the whole thing, the read is denied locally and the agent is directed to sample or search it instead. It's set with read_guard_max_bytes in your settings and is off unless you set a ceiling. Unlike the planning gate, it's a deterministic local check, not a reviewer decision.