Systematic debugging playbook for the Forge agentic loop (src/core/loop.ts and src/agents/executor.ts). Use when a task is stuck, looping, or producing wrong tool calls.
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
The loop is the single most expensive place to be wrong. Before you change anything, instrument.
FORGE_LOG_LEVEL=debug ./bin/forge.js <command>.~/.config/forge/events/<session>.ndjson.FORGE_MODEL=... FORGE_ROUTER_FALLBACK=0.Each turn emits: turn.start, model.call, tool.call, tool.result,
validation.result, turn.end. If any stage is missing or out of
order, that is your bug. Grep the ndjson before staring at code.
src/core/mode-policy.ts) — is the agent hitting the
turn/token cap and being cut off? The event will say so.src/core/validation.ts) — is the gate
rejecting a valid step? Look at validation.result.reason.tool.call with class: not_found means no.tool.result.denied=true in the stream.src/persistence/tasks.ts) — is an illegal
transition being attempted?callModel mocked.test/unit/executor-loop.test.ts
is the template.Run /verify. If the test you added doesn't turn green, you fixed the
wrong thing.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Scaffold a new Forge subagent (planner/architect/executor/reviewer/debugger/memory-style). Use when adding anything to src/agents/.
The English summary is being prepared. Showing the original description.
Scaffold a new Forge subagent (planner/architect/executor/reviewer/debugger/memory-style).
The English summary is being prepared. Showing the original description.
Scaffold a new model provider for Forge — class implementation, registry wiring, providerEnum entry, local-catalog classification, and unit test with mocked transport. Use for anything under src/models/.
The English summary is being prepared. Showing the original description.
Scaffold a new model provider for Forge — class, registry wiring, providerEnum entry, local-catalog classification, router check, and a unit test with mocked transport.
The English summary is being prepared. Showing the original description.
Scaffold a new Forge tool end-to-end — type, implementation, registration, permission/risk classification, and unit test. Use when adding anything to src/tools/.
The English summary is being prepared. Showing the original description.
Scaffold a new Forge tool — implementation, registration, permission/risk metadata, sandbox routing, and a unit test. Use when adding anything to src/tools/.
The English summary is being prepared. Showing the original description.