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 emitting 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 most expensive place to be wrong. Instrument before you change anything.
FORGE_LOG_LEVEL=debug ./bin/forge.js <command>
Capture the session id. Events land in
~/.config/forge/events/<session>.ndjson.
If the bug only reproduces against a real provider, pin the model and disable router fallback:
FORGE_MODEL=... FORGE_ROUTER_FALLBACK=0 ./bin/forge.js <command>
Each turn emits: turn.start, model.call, tool.call,
tool.result, validation.result, turn.end. Missing or
out-of-order events are your bug.
src/core/mode-policy.ts) — is the agent hitting
turn/token cap?src/core/validation.ts) — is a valid step
being rejected?tool.call with class: not_found means no.tool.result.denied=true.src/persistence/tasks.ts) — illegal
transition attempted?Template: test/unit/executor-loop.test.ts. Mock callModel. If the
test you add doesn't turn green after your fix, you fixed the wrong
thing.
verify.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.