loop_guard
Prove the work is done — don't trust transcript self-grading.
Zephex is a hosted Model Context Protocol (MCP) server that gives AI coding agents independent verification through loop_guard — real tests, lint, typecheck, HTTP, and lockfile sensors — plus nine other tools and one API key for safer agent loops.
When to use
- An agent claims done, fixed, deployed, or all tests pass — verify before you ship.
- You need independent proof that lint, tests, or typecheck actually pass.
- A deploy or staging URL should be probed — not just described in chat.
- Multi-step fixes where the agent might self-grade from its own transcript.
When not to use
- You need package CVE or upgrade migration detail — use check_package with task=upgrade.
- You only need to scope which files to edit — use scope_task first.
- You want long-form reasoning across many steps — use keep_thinking.
- You need a quick registry exists check — use check_package with task=check.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | No | User's exact words when goal/claim unclear. |
| goal | string | No* | Stopping condition (e.g. tests pass and lint clean). *One of task/goal/claim required. |
| claim | string | No | What the agent said it finished. |
| path | string | No | Absolute dir or github:owner/repo. |
| mode | enum | No | auto | sensors | prove | full |
| url | string | No | HTTPS URL for deploy/live checks. |
| guard_session_id | string | No | Chain follow-up iterations. |
| detail_level | enum | No | agent | human |
| profile_path | string | No | .zephex/loop/profile.json when customized. |
| profile_overrides | object | No | One-call rule patch e.g. test_command. |
Limits: Hosted sensors need path or url. Package upgrade intel is check_package task=upgrade, not loop_guard. Respect max_guard_calls_per_task from profile.
Try it — copy a prompt
Paste into Cursor, Claude Code, Windsurf, VS Code, or any editor with a hosted MCP connection.
Before you call it
- Zephex API key and hosted MCP.
- Absolute project path or github:owner/repo for code checks.
- HTTPS url when verifying deploy/live behavior.
Token and request cost
loop_guard responses are typically 400–900 tokens — sensor output plus next_prompt. Budget one call per done-claim; chain with guard_session_id on the same task. Free tier includes 555 requests/month across all ten tools.
Example
{ "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "loop_guard", "arguments": { "goal": "auth tests pass and lint clean", "claim": "fixed the login redirect bug", "path": "/Users/dev/my-app", "mode": "auto" } }}Response shape
{ "loop_status": "CONTINUE", "prove_status": "PARTIAL", "trust_score": 0.42, "next_prompt": "loop_guard did not pass. Fix these before claiming done: …", "checks": [{ "type": "test_run", "status": "FAIL", "summary": "2 tests failed" }], "proof_url": "https://zephex.dev/proof/…", "guard_session_id": "gs_…", "iteration": 1}Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| Verify done/deployed/fixed claims | loop_guard | keep_thinking |
| Package CVE + migration steps | check_package (task=upgrade) | loop_guard |
| Minimal files for a task | scope_task | loop_guard |
| Long investigation memory | keep_thinking | loop_guard |
What it can do in your codebase
- Independent sensors — tests, lint, tsc, HTTP, lockfile — not agent self-report
- loop_status — CONTINUE, DONE, or BLOCKED for dev loops
- prove_status — SAFE, PARTIAL, BROKEN, or UNVERIFIED for claims
- trust_score — 0–1 confidence from check results
- next_prompt — agent-ready fix list when checks fail
- proof_url — signed receipt link for audit trail
- guard_session_id — chain follow-up iterations on the same task
- zephex-engineer-v1 profile — default test/lint commands applied invisibly
- profile_overrides — one-call patch e.g. test_command without a file
- Honest UNVERIFIED when sensors cannot run — agents must not fake pass
Common response fields
Why teams use it
Real checks, not chat
Runs test, lint, and typecheck commands from your profile — independent of whatever the agent said passed.
Deploy verification
HTTPS url probes for staging/production claims — form works, page loads, status codes.
Session chaining
Pass guard_session_id on follow-up calls so prior verdicts and iteration count persist.
Pairs with scope_task
Scope files first on multi-file edits, then loop_guard after the agent claims done.
What it looks at vs skips
- Test runner (profile test_command)
- Lint + typecheck (profile commands)
- HTTPS live URL probes
- Lockfile / package_installed parse
- Package CVE or breaking-change research — check_package task=upgrade
- Whole-repo architecture maps — explain_architecture
- Approving done claims without running sensors
Task modes
| task | What you get |
|---|---|
| auto | Infers sensors vs prove from task/goal/claim/url (default). |
| sensors | Run repo checks: tests, lint, tsc, lockfile, file_contains. |
| prove | Evaluate a specific claim against sensors and live URL. |
| full | Extended prove path (Phase B — may be partial on hosted). |
Mode options
How it fits your workflow
- scope_task — minimal files before multi-file edits
- Agent implements the fix
- loop_guard — verify tests, lint, or live URL before telling user done
Troubleshooting
- UNVERIFIED checks → add path for repo sensors or url for live probes.
- BLOCKED with no path → pass absolute project root or github:owner/repo.
- CONTINUE after fixes → re-call with same guard_session_id.
- 429 / slow → one verification per iteration; respect max_guard_calls_per_task.
How to verify it works
- Connect Zephex MCP; confirm loop_guard in tools/list.
- Ask: “loop_guard — goal: tests pass, claim: auth fix is done, path: <workspace>.”
- Response should include loop_status, trust_score, checks[], and next_prompt or human_summary.
Common questions
Billing and plan limits: FAQ, usage limits.
When should I call loop_guard?
After any agent message containing done, fixed, deployed, installed, or tests pass. loop_guard runs real sensors before you tell the user work is finished.
What is the difference between loop_guard and keep_thinking?
keep_thinking persists structured reasoning across steps. loop_guard runs independent verification — tests, lint, HTTP — and returns CONTINUE/DONE/BLOCKED with a trust_score.
Does loop_guard replace check_package for upgrades?
No. Package CVEs, breaking changes, and migration steps live in check_package with task=upgrade or task=security. loop_guard verifies implementation work (tests pass, lint clean, site works).
What are the main response fields?
Ten fields agents rely on: loop_status, prove_status, trust_score, next_prompt, human_summary, checks[], proof_url, guard_session_id, iteration, and intent_detected.
How do I chain multiple verification passes?
Pass guard_session_id from the first response on every follow-up loop_guard call for the same task. iteration increments and prior_verdict is available server-side.
What path should I pass?
Absolute directory to the project root on the machine where code runs, or github:owner/repo for remote analysis. Without path, repo sensors may return UNVERIFIED.
How do I use loop_guard with Cursor?
With Zephex in .cursor/mcp.json, paste: “loop_guard goal: auth tests pass claim: login fix done path: <workspace>.” Use next_prompt from the response — do not self-grade from chat.
Before multi-file edits: scope_task for minimal focus files, then loop_guard after the agent claims done.
Billing: Each tool call counts as one request on your Zephex plan (Free includes 555 requests/month). See usage limits for tier details. Usage limits.
keep_thinking tracks reasoning; loop_guard runs real sensors — tests and lint, not transcript self-grading (see also keep_thinking.
For AI agents (JSON)
{"tool":"loop_guard","when":"after done/fixed/deployed claim","need":"goal or claim plus path or url"}