DEV-104-1.1
The Agentic Loop Under the Hood: Tools, Context & Control
Verified current as of November 14, 2026
The beginner track describes Claude Code as a loop: you ask, it proposes, you approve, it acts. That mental model is correct, but it hides the machinery you need to control once you're shipping real Next.js and Supabase code. Under the hood, Claude Code is an agentic loop: a model that repeatedly reasons about your request, calls tools, reads the results, and decides what to do next — until it judges the task done. Understanding that loop is the difference between a tool that occasionally surprises you and one you can steer deterministically.
The loop is just model → tool → result → model
Each turn, the model receives the full conversation plus your project context, then emits either text or a tool call — read a file, run a shell command, edit a file, grep, fetch a URL. The harness executes the tool, feeds the output back, and the model runs again. There's no hidden intelligence beyond this. The agent feels capable because the loop compounds: a grep, then a Read, then an Edit, then npm test, each step informed by the last.
This is why specificity in the request changes the trajectory of tool calls. "Fix the auth bug" forces the model to spend turns discovering context. "The Supabase session is null in middleware.ts after the OAuth redirect — check the cookie handling" lets it jump straight to the right file.
Context is the budget you're actually managing
Everything the model knows lives in its context window: your messages, file contents it has read, tool outputs, and the CLAUDE.md files that auto-load. This is finite, and it degrades. Reading a 2,000-line generated migration to answer a one-line question burns budget you'll want later. Two production habits:
- Scope reads. Point the agent at the file and symbol, not the directory.
- Use
CLAUDE.mdas persistent, cheap context. Conventions, commands, and gotchas placed there load every session — far cheaper than re-explaining each time.
# Give the agent a fast, scoped feedback loop instead of a vague "make it pass"
npm run typecheck && npm run test -- src/lib/auth.test.ts
When the agent can run that itself, the loop self-corrects: it edits, runs the command, reads the failure, and edits again — no round trip through you.
Control: permissions, MCP, and the danger zone
Tools are the agent's hands, and you decide which hands it has. Allowlisting safe commands removes approval friction; everything irreversible should still prompt. MCP servers extend the toolset — the Supabase, GitHub, and Stripe integrations on this stack are MCP tools — and they inherit the agent's reach. That cuts both ways.
Save this as .claude/settings.json to let the agent run your checks freely and gate the rest (settings files are strict JSON, so no comments inside the file):
{
"permissions": {
"allow": ["Bash(npm run test *)", "Bash(npm run typecheck)"],
"ask": ["Bash(npx supabase db push *)"]
}
}
The permission mode sets the baseline: as of November 2026 the main modes are Manual (asks before edits and most commands), Accept edits, Plan (read-only until you approve a plan), and Auto (a classifier reviews actions instead of you; recent versions start in Auto in the terminal and VS Code). Shift+Tab cycles them. Your allow/ask/deny rules apply on top of whichever mode you're in.
The engineered request
fix the auth bug
Bug: after the Google OAuth redirect, `supabase.auth.getUser()` returns null in middleware.ts, so signed-in users get bounced to /login. Scope: middleware.ts, lib/supabase/server.ts, app/auth/callback/route.ts. Don't read .env files. Reproduce first: tell me the exact steps or test that shows the bug before changing anything. Then fix it and verify with: npm run typecheck && npm run test -- src/lib/auth.test.ts Done means: the test passes, and you can explain in two sentences why the session was missing. If the cause is outside those three files, stop and tell me instead of expanding the change.
What each element changes: the symptom and file scope cut the discovery turns; "reproduce first" stops a fix for the wrong bug; the exact verification command closes the loop; "stop and tell me" caps the blast radius of the change.
Pitfalls that bite in production
- The agent stops too early. If your test command isn't in context, it can't verify its own work. Always hand it the loop that proves "done."
- Stale context. After a big refactor, earlier file reads in the window are now wrong. Start a fresh session (
/clear) for the next task rather than fighting outdated state. - Over-broad tools. A connected Stripe MCP pointed at a live account will act on a live account. Match tool authority to the blast radius you can tolerate.
The agent is only as good as the loop you build around it: tight feedback, scoped context, deliberate permissions.
- The loop can run long. Every tool call uses context and plan limits; scope the request and the verification command.
- Self-verification is only as good as the tests. A passing test that doesn't cover the bug proves nothing; ask Claude to show the failing test first.
- Mode defaults vary by version and plan, as of November 2026; check the status line before assuming you'll be asked.
⌨️ Exercise
Take a real bug in your Next.js app. Write a CLAUDE.md entry with your exact typecheck and scoped test commands, add them to the allow list in .claude/settings.json, then send a request shaped like the engineered prompt above. Watch the loop: count how many tool calls it makes before declaring done, and confirm it ran your test command unprompted.
- Claude Code is a loop: model → tool call → result → model, until it judges the task done.
- Specific requests (symptom, files, verification command) change which tools it calls.
- Context is a budget: scope reads, use CLAUDE.md for durable conventions, start fresh after big changes.
- Permission mode sets the baseline; allow/ask/deny rules decide the details.

