Troubleshooting
Chat Works, But Tools Don’t Run?
Fix the high-friction “agent replies normally, but file/command tasks hang” loop in under 5 minutes.
A recurring support pattern is: “My agent is talking fine, but git/file/tool actions freeze or never finish.” This is usually a runtime/session execution issue, not a prompt-quality issue.
Core rule: treat “chat is alive” and “tool execution is healthy” as two separate systems. One can work while the other is stalled.
2-minute isolation checklist
- Run a tiny canary tool task (for example: list one folder).
- If canary hangs, open a fresh session and retry the same tiny task.
- If fresh session works, your old session is likely execution-stuck.
- If fresh session also fails, suspect runtime/container/gateway health.
- Avoid retry spam while stuck — it usually makes diagnosis harder.
Known symptoms of execution-layer freeze
- Normal chat answers still come back quickly.
- Tool tasks (file reads, git commands, pushes) stay pending or timeout.
- Approvals may appear repeatedly without task completion.
- A restart/new session temporarily clears the issue.
Safe recovery flow
- Stop queueing new heavy tasks.
- Open fresh chat/session and run one tiny canary first.
- If canary passes, re-run your real task in the fresh session.
- If canary fails, perform runtime restart/health checks before retrying.
- If still failing after restart, escalate with clean evidence packet (below).
Don’t trust “done” without proof: require a verifiable output (file path, diff snippet, command result) before assuming the task completed.
Copy/paste canary prompt
Run one tiny tool canary task only:
1) List files in the current workspace root.
2) Return exactly 5 filenames.
3) If any step fails, return the exact error text and stop.
Do not run any additional commands.
Proof-first completion contract
For every task, respond in this format:
- Status: success or failed
- Evidence: exact output/path/diff proving the action happened
- Verification: one check that confirms state changed as expected
If evidence is missing, treat task as not completed.
Support-ready escalation packet
Execution freeze report
What still works: (chat replies yes/no)
What fails: (file/git/tool tasks)
Tiny canary result: (pass/fail + exact output)
Fresh session canary result: (pass/fail)
Restart attempted: (yes/no + what was restarted)
Time observed (timezone):
Recent exact error text:
Bottom line: if chat works but tools hang, isolate with one tiny canary, move to a fresh session, then escalate only with exact evidence.