Connection
| Symptom | Cause | Fix |
|---|---|---|
401 invalid_token | Token missing or expired. Tokens are per client. | Claude Code: /mcp → slaunt → Authenticate. Codex: restart to re-login. |
400 session header required | Client isn’t keeping Mcp-Session-Id | Persist it from the initialize response |
404 Unknown MCP session | Session expired, or reused with another token or client | Re-initialize. If it happens every time, two clients are sharing a session. |
| Installer: entry already exists | A previous Slaunt config is present | Re-run with --overwrite-config |
Lifecycle and hooks
| Symptom | Cause | Fix |
|---|---|---|
run_begin is invalid while thread state is RUNNING | A run is already active, usually started by a hook | With hooks, don’t call run_begin from the model. Otherwise run_end first. |
thread_begin is invalid while thread state is RUNNING | Rotating threads mid-run | run_end, then thread_begin with new_thread: true |
run_step is invalid while thread state is IDLE | No active run | run_begin first |
Tool calls denied: runtime_stopped | Agent was stopped in Quaero or KillBar | Intended. A new prompt starts a fresh run. |
Tool calls denied: run_not_active | The UserPromptSubmit hook didn’t start a run | Restart the client so hooks and MCP come up together |
| Codex chats merge or split oddly | Hook and tool calls don’t share threadId | See Codex thread routing |
Tools and quotas
| Symptom | Cause | Fix |
|---|---|---|
| A documented tool isn’t listed | It’s conditional | Check the conditions |
| Provider tools missing | Gateway discovery failed or nothing connected | Read _meta["ai.slaunt/gateway-discovery"] in tools/list |
Agent quota has been hit | Concurrent agent limit | End idle sessions in Quaero or upgrade |
... quota has been hit for the ... plan | Monthly quota used | Wait for the reset (1st, UTC) or upgrade |
| Context summary cut off | 20-word limit | Shorten it |