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:

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.
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. Tools on plan_allowed are admitted for the hold too.
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.
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.
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.

In Codex the same command is $z plan <task>.

Admitting a tool just for planning¶

A hold blocks the tools that would let the agent start executing. Sometimes the agent needs one of those tools purely to orient – a documentation lookup, a read-only database query – and whitelisting it would mean the tool is never blockable at any point in the session, which is a much bigger grant than you wanted.

plan_allowed is the narrower grant. Tools on it are admitted past a planning hold, and only during the hold:

profiles:
  research:
    agents: [analyst]
    planning_gate: true
    tools:
      plan_allowed:
        - mcp__context7
        - mcp__db-finance

Two things to know:

The other tool rules still apply during the hold. A plan_allowed tool that is also in pre_review is still reviewed before it runs, and can still be blocked on its own merits. Admission past the gate is not a bypass of review.
It has no effect once the gate releases. After the hold lifts, the tool is governed by the normal visibility and enforcement lists exactly as if plan_allowed were not set.

The key lives under tools: alongside the visibility tiers, but it is not one of them – it controls admission during a hold, not what the reviewer can see.

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.