mirror/docs/mcp-contract.md

# MCP tool contract

The local server stores and projects intent state only. It does no domain task work, planning, host permission management, file editing, testing, or delivery.

All tools return both a concise text block and `structuredContent` with `ok`, `schema_version`, `operation`, `project_id`, `task_id`, and an operation-specific result or structured error. Inputs are strict; unknown keys are rejected.

Every project-scoped tool accepts an optional `project_root`. The server advertises Codex's experimental `codex/sandbox-state-meta` capability and uses the host-provided `sandboxCwd` as the authoritative root when present. Malformed advertised metadata returns `PROJECT_ROOT_METADATA_INVALID`; a conflicting explicit root returns `PROJECT_ROOT_MISMATCH`, both before state access. Roots must be absolute existing local directories, and Windows UNC/device namespaces are rejected before filesystem resolution. On another MCP host, an explicit existing local root is accepted; if it is omitted, the server accepts exactly one advertised local file root and otherwise fails closed with `PROJECT_ROOT_REQUIRED`. The service stores only the canonical-root hash, exposes no global task search, and still requires a task UUID for task-level reads.

The server also exposes one static read-only MCP resource, `intent-loop://skill/intent`. It returns the actual bundled `skills/intent/SKILL.md` as `text/markdown`. This is a host-compatibility fallback for Windows sandboxes that discover a plugin Skill but deny direct shell reads from the installed cache. It contains no task data and introduces no second policy source.

## Tools

| Tool | Required intent and effect |
| --- | --- |
| `intent_start_task` | Start or associate a task with the current host-bound project and optional host session ID; private mode requires that hidden host token. Returns task UUID and compact empty/current snapshot. |
| `intent_get_snapshot` | Read a capped current snapshot, unresolved disputes/unknowns, stale warnings, and resolved storage location. No mutation. |
| `intent_add_explicit` | Add an atomic statement directly expressed or confirmed by the user. Requires a user-event source and `direct_statement` or `confirmed_candidate`; never accepts tool/evidence source kinds. |
| `intent_add_inference` | Add an agent inference with required numeric confidence and minimal source. It remains visibly inferred. |
| `intent_add_evidence` | Add result feedback or external/tool evidence. Evidence remains evidence even when compelling. |
| `intent_mark_unknown` | Add a first-class unknown with the decision it affects. |
| `intent_mark_dispute` | Add a disagreement referencing two or more claim IDs or an explicit free-standing disagreement. It does not choose a winner. |
| `intent_replace_claim` | Atomically add a corrected claim and supersede one or more existing claims while preserving their source history. |
| `intent_invalidate` | Append invalidation for a claim with reason and source. The claim leaves the current projection. |
| `intent_list_candidates` | Read unconfirmed Hook/result/history candidates. It never promotes them. |
| `intent_export` | Return either a compact human summary or one portable versioned task graph. Default output is structured content, not a file write. |
| `intent_import` | Validate and explicitly import a portable graph. Preserves provenance and relationships, labels the import as incomplete external history, and never silently merges conflicts. |
| `intent_delete` | Physically delete one claim or task after an exact confirmation token; verifies views, mappings, exports, and persistent bytes. |
| `intent_set_mode` | Set task `on`, `private`, or `off`. Private semantics are process-local; a hashed control marker suppresses Hooks and makes restart fail closed. |
| `intent_status` | Report server/schema versions, runtime mode, resolved storage directory, corruption status, the real aggregate Hook candidate count, and private-control counts without returning claim content. Read-only status does not create storage. |

## Mutating-tool invariants

- Statements are redacted and capped at 500 characters; source excerpts at 160.
- `inferred` requires confidence; no other status accepts model confidence.
- Tool/external results cannot use `intent_add_explicit`.
- Replacement and invalidation target active records in the same task/project. A user-explicit claim can be replaced only by direct user-explicit input and invalidated only by a direct user event.
- Long-term inferred claims cannot be promoted directly; they become candidates until the three-task plus confirmation rule is met.
- `private` never writes semantic content to disk; it does write the hashed suppression control described above. `off` rejects semantic reads and writes with a non-blocking status result.
- Task-scoped mutations deduplicate the same `request_id` inside the storage lock, including across MCP processes. Starting a new task is intentionally not advertised as idempotent.

## Hook-only command surface

Hooks invoke a small local CLI, not MCP tools exposed to the model:

- `hook session-start`: load same-project direct user-event/user-explicit context or output nothing;
- `hook user-prompt`: record only event ID/hash and candidate metadata when mode is on;
- `hook post-compact`: verify state and flag recovery for the next SessionStart;
- `hook stop` / `hook session-end`: record only hashed candidate outcome metadata.

Every Hook catches all errors, emits `continue: true`, and exits within its timeout. No Hook calls the network, reads a transcript path, blocks a prompt, sets user satisfaction, or promotes a candidate.

## Manual Skill entry points

The `intent` Skill maps the requested entry points to these tools:

- `/intent start` → start/associate;
- `/intent show` → snapshot;
- `/intent correct` → replacement or invalidation after one low-burden clarification if necessary;
- `/intent feedback` → result evidence followed by keep / implementation change / intent change / uncertain classification;
- `/intent forget` → explicit deletion confirmation and delete;
- `/intent export` → portable export;
- `/intent off` → task-level off.

If the installed surface exposes skills through `$intent` rather than a direct `/intent` alias, the Skill must still accept the same subcommands in ordinary conversation. Exact command discoverability is an E2E item, not an assumed fact.