# Supen Codex Tool Contract

This is the planned MCP tool contract for the Supen Codex plugin. The first implementation should keep these tools thin wrappers over the gateway API.

## Tools

### `supen_list_computers`

Returns visible Supen computers and their current availability.

### `supen_list_threads`

Input:

- `computer_id`

Returns Codex threads for a computer.

### `supen_read_thread`

Input:

- `computer_id`
- `thread_id`
- `limit`

Returns thread metadata, recent messages, runtime context, artifacts, browser links, and pending input when present.

### `supen_list_active_threads`

Input:

- `computer_ids`
- `include_idle`
- `limit_per_computer`

Returns active or attention-needed Codex threads across visible computers, plus per-computer errors when a daemon cannot be reached. This is the first tool SupenAgent should use for operational supervision across many machines.

### `supen_watch_thread_events`

Input:

- `computer_id`
- `thread_id`
- `after`
- `max_events`
- `timeout_ms`

Returns a bounded batch of Codex stream events for progress monitoring. This tool does not create durable subscription state.

### `supen_start_thread`

Input:

- `computer_id`
- `title`
- `task_workspace_folder`
- `model`
- `system_prompt_append`

Starts a new Codex thread on a computer.

### `supen_send_thread_message`

Input:

- `computer_id`
- `thread_id`
- `text`
- `turn_id`
- `files`

Sends a normal user message to a Codex thread.

### `supen_interrupt_thread`

Input:

- `computer_id`
- `thread_id`

Interrupts the current turn for a Codex thread. The daemon treats already-not-running threads as a completed no-op.

### `supen_archive_thread`

Input:

- `computer_id`
- `thread_id`

Archives a Codex thread on a computer.

### `supen_respond_input`

Input:

- `computer_id`
- `thread_id`
- `input_id`
- `text`

Responds to a specific pending input request.

### `supen_respond_approval`

Input:

- `computer_id`
- `thread_id`
- `approval_id`
- `approved`

Responds to a specific pending approval request.

### `supen_list_dev_servers`

Input:

- `computer_id`

Returns running dev servers for a computer.

### `supen_list_artifacts`

Input:

- `computer_id`
- `thread_id`

Returns artifacts and generated outputs associated with a thread when available.

### `supen_preview_file`

Input:

- `computer_id`
- `path`

Returns file preview metadata or bytes for image/file inspection.

## Team handoff tools

See also `docs/teams/handoff-protocol.md`.

These tools are the **primary orchestration surface**. A coordinator agent should use them (with a coordinator prompt) to inspect the roster, pick suitable idle members, propose/deliver handoffs, and close work via reports. Do not assume a human workflow UI will make those decisions.

### `team_status`

Input:

- `team_id` — Team slug or uuid (default `default`). User-scoped Gateway store; not a computer.
- `include_runtime` — optional, defaults to `true`. Adds each member's pinned-thread status, compact subagent summary, and read-only Codex quota/capacity snapshot.

Returns Team graph/members, open handoffs, and recent Team events from Gateway `/api/gateway/teams/:teamId`. With runtime included, `memberRuntime` is a derived live view: `busy`, `needsAttention`, observed `harness` / `modelLabel`, `capabilities` (`allowed` / `forbidden` / optional `notes`; `source` is `member` when `team_members.expectations` is set, else `role_default`), pinned Codex `thread` or bound tmux `seat`, compact structured `subagents` when the harness reports them, `work` (current execution item, plan, artifacts), and `capacity`. Codex capacity includes remaining quota windows, freshness, and members sharing the same known account source; Cursor/Kimi capacity is explicitly unreported rather than borrowing the computer's Codex quota. Also returns `promptPacks` pointers into the Supen skill `references/` packs. Runtime lookup errors are returned in `runtimeErrors` instead of hiding the Team snapshot.

Quota is observational. This tool never switches auth profiles, edits Codex login state, or elects a replacement member.

### `team_report`

Input:

- `team_id` — optional, default `default`
- `summary`
- `member_id`
- `thread_id`
- `computer_id` — optional reporting context only (execution target, not store host)
- `handoff_id` — optional; when set (or when `thread_id`/`member_id` match open handoffs), closes those handoffs as `done` (or `blocked` if `blockers` present)
- `blockers`
- `artifacts`

Appends a report event to the Team timeline and advances matching handoff status.

### `team_handoff`

Input:

- `team_id` — optional, default `default`
- `from_member_id`
- `to_member_id`
- `kind` — `request_review` | `implement` | `test` | `merge` | `custom`
- `summary`
- `source_thread_id`
- `deliver`
- `context`

Proposes a handoff packet via Gateway. When `deliver` is true, Gateway validates the caller can access the target member's computer (`requestCanAccessComputer`), then relays a Codex turn through the existing daemon bridge. User-visible text stays short; packet details go as turn-scoped developer instructions.

### `team_open_thread`

Input:

- `computer_id`
- `thread_id`
- `text`
- `developer_instructions`
- `title`

Creates or continues a Codex thread for handoff delivery on the target computer.

### `team_set_expectations`

Input:

- `team_id` — optional, default `default`
- `member_id` — required
- `allowed` — optional string tags (e.g. `review`, `docs`)
- `forbidden` — optional string tags (e.g. `code_edit`)
- `notes` — optional short note
- `clear` — when true, clears member expectations (role defaults apply again)

Persists soft capability bounds on the member via Gateway graph replace (`team_members.expectations`). Not a policy engine — coordinators and handoff instructions should honor these hints.