Click: a Codex plugin that prevents repeated planning and over-verification

[grapefruit0205]

Hi everyone,

I built an open-source Codex plugin called Click to address a behavior I kept seeing in high-reasoning coding agents:

The implementation would already be complete, but the agent would continue to:

• reread the same files;
• rescan the repository;
• create another plan after the original direction was already approved;
• run a focused test, then the full suite, then rerun it “just to be safe”;
• keep expanding verification even after the relevant checks had passed.

The problem was not that the model was incapable. In many cases, it was capable enough to identify too many possible risks and did not know when to stop.

Prompt instructions such as “do not overthink” or “verify only once” helped with short tasks, but they were not reliable during longer runs. So I moved the constraint outside the prompt and implemented it with Codex Hooks and persistent state.

What Click does

For a software change, Click creates one compact execution contract containing:

• the expected outcome;
• in-scope and out-of-scope boundaries;
• behavior that must remain true;
• the smallest repository-aware implementation approach;
• a verification scale;
• a plain-language explanation.

The contract is shown first, and the user approves it in a later turn. The initial request is never treated as approval of an unseen contract.

After approval, Click can enforce the following observable behavior:

• block parallel update_plan calls;
• prevent repeated repository-wide inventory scans;
• reuse successful read and search evidence;
• block identical successful observations until the implementation changes;
• require one final verification batch within an approved budget;
• block a successful verification batch from being rerun unless the code changes;
• allow only one unchanged retry after a failed verification batch;
• keep the approved contract and observation ledger active across user turns;
• reject repeated staging of the same contract.

Verification budgets

Click supports three verification scales:

• quick: 1 unit
• focused: 4 units
• full: 10 units

Each check is classified as:

• targeted: 1 unit
• broad: 3 units
• deep: 5 units

The Hook does not blindly trust the submitted class. It infers a minimum cost from the actual argv and target scope.

For example:

• one exact test file or test node may be targeted;
• filters, multiple files, directories, packages, and full suites are at least broad;
• full integration, security, E2E, audit, or load-test suites may be deep.

This prevents a complete test suite from being submitted as a cheap targeted check.

Structured capabilities

During active work, Click uses versioned inspect, mutate, and verify requests with argv arrays.

Accepted commands are executed without a shell, so pipelines, redirects, command substitution, and shell wrappers cannot be hidden inside the capability request.

Click also detects when final verification unexpectedly modifies protected Git content. In that case, the verification result becomes stale instead of being recorded as successful.

Modes

Click supports:

• Always ON for supported software changes;
• Manual activation through @Click;
• a one-turn bypass;
• normal behavior for questions, explanations, and simple read-only inspection;
• a read-only review mode that does not require a build contract.

Installation

codex plugin marketplace add grapefruit0205/click
codex plugin add click@click

Repository:
https://github.com/grapefruit0205/click⁠

The current deterministic test suite passes on Ubuntu, macOS, and Windows.

I also built an isolated A/B harness that can compare correctness, token usage, elapsed time, repeated commands, repository rescans, planning calls, and verification counts against a no-plugin baseline.

However, I have not run the full paid repeated benchmark yet, so I am not claiming proven token or time savings.

Limitations
Click is a workflow guardrail, not a security sandbox.

It cannot fully observe:
hidden model reasoning;
hosted tools or tools outside the Hook matcher;
work concealed inside an allowed wrapper;
whether a new service, queue, or abstraction is semantically overengineered.

Its goal is intentionally narrower:
Prevent an already-capable coding agent from planning, inspecting, and verifying the same work more than necessary.

I would really appreciate feedback from Codex users and maintainers:
Does this problem match what you see in longer Codex tasks?

Would a verification budget be useful, or would it feel too restrictive?

Are there common build, test, lint, or inspection commands that this design may misclassify?

Is there a more idiomatic way to model cross-turn approval and persistent Hook state in Codex?
Thanks for taking a look.