LangChain jumped from 52.8% to 66.5% on Terminal Bench 2.0 by constraining their agent, not upgrading the model. Running at maximum reasoning budget actually scored worse. Three data points prove it: freedom is the enemy of AI agent reliability.
Two approaches. Same model. Different results:
# Approach A: Give the agent more freedom
→ Upgrade model, add more tools, increase context window
→ Remove guardrails so it "moves faster"
→ Result: unpredictable, rolls back 3x per session
# Approach B: Give the agent more constraints
→ Same model, same tools, same context
→ Add: verification loop, compute budget, context injection
→ Result: 52.8% → 66.5% on Terminal Bench 2.0 (LangChain, 2026)
Every time a team complains about Claude Code "doing the wrong thing," I ask the same question: what stopped it from doing that? The answer is always nothing. The agent had the capability. Nothing prevented the action.
The instinct is to want a smarter model. The fix is a tighter harness.
This is the Constraint Paradox: the more you restrict what your AI agent can do, the better it performs at what it should do.
Why does everyone assume "smarter model" is the answer?
Developers instinctively optimize for agent capability. Smarter model + more tools + fewer restrictions = better output. But this assumption conflates capability with reliability, and they're fundamentally not the same thing.
A senior developer with no code review, no CI/CD, no linting, and full production access will ship worse code than a junior developer working inside a strict pipeline. Not because the senior is less capable. Because unrestricted capability doesn't self-organize toward correct behavior. It just has a larger surface area for mistakes.
AI agents have the same problem, magnified. An LLM doesn't have intuition for "this feels wrong." It doesn't pause before a destructive command and think "wait, should I really do this?" Constraints provide that intuition externally.
OpenAI demonstrated this at scale. Their Codex team shipped roughly one million lines of production code with zero human-written lines over five months. Codex didn't succeed because it used a smarter model. It succeeded because it ran inside one of the most constrained environments in the industry: AGENTS.md files, reproducible dev environments, CI invariants, and mechanical verification.
The question isn't "how smart is your model?" The question is "how tight is your harness?"
Three data points that prove constraints beat capability
Evidence 1: LangChain Terminal Bench 2.0
LangChain improved their coding agent from 52.8% to 66.5% on Terminal Bench 2.0 by changing only the harness. Same model (gpt-5.2-codex). No fine-tuning. No model swap. Three harness changes:
-
Context injection via
LocalContextMiddleware— map the environment upfront -
Self-verification loop via
PreCompletionChecklistMiddleware— verify before marking complete - Compute budget management — cap reasoning to prevent timeouts
The counterintuitive part: running at maximum reasoning budget (xhigh) scored 53.9%, worse than the original baseline. The high setting scored 63.6%.
| Setting | Score | Change |
|---|---|---|
| Baseline (no harness changes) | 52.8% | - |
| Harness changes + high reasoning | 66.5% | +13.7pp |
| Harness changes + xhigh reasoning | 53.9% | +1.1pp (timeouts) |
More thinking didn't help. Better constraints did.
Evidence 2: Mitchell Hashimoto's AGENTS.md
Mitchell Hashimoto (creator of Terraform, Vagrant, Ghostty) treats his AGENTS.md as a failure log. Every single line exists because the agent made that specific mistake at least once:
"Each line in that file is based on a bad agent behavior, and it almost completely resolved them all" — mitchellh.com, 2026
Ghostty is one of the most productive AI-assisted codebases in the open source world. Hashimoto estimates agents run 10-20% of his working day in the background. And it runs on one of the most constrained harnesses. Not despite the constraints. Because of them.
Evidence 3: Claude Code's permission model
Claude Code defaults to read-only. You must explicitly allow write access, file creation, and command execution. This isn't a limitation. It's a design decision.
Instead of evaluating every possible action (including destructive ones), the agent operates within a bounded set of safe actions. When it needs to do something outside that set, it asks. That asking catches mistakes before they happen.
Compare this to an agent with full file system access from the start. It never pauses. It never asks. It just does — including rm -rf when it thinks cleanup is needed.
Why do constraints actually improve AI agent output?
Three mechanisms:
Mechanism 1: Constraints reduce the search space. An unconstrained agent evaluates every possible action, including destructive ones. A constrained agent only evaluates valid actions. Same reason chess engines play better with opening books: eliminating bad moves early means more compute spent on good ones.
LangChain's LocalContextMiddleware is search space reduction in practice. Instead of the agent spending steps figuring out its environment, the middleware injects that context upfront.
Mechanism 2: Constraints clarify intent. When you tell an agent "don't modify files in /config," you're not just preventing a bad action. You're giving the agent information about what matters. Constraints are communication that's harder to misinterpret than instructions.
An instruction says: "Be careful with config files." That's ambiguous. A constraint says: Hook blocks all writes to /config/**. No ambiguity. No interpretation required.
Mechanism 3: Hard stops beat soft warnings. A Hook that blocks git push --force doesn't require the agent to "decide" whether to follow the rule. The rule is enforced. The agent doesn't waste tokens weighing the instruction against other context.
LangChain's PreCompletionChecklistMiddleware is a hard stop. The agent cannot mark a task complete without running verification. It doesn't "decide" whether to verify. Verification is mandatory.
| Enforcement | Mechanism | Compliance | Example |
|---|---|---|---|
| Instruction | Soft context, weighted by LLM | 60-70% | "Don't force push" |
| Hook | Shell script, pre-action | 100% | Block force push |
| Middleware | Code in agent pipeline | 100% | Forced verification |
Won't constraints slow down development?
No. Unconstrained agents waste more time recovering from mistakes than constrained agents spend on guardrail checks.
# Unconstrained session
Agent runs → mistake at min 15 → rollback → retry → 50 min total
Useful work: 15 min (30% efficiency)
# Constrained session
Agent runs → blocked at min 15 → redirects → completes → 25 min total
Useful work: 25 min (100% efficiency)
A single bad agent decision (deleted file, force push, broken migration) costs 30 minutes of recovery. A Hook check takes 5 milliseconds.
LangChain's LoopDetectionMiddleware makes this concrete. It detects when the agent is stuck in repetitive edits and forces it to reconsider its approach. Without this constraint, the agent burns through tokens re-editing the same file. With it, the agent backs up and tries a different strategy.
The real cost isn't the constraint. The real cost is the recovery from what would have happened without it.
Where should you constrain (and where not)?
| Constrain (high cost to undo) | Don't constrain (low cost) |
|---|---|
File deletion, rm -rf
|
Variable naming choices |
git push --force |
Algorithm selection |
| Production database writes | Refactoring approach |
.env and secrets edits |
Comment style |
| CI/CD pipeline changes | Test structure |
Over-constraining is a real risk. If every file is protected, every command requires approval, and every edit needs pre-authorization, you've built a system that accomplishes nothing. The goal isn't zero risk. The goal is zero unrecoverable risk.
Claude Code's permission model gets this balance right. Read is unrestricted. Write requires approval. Destructive commands require explicit allowlisting. The agent explores freely but can't break things without your sign-off.
FAQ
What is the constraint paradox in AI agents?
The constraint paradox is the counterintuitive finding that restricting an AI agent's capabilities produces better output than giving it more freedom. LangChain demonstrated this by gaining 13.7 benchmark points through harness constraints alone. The mechanism: constraints reduce the agent's search space, clarify intent, and enforce rules deterministically.
Does more compute always improve AI agent performance?
No. LangChain's benchmark data shows running at maximum reasoning budget (xhigh) scored 53.9%, worse than the high setting at 63.6%. More compute caused timeouts that hurt overall performance. The optimal approach is budgeted compute with hard verification stops, not unlimited reasoning.
What's the difference between constraining and limiting an AI agent?
Constraining means removing dangerous or wasteful actions while preserving the ability to solve the problem. Limiting means reducing capability entirely. A Hook that blocks rm -rf is a constraint. Removing file system access entirely is a limitation. Constraints improve reliability. Limitations reduce usefulness.
How many constraints should an AI agent harness have?
Enough to prevent unrecoverable mistakes, not so many the agent can't work. The rule of thumb: constrain any action that would take more than 5 minutes to undo. Leave everything else to the agent's judgment. Start with 3-5 constraints and add only after real failures, following the failure log pattern.
Try it now: Open .claude/settings.json and check your current permission config. If the agent has unrestricted write access, add one PreToolUse Hook that blocks edits to .env and credentials. Test it: ask Claude Code to edit your .env file and confirm the hook blocks it.
What's your take — have you seen constraints improve your agent's output? Drop it in the comments.
Originally published on ShipWithAI. I write about Claude Code workflows, AI-assisted development, and shipping software faster with structured AI.
Top comments (0)