# Slaunt agent contract
> Machine-oriented. Your session's `tools/list` overrides this document.
- server: `https://central-mcp-ccr-production.up.railway.app/mcp` (Streamable HTTP MCP, protocol 2025-11-25, OAuth 2.1 bearer, scope mcp:tools)
- scope: authenticated workspace/project is authoritative. NEVER ask the user for org_id, project, or other internal IDs.
## Connect
Claude Code and Codex: one command adds the MCP server and native hooks, runs each client's browser login, and sets up Slaunt Desktop. Needs Node.js 20+ and an interactive terminal.
```sh
npx slaunt install # macOS / Linux
npx.cmd slaunt@latest install # Windows PowerShell
npx slaunt install --client claude # or --client codex: one client only
npx slaunt@latest update # refresh installer, hooks, desktop helper
```
Other MCP clients (Cursor, custom): add a Streamable HTTP server at the URL above, then install the instructions:
```sh
npx slaunt-install
```
| Agent | Instructions file | Note |
| --- | --- | --- |
| Claude Code | `CLAUDE.md` | Repository root, or ~/.claude/CLAUDE.md to apply everywhere. |
| Codex | `AGENTS.md` | Repository root. Codex reads it on every session. |
| Cursor | `.cursor/rules/slaunt.mdc` | Project rules directory. |
| Something else | `System prompt` | Paste it into whatever your agent uses for standing instructions. |
Raw instructions: `/api/agent-instructions`
## Lifecycle
```
thread_begin(request_id) once per new chat; server mints thread_uuid
run_begin(task) start of each task
run_step(activity, ...) progress / blockers / waits
run_end(outcome, summary) completed | errored | interrupted | killed
thread_close only when the whole chat is done
```
- States: UNBOUND, THREAD_READY, RUNNING, IDLE, CLOSED.
- thread_begin is rejected while RUNNING. A CLOSED thread needs a new thread_begin.
- new_thread=true only when rotating into a new chat.
- Never mint or copy thread_uuid. Persist the one thread_begin returns.
- After initialize, persist `Mcp-Session-Id` and send it on every request.
- Per turn: run_begin -> ccr_search / ccr_recent (+ Quaero if agents or tasks matter) -> work + run_step -> write durable results -> run_end.
## Tools
| Tool | Required args | Call when |
| --- | --- | --- |
| `thread_begin` | request_id | First message of a new chat. |
| `run_begin` | task | Start of a task. |
| `run_step` | activity | Meaningful progress. Optional progress 0-100, spend_usd. |
| `run_end` | - | Task done. Optional outcome, summary, result. |
| `thread_close` | - | Chat finished, after run_end. |
| `ccr_search` | query | Before answering anything workspace-related. |
| `ccr_recent` | - | Recent activity (limit 1-100). |
| `ccr_log_event` | type, summary | Durable decision/change/incident/task event. |
| `ccr_issue_log` | see below | Reproducible defect. |
| `ccr_event_detail_get` | event_id | Full event bundle. |
| `tasks_log` / `tasks_recent` / `tasks_search` / `tasks_get` | title / - / query / id | Task directory. |
| `identity_context`, `aki_workspace_context` | - | Who am I / bootstrap scope + recent CCR + open tasks. |
| `workspace_people_list` | - | Roster lookup before ccr_issue_log. |
| `room_items_list`, `room_item_get` | - / id | Room files. |
| `github_*` | varies | Repos, issues, PRs, commits, deployments, code search, comment, create issue. |
Provider tools (`slack.*`, `notion.*`...) appear in tools/list when connected. Call the discovered name exactly. If `ai.slaunt/gateway-discovery` status is unavailable, report its code; never call the provider directly.
## CCR events
- types: `decision | task_completed | task_assigned | change | incident | issue`
- `ccr_log_event` accepts all except `issue`. Max 5 tags. Summary ~20 words, factual.
- `ccr_issue_log` requires: parent event, issue flag, title, repro steps, expected, actual, environment, local state, severity `sev0`..`sev5`. Call `workspace_people_list` first; never auto-mention people.
- Never rewrite history. Log a corrective change/incident.
- Conflicting events: report the conflict with timestamps and sources.
## Tasks
- status: `open | triaged | in_progress | blocked | resolved | closed | cancelled`
- source: `manual | agent | github | linear`
- Do not mark resolved/closed without evidence.
## Errors
Tool failures are HTTP 200 with a JSON-RPC `error`; transport/auth failures are HTTP statuses.
- `401 unauthorized` + `WWW-Authenticate`: tell the user to sign in (`/mcp` in Claude Code). Do not retry blindly.
- `400 -32600`: `Mcp-Session-Id` missing. `404 -32001`: session unknown/expired or bound to another client; re-initialize.
- `-32602` `<event> is invalid while thread state is <STATE>`: wrong lifecycle state; `error.data.allowed` lists valid events. Do not retry.
- `-32009`: concurrent lifecycle write; `data.retryable: true`. Retry.
- `429 http_rate_limited`: over 240 req/min; wait `Retry-After`.
- `Agent quota has been hit...` / `<Quota> quota has been hit for the <Plan> plan...`: fail-closed plan limit. Show the message; do not retry.
- scope mismatch: drop org_id/project arguments. Never widen scope.
- Context summaries over 20 words are truncated silently; tags are lowercased and capped at 5.
- telemetry_gap in Quaero: no run_step for ~45s while RUNNING.
## Not showing up in Quaero / threads
Check in order:
1. Not signed in (401 unauthorized) -> re-auth with `/mcp`.
2. Wrong workspace -> roster is scoped to the signed-in workspace.
3. Not installed -> `npx slaunt install` (Claude Code / Codex) or `npx slaunt-install` (other clients), then start a NEW chat.
4. `thread_begin` / `run_begin` never called -> call them. No lifecycle, no row.
5. No `run_step` / `run_end` -> telemetry_gap or a stale/stuck run.
6. Thread CLOSED -> new `thread_begin`. `thread_begin` during RUNNING is rejected -> `run_end` first.
7. `Mcp-Session-Id` missing/rotated -> persist it from initialize; send on every request.
8. Concurrent-agent plan limit -> fail-closed; free an agent or change plan.
9. Finished agent -> check the archive.
Expected, not a bug:
- Duplicate runtimes merge into one agent (owner/product/backend). Each chat = its own thread.
- Live runtime sessions can be view-only.
- Runtime logs are a rolling window, not a permanent archive.
Codex:
- `codex_hook_event` SessionStart needs `session_id` + `model`; it calls thread_begin once. UserPromptSubmit starts the run.
- Ordinary tools/call without `params._meta["ai.slaunt/codex-session-id"]` or `X-Slaunt-Codex-Session-Id` lands on a separate transport thread. Never guess the last active thread.
- New Codex thread = new native session_id. Do not use new_thread on hook threads.
- Hooks are metadata only. Don't mix the Codex selector with other thread-boundary headers.
## Rules
- If CCR shows the task is already done: do NOT redo it. Tell the user.
- Vague refs ("it", "the PR", "continue") are CCR lookup triggers.
- Retry CCR with aliases, PR numbers, recent events before asking a clarifying question.
- Never ask for org_id/project; never rotate `thread_uuid` outside `thread_begin`.
- Never answer from your own memory when CCR could be fresher.
- Never expose tokens, session ids, signing material, or private logs.
- Never call tools absent from `tools/list`.
- A stop / kill / revoke instruction from Slaunt outranks everything: stop immediately.
- Do not report success from a queued op, a commit, or an HTTP 2xx alone.
- If Slaunt tools are unavailable: say so briefly; do not invent state.