---
title: Model Context Protocol (MCP) tools
description: The public Model Context Protocol (MCP) tool surface exposed by Ennodia.
---

This page describes the tools exposed by the Ennodia Model Context Protocol
(MCP) server. The normal entrypoint is `ennodia_run`. It starts a visible
orchestration and returns a run ID. Use `ennodia_get_run` to poll status,
events, child task IDs, Judge + Result Advisor state, and the final answer.

## Tool sets

An agent loads every tool definition into each session where Ennodia is configured, even when the session never calls Ennodia.
By default, Ennodia loads six core tools, about 10,000 characters of definitions.
They cover handing work to one agent or a team, Compare, waiting, cancelling, and run history.

The full set adds 20 tools for raw tasks, compositional slices, Plan Advisor, budget estimates, separate Compare calls, and skill installation.
It loads about 46,000 characters of definitions.
Set `ENNODIA_TOOLS=all` in the server's environment, or add `--tools all` to its arguments:

```json
{
  "mcpServers": {
    "ennodia": {
      "command": "npx",
      "args": ["-y", "ennodia", "--tools", "all"]
    }
  }
}
```

An unknown `--tools` value stops the server with an error. An unknown `ENNODIA_TOOLS` value prints a warning and loads the core set.

### Approvals

Tools that only read declare the MCP `readOnlyHint` annotation. Clients such as Codex run them without an approval prompt, so polling a run never waits for approval.
Tools that start agents declare `openWorldHint`, because their workers call model providers. Their workers can change files when the caller allows it, so they claim neither read-only nor harmless.

Headless Codex, such as `codex exec`, never asks for approval. It refuses any tool that needs one.
To let it start Ennodia runs, add this to `~/.codex/config.toml`:

```toml
[mcp_servers.ennodia.tools.ennodia_run]
approval_mode = "approve"
```

This setting approves Ennodia runs only. Codex's sandbox and its other tools keep their settings.

## Common workflows

| Goal | Tool sequence | Tool set |
| --- | --- | --- |
| Check local setup | `ennodia_list_harnesses` | core |
| Start a visible end-to-end run | `ennodia_run` -> `ennodia_get_run` | core |
| Inspect terminal receipts after restart | `ennodia_history` | core |
| Preview route and cost | `ennodia_estimate_budget` | full |
| Preview compositional shard cost | `ennodia_estimate_compositional_budget` | full |
| Request a tailored team, inspect it, then launch it | `ennodia_start_plan_advice` -> `ennodia_get_plan_advice` -> `ennodia_start_advised_plan` | full |
| Start focused review shards | `ennodia_start_compositional` -> `ennodia_get_compositional_status` | full |
| Debug raw child tasks | `ennodia_start` -> `ennodia_get_task` | full |
| Judge completed outputs and advise on the result | `ennodia_start_compare` -> `ennodia_get_compare` | full |
| Install bundled skills | `ennodia_list_skills` -> `ennodia_install_skills` | full |

For harness IDs and setup notes, see
[Supported Harnesses](/docs/reference/supported-harnesses/). For budget request
examples, see [Budgets and Limits](/docs/guides/budgets-and-limits/).

## Shared behavior

`ennodia_plan`, `ennodia_estimate_budget`, `ennodia_start`, and `ennodia_run`
use local harness discovery plus either a caller-provided `category` or a
lightweight keyword fallback. Pass `category` when the agent caller knows
the task type. Pass `refresh: true` to re-scan installed commands before
planning or starting work.

`ennodia_start` and `ennodia_run` also accept `skillIds`. Ennodia treats skills
as native Agent Skills: folders containing `SKILL.md`, installed in paths
supported by each harness. It does not inline full skill content into the
delegated prompt. Task and run views include selected skill metadata in
`appliedSkills`.
This metadata records the request. It does not prove that the native agent loaded or followed the skill.

`ennodia_estimate_budget`, `ennodia_estimate_compositional_budget`,
`ennodia_start`, `ennodia_run`, `ennodia_start_compare`,
`ennodia_start_plan_advice`, and `ennodia_start_advised_plan` support a `budget`
object for local preflight enforcement. Budgeting is an input-token estimate
plus child-task count guard. It does not claim to know provider billing, output
tokens, cache behavior, harness-internal context, or private subscription quota.

### Routing hints

Development versions of `ennodia_run` and `ennodia_start` accept optional `reasoningEffort` for Codex workers, forwarded through the native `model_reasoning_effort` configuration. Other adapters reject an explicit setting. Omission preserves native defaults. This field does not configure comparison agents.

Task and run views record the requested value. Model and CLI support remain authoritative.

Ennodia uses `category` before keyword classification. Valid categories are
`code`, `research`, `browser`, `image`, and `general`. The fallback classifier
uses strong browser, image, code, and research signals. Bare words such as
`review` or `page` do not route on their own. Pass `harnessId` to skip
adapter choice and target a specific adapter.

`harnessId` forces a specific adapter. Current adapter IDs are:

Each adapter starts a supported command-line interface (CLI).

| ID | Tool |
| --- | --- |
| `claude-code` | <span class="agent-logo agent-logo--claude-code" aria-hidden="true"></span>Claude Code |
| `codex` | <span class="agent-logo agent-logo--codex" aria-hidden="true"></span>Codex CLI |
| `opencode` | <span class="agent-logo agent-logo--opencode" aria-hidden="true"></span>OpenCode |
| `kilo` | <span class="agent-logo agent-logo--kilo-code" aria-hidden="true"></span>Kilo Code |
| `kiro` | <span class="agent-logo agent-logo--kiro" aria-hidden="true"></span>Kiro CLI |
| `cline` | <span class="agent-logo agent-logo--cline" aria-hidden="true"></span>Cline CLI |
| `hermes-agent` | <span class="agent-logo agent-logo--hermes-agent" aria-hidden="true"></span>Hermes Agent |
| `antigravity` | <span class="agent-logo agent-logo--antigravity" aria-hidden="true"></span>Antigravity |

Fields named `maxOutputChars`, `maxAnswerChars`, or `maxCandidateChars` bound
returned text. `0` omits that text while still returning status, IDs, timing,
and character counts.

For task views, `maxOutputChars` bounds each of `stdout`, `stderr`, and `finalMessage`.
`includeOutput: false` omits their text. `hasOutput` and `finalMessageChars` remain available in compact views.
`hasOutput` includes captured diagnostic output. It does not establish correctness or a useful answer.

A worker CLI can stop at startup when another instance holds its local state, as OpenCode does with its database.
Ennodia restarts that start up to three times, records a `restart` task event, and reports `startupRestarts` in the task view.
Restarts keep the original deadline.

On macOS and Linux, tasks own process groups. Cancellation sends TERM, then KILL after a bounded grace period.
Cleanup also removes descendants that remain in the owned group after the parent exits.
Processes that create a separate session can escape that group.
On Windows, cleanup signals the direct child process.
Closing the MCP input stream shuts down active work.

Raw and compositional batch starts cancel earlier workers if a later spawn fails.
Active runs retain child evidence until comparison and receipt capture finish.

### Media review

Ennodia transports text prompts with local file paths. Native media inspection depends on the selected harness, model, available tools, and permissions.
Discovery and Plan Advisor expose optional, bounded `inputGuidance: string[]` for adapter observations and input advice.
This guidance does not guarantee successful ingestion or model access.

Media prompts also receive preparation guidance at worker launch, recorded by an `input-guidance` task event.
Budget estimates include this added prompt text.
Automatic native-audio routes suggest one worker without comparison. Keyword routing does not verify the worker's native access.
For Antigravity, see [supported harnesses](/docs/reference/supported-harnesses/#antigravity) for the text-only wire format and scoped native-media observations.

1. Run a small native-media probe before launching a larger review or comparison.
2. Include exact local files, requested ranges, and the reference in each worker prompt.
3. Match excerpts, playback level, and reference material across audio candidates.
4. Request the model, inspected files and ranges, native tool results, errors, and excerpt-specific findings.
5. Retain task IDs and available terminal history receipts with the final assessment.

Successful media ingestion and excerpt-specific observations support a native listening claim.
Transcription, digital signal processing (DSP), and text-only judges provide separate evidence. Label each method and any fallback explicitly.
A Judge's comparison of written reports does not establish that the Judge inspected the source media.
Task output and history receipts are bounded. They do not provide complete transcripts or a permanent audit record.

## Discovery and planning

### `ennodia_list_harnesses`

Detects supported local artificial intelligence (AI) tools and reports
availability, runnable state, command path, version, capabilities, and adapter
notes. Optional `inputGuidance` contains a bounded string array of input advice and scoped observations.

Version probes have bounded deadlines. A failed probe appears in adapter notes without blocking other discoveries.
`runnable` means Ennodia found an executable adapter. Authentication and requested model access still require a real task.

| Input | Default | Meaning |
| --- | --- | --- |
| `refresh` | `false` | Ignore the short discovery cache and re-scan. |

Use this first when a client setup, command path, or adapter is not behaving as
expected.

### `ennodia_list_skills`

Discovers native Agent Skills from supported harness locations, plus bundled
Ennodia skills that can be installed into those locations:

- Codex and agent-compatible: `.agents/skills`, `~/.agents/skills`
- Claude Code: `.claude/skills`, `~/.claude/skills`
- OpenCode native: `.opencode/skills`, `~/.config/opencode/skills`
- OpenCode compatible: `.agents/skills`, `~/.agents/skills`,
  `.claude/skills`, `~/.claude/skills`
- Antigravity: `.agent/skills`, `~/.gemini/antigravity/skills`
- Ennodia bundled installable skills under `skills`

The list response returns summaries, searched directories, installation
metadata, and load warnings. It does not return full instruction text.

| Input | Default | Meaning |
| --- | --- | --- |
| `cwd` | server process cwd | Optional working directory to locate project-specific skills. |

### `ennodia_install_skills`

Installs bundled Ennodia skills into native harness skill directories. It
defaults to `dryRun: true`, so callers can inspect planned writes first.

| Input | Default | Meaning |
| --- | --- | --- |
| `skillIds` | all bundled | Bundled skill IDs to install. |
| `harnessIds` | Codex, Claude Code, OpenCode, Antigravity | Native harness locations to target. |
| `scope` | `project` | `project` or `user`. |
| `cwd` | required for project scope | Project directory used for project installs. |
| `overwrite` | `false` | Replace existing target skill folders. |
| `dryRun` | `true` | Preview without copying files. |

### `ennodia_plan`

Classifies a prompt and previews the route Ennodia would take without starting a
child process.

| Input | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Task text to classify. |
| `category` | fallback classifier | Optional caller-provided category: `code`, `research`, `browser`, `image`, or `general`. |
| `refresh` | `false` | Re-scan harness discovery before planning. |
| `includeMermaid` | `true` | Include a presentational Mermaid route diagram. Set `false` for compact machine reads. |

Returns the category, routing reasons, ordered candidate harness IDs, selected
harness, parallel execution guidance, Judge + Result Advisor guidance, and, by
default, a Mermaid route diagram. Run and
polling views do not embed that diagram.

## Plan Advisor

Plan Advisor turns a natural-language task into a suggested team without making
that suggestion executable by itself. Plan Advisor sees a frozen inventory of
allowed harnesses, caller-approved models, installed skills, and hard size
limits. It can propose only explicit worker slices containing a prompt, harness,
optional model, and skill IDs. It cannot choose `cwd`, environment variables,
arguments, permissions, isolation, timeouts, retries, or budgets.

Harness inventory entries preserve optional `inputGuidance: string[]` from discovery.
Plan Advisor treats this bounded guidance as observations, not proof of native media support.
Slices execute concurrently. For unverified native access, its instructions request a probe-only plan, followed by a new plan after the probe.

The lifecycle is deliberately two-phase: request and inspect advice first, then
launch the exact validated plan in a separate call. Ennodia rejects invalid
Plan Advisor output as a whole and revalidates the plan digest and current inventory
before starting any worker.

### `ennodia_start_plan_advice`

Starts one Plan Advisor task. It starts no proposed worker task and returns an
advice `id` for polling with `ennodia_get_plan_advice`.

| Input | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Work for which Plan Advisor proposes a team. |
| `cwd` | server process cwd | Target directory used only to inventory project skills. The Plan Advisor task runs in a separate empty temporary directory. |
| `refresh` | `false` | Re-scan harnesses before freezing the inventory snapshot. |
| `advisorHarnessId` | harness priority | Harness used for the single Plan Advisor task. |
| `advisorModel` | Plan Advisor harness default | Optional model override for the Plan Advisor task. |
| `allowedHarnessIds` | all runnable public adapters | Worker harness IDs the proposal may select. |
| `allowedModels` | `{}` | Exact caller-approved worker model IDs grouped by harness. An omitted worker model means the harness default. |
| `maxSlices` | `8` | Maximum explicit worker slices. Capped at 64 and by `budget.maxChildTasks` when supplied. |
| `maxSkillsPerSlice` | `8` | Maximum native skills on one slice. Capped at 64. |
| `maxTotalSkillAssignments` | `32` | Maximum skill assignments across the plan. Capped at 1024. |
| `timeoutMs` | `300000` | Timeout for the one Plan Advisor task, capped at 1 hour. |
| `budget.maxEstimatedInputTokens` | none | Fail before Plan Advisor starts, or reject its proposal, if the estimate exceeds this value. |
| `budget.maxChildTasks` | none | Bound both the Plan Advisor start and proposed worker count. |

The returned view begins in `advising`. Terminal states are `ready`, `consumed`,
`invalid`, `failed`, and `cancelled`. Only `ready` advice can be authorized.
Authorization changes the status to `consumed`. A consumed plan cannot run
again. A ready view has a validated `plan` and `planDigest`.

### `ennodia_get_plan_advice`

Returns Plan Advisor status, validation issues, inventory snapshot ID, proposal,
validated inert plan, and plan digest. It also returns budget checks, events,
timing, and estimated time of arrival (ETA). A consumed view also returns
`consumedAt`.

| Input | Default | Meaning |
| --- | --- | --- |
| `adviceId` | required | ID returned by `ennodia_start_plan_advice`. |
| `includeProposal` | `true` | Include the untrusted model-authored proposal when available. |
| `includePlan` | `true` | Include the validated inert plan when ready. |
| `includeEvents` | `true` | Include bounded lifecycle events. |
| `maxEvents` | `100` | Maximum events to return. Capped at 300. Use 0 to omit them. |

### `ennodia_start_advised_plan`

Explicitly launches the exact plan from a `ready` advice result. Before the first
worker starts, Ennodia checks the supplied digest and refreshes the inventory.
It validates every harness and skill again. It confirms that explicit models
remain in the unchanged caller allowlist and enforces the caller-owned runtime budget.

Provider model availability remains unverified until its harness runs. Digest
mismatch, inventory drift, or deterministic validation failure starts zero
workers. Successful authorization consumes the advice before task launch. The
same advice cannot authorize a second launch.

| Input | Default | Meaning |
| --- | --- | --- |
| `adviceId` | required | Ready advice ID returned by `ennodia_start_plan_advice`. |
| `expectedPlanDigest` | required | Exact `planDigest` returned by `ennodia_get_plan_advice`. |
| `cwd` | inventoried directory | Working directory for worker tasks. |
| `isolateCwd` | `false` | Run each worker against an ephemeral isolated copy of `cwd`. Isolation fails before task spawn if the copied tree contains a symbolic link. The reported task `cwd` is an execution trace. Ennodia deletes the temporary copy after the task becomes terminal. |
| `timeoutMs` | `300000` | Per-worker timeout, capped at 1 hour. |
| `budget.maxEstimatedInputTokens` | none | Fail before any worker starts if the exact plan estimate exceeds this value. |
| `budget.maxChildTasks` | none | Fail before any worker starts if the exact slice count exceeds this value. |

The response reports the frozen plan and digest, task IDs mapped to slice IDs,
execution controls, and the budget check. It also reports unrequested installed
skills observed on the selected harnesses. This operation does not automatically run the Judge
and Result Advisor comparison.

### `ennodia_cancel_plan_advice`

Cancels an `advising` request and its single Plan Advisor task. Pass `adviceId` from
`ennodia_start_plan_advice`. Calling it for a terminal request returns
the existing terminal view.

| Input | Default | Meaning |
| --- | --- | --- |
| `adviceId` | required | ID returned by `ennodia_start_plan_advice`. |

### `ennodia_list_plan_advice`

Lists recent Plan Advisor requests from the current MCP server process.

| Input | Default | Meaning |
| --- | --- | --- |
| `includeProposal` | `false` | Include model-authored proposals. |
| `includePlan` | `false` | Include validated inert plans. |
| `includeEvents` | `false` | Include bounded event history. |
| `maxEvents` | `25` | Maximum events per item when included. Capped at 300. |

### `ennodia_estimate_budget`

Plans a run without starting child tasks, then estimates preflight input tokens
and checks optional limits.

| Input | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Task text to classify, route, and estimate. |
| `category` | fallback classifier | Optional caller-provided category. |
| `harnessId` | planner choice | Force one adapter by ID. |
| `mode` | `auto` | `auto`, `single`, or `parallel`. |
| `compare` | `auto` | Include the Judge + Result Advisor pass in the estimate. |
| `refresh` | `false` | Re-scan harness discovery before planning. |
| `maxOutputChars` | effective 24000 | Characters assumed for each successful task in Compare. Ennodia estimates values above the Judge prompt cap at 24000. |
| `budget.maxEstimatedInputTokens` | none | Mark the estimate exceeded above this input-token count. |
| `budget.maxChildTasks` | none | Mark the estimate exceeded above this child-task count. |

The response includes the route plan, selected harness IDs, estimate
assumptions, subscription-limit check status, and exceeded issues.

### `ennodia_estimate_compositional_budget`

Resolves focused compositional slices to harnesses, then estimates preflight
input tokens and child task count without starting child processes.

| Input | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Overall task or question that every slice belongs to. |
| `slices[].id` | generated | Optional stable slice ID. Supplied IDs must be unique. |
| `slices[].title` | none | Optional short label for the slice. |
| `slices[].prompt` | required | Focused task prompt for the slice. |
| `slices[].category` | fallback classifier | Optional caller-provided route category for this slice. |
| `slices[].harnessId` | slice planner choice | Optional adapter ID for this slice. |
| `slices[].model` | adapter default | Optional model override retained in the resolved slice summary. |
| `slices[].skillIds` | inherited | Slice-specific native skill IDs. An explicit list, including `[]`, replaces batch `skillIds`. |
| `cwd` | server process cwd | Optional working directory used to validate requested native skills. |
| `refresh` | `false` | Re-scan harness discovery before resolving slice routes. |
| `skillIds` | `[]` | Default installed native skill IDs for slices that omit `slices[].skillIds`. |
| `includeCompareEstimate` | `true` | Include a later Judge + Result Advisor pass in the returned budget estimate. |
| `maxOutputChars` | effective 24000 | Characters assumed for each successful slice in Compare. Ennodia estimates values above the Judge prompt cap at 24000. |
| `budget.maxEstimatedInputTokens` | none | Mark the estimate exceeded above this input-token count. |
| `budget.maxChildTasks` | none | Mark the estimate exceeded above this child-task count. |

The response includes resolved slice summaries, selected harness IDs, budget
assumptions, subscription-limit check status, and exceeded issues.

## End-to-end runs

### `ennodia_run`

Starts the full orchestration. It plans and executes one or more child tasks.
It can run the Judge + Result Advisor over successful outputs. It exposes the
final answer through `ennodia_get_run`.

Runs usually take minutes. Poll `ennodia_get_run` at sensible intervals. Trust
`remainingMs` and `etaConfidence`. Do not give up after a few seconds.

| Input | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Task sent to the selected local AI tools. |
| `category` | fallback classifier | Optional caller-provided category. |
| `harnessId` | planner choice | Force one adapter by ID. |
| `mode` | `auto` | `auto`, `single`, or `parallel`. |
| `cwd` | server process cwd | Working directory for child commands. |
| `isolateCwd` | `false` | Run each selected harness against an ephemeral isolated copy of `cwd`. Isolation fails before task spawn if the copied tree contains a symbolic link. The reported task `cwd` is an execution trace. Ennodia deletes the temporary copy after the task becomes terminal. |
| `model` | adapter default | Optional model override passed to task harnesses. |
| `timeoutMs` | `300000` | Timeout for each child task, capped at 1 hour. |
| `compare` | `auto` | `auto`, `true`, or `false`. |
| `refresh` | `false` | Re-scan harness discovery before planning. |
| `judgeHarnessId` | Compare priority | Harness used for the Judge pass. |
| `judgeModel` | Judge default | Optional Judge model override. |
| `advisorHarnessId` | Judge harness | Harness used for the Result Advisor pass. |
| `advisorModel` | Result Advisor harness default | Optional Result Advisor model override. |
| `synthesizerHarnessId` | deprecated | Compatibility alias for `advisorHarnessId`. Ennodia rejects conflicting values. |
| `synthesizerModel` | deprecated | Compatibility alias for `advisorModel`. Ennodia rejects conflicting values. |
| `maxOutputChars` | `80000` | Characters per successful task loaded for Compare before the 24000-character Judge prompt cap. |
| `skillIds` | `[]` | Optional installed native skill IDs for selected harnesses. |
| `budget.maxEstimatedInputTokens` | none | Fail before starting if estimated input tokens exceed this value. |
| `budget.maxChildTasks` | none | Fail before starting if selected child tasks exceed this value. |

Returns a run view with `id`, status, selected harnesses, child task IDs,
comparison ID when one exists, events, timing, ETA, and budget estimate/check.
It also returns the final answer when available. The important value is `id`.
Poll it with
`ennodia_get_run`.

### `ennodia_get_run`

Returns the current run state. Set `waitMs` to wait for completion without repeated immediate polls. A wait timeout leaves the run running.

| Input | Default | Meaning |
| --- | --- | --- |
| `runId` | required | ID returned by `ennodia_run`. |
| `waitMs` | `0` | Wait up to 300000 milliseconds for a terminal state. Does not cancel or extend the run. Longer waits require a client tool timeout greater than this value. |
| `includeEvents` | `true` | Include run event history. Set false for compact waiting responses. |
| `maxEvents` | `100` | Maximum run events to return. Capped at 300. |
| `maxAnswerChars` | `80000` | Maximum final-answer characters. Capped at 200000. |

Terminal run states are `succeeded`, `failed`, and `cancelled`. A run is not
complete before it reaches one of those states.

### `ennodia_cancel_run`

Cancels a high-level run and any active child task, Judge, or Result Advisor.

| Input | Default | Meaning |
| --- | --- | --- |
| `runId` | required | ID returned by `ennodia_run`. |

Cancellation is explicit. Do not present a run with `cancelled` status as a
normal model failure.

### `ennodia_list_runs`

Lists runs started by the current MCP server process.

| Input | Default | Meaning |
| --- | --- | --- |
| `includeEvents` | `false` | Include bounded event history. |
| `maxEvents` | `25` | Maximum events per run. Capped at 300. |
| `maxAnswerChars` | `2000` | Maximum answer characters per run. Capped at 200000. |

Live run history is bounded and in-memory. Restarting the MCP server clears
in-progress state. Terminal receipts remain available through
`ennodia_history` when history is enabled.

### `ennodia_history`

Lists terminal run snapshots persisted under the local history directory. Use it
after a restart to inspect previous final answers and Judge disagreement
analysis.

| Input | Default | Meaning |
| --- | --- | --- |
| `limit` | `20` | Maximum persisted run snapshots to return, newest first. Capped at 500. |

History is enabled by default for `createDefaultEnnodiaCore`, written under
`~/.ennodia/history/runs.jsonl`, and capped to the most recent 500 terminal
runs. Set `ENNODIA_HISTORY=0` to opt out.

## Direct tasks

### `ennodia_start`

Starts one or more raw child tasks without a run-level Judge + Result Advisor
pass. Use it for debugging adapters or manual comparison workflows.

| Input | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Task sent to the selected local AI tools. |
| `category` | fallback classifier | Optional caller-provided category. |
| `harnessId` | planner choice | Force one adapter by ID. |
| `mode` | `single` | `single` or `parallel`. |
| `cwd` | server process cwd | Working directory for child commands. |
| `isolateCwd` | `false` | Run each task against an ephemeral isolated copy of `cwd`. Isolation fails before task spawn if the copied tree contains a symbolic link. The reported task `cwd` is an execution trace. Ennodia deletes the temporary copy after the task becomes terminal. |
| `model` | adapter default | Optional model override. |
| `timeoutMs` | `300000` | Timeout for each child task, capped at 1 hour. |
| `refresh` | `false` | Re-scan harness discovery before planning. |
| `skillIds` | `[]` | Optional installed native skill IDs for selected harnesses. |
| `budget.maxEstimatedInputTokens` | none | Fail before starting if estimated input tokens exceed this value. |
| `budget.maxChildTasks` | none | Fail before starting if selected child tasks exceed this value. |

Returns started task IDs, the route plan, and the budget estimate/check.

### `ennodia_start_compositional`

Starts one focused child task per slice. Use it for large reviews where each
agent can inspect a smaller part of the problem. The tool returns task IDs.
poll them with `ennodia_get_task`, then pass the useful completed task IDs to
`ennodia_start_compare`.

| Input | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Overall task or question that every slice belongs to. |
| `slices[].id` | generated | Optional stable slice ID. Supplied IDs must be unique. |
| `slices[].title` | none | Optional short label for the slice. |
| `slices[].prompt` | required | Focused task prompt for the slice. |
| `slices[].category` | fallback classifier | Optional caller-provided route category for this slice. |
| `slices[].harnessId` | slice planner choice | Optional adapter ID for this slice. |
| `slices[].model` | adapter default | Optional model override for this slice. |
| `slices[].skillIds` | inherited | Slice-specific native skill IDs. An explicit list, including `[]`, replaces batch `skillIds`. |
| `cwd` | server process cwd | Working directory for child commands. |
| `isolateCwd` | `false` | Run each slice against an ephemeral isolated copy of `cwd`. Isolation fails before task spawn if the copied tree contains a symbolic link. The reported task `cwd` is an execution trace. Ennodia deletes the temporary copy after the task becomes terminal. |
| `timeoutMs` | `300000` | Timeout for each slice task, capped at 1 hour. |
| `refresh` | `false` | Re-scan harness discovery before resolving slice routes. |
| `skillIds` | `[]` | Default installed native skill IDs for slices that omit `slices[].skillIds`. |
| `includeCompareEstimate` | `true` | Include a later Judge + Result Advisor pass in the returned budget estimate. |
| `maxOutputChars` | effective 24000 | Characters assumed for each successful slice in Compare. Ennodia estimates values above the Judge prompt cap at 24000. |
| `budget.maxEstimatedInputTokens` | none | Fail before starting if estimated input tokens exceed this value. |
| `budget.maxChildTasks` | none | Fail before starting if slice child tasks exceed this value. |

Returns slice task IDs, resolved harness IDs, the budget estimate/check, and a
ready-to-use `compareNext` object for the later `ennodia_start_compare` call.

### `ennodia_get_compositional_status`

Inspects multiple shard task IDs at once, groups their states, and returns the
successful non-empty task IDs ready for a Judge + Result Advisor comparison.

| Input | Default | Meaning |
| --- | --- | --- |
| `taskIds` | required | Shard task IDs returned by `ennodia_start_compositional`. |
| `prompt` | none | Optional comparison prompt included in `compareNext` when the minimum outputs are ready. |
| `minSuccessfulTasksForCompare` | `2` | Minimum successful non-empty outputs required for `compareReady`. |
| `includeOutput` | `false` | Include bounded stdout, stderr, and finalMessage previews for known tasks. |
| `maxOutputChars` | `2000` | Maximum characters per task output field when output is included. |

The response includes `readyTaskIds`, `runningTaskIds`, `failedTaskIds`,
`cancelledTaskIds`, `emptySucceededTaskIds`, and `missingTaskIds`. It includes
grouped counts, compact task summaries, and `compareNext` when a comparison
prompt was supplied and the minimum task outputs are ready.

### `ennodia_get_task`

Returns task status, captured output, events, timing, and ETA.

| Input | Default | Meaning |
| --- | --- | --- |
| `taskId` | required | ID returned by a raw, compositional, advised-plan, run, Plan Advisor, or Compare start. |
| `includeOutput` | `true` | Include bounded stdout, stderr, and finalMessage. |
| `includeEvents` | `true` | Include bounded task events. |
| `maxOutputChars` | `20000` | Maximum characters per output field. Capped at 200000. |
| `maxEvents` | `100` | Maximum task events. Capped at 300. |

A task is terminal only after the child process exits and stdout/stderr have
drained or timed out visibly. Final-message collection and adapter error checks complete before terminal status becomes visible.
Antigravity's explicit no-output error is a failure even when its command exits with code zero.

### `ennodia_cancel_task`

Cancels a running task by task ID.

| Input | Default | Meaning |
| --- | --- | --- |
| `taskId` | required | ID returned by a task start. |

### `ennodia_list_tasks`

Lists recent tasks started by the current MCP server process. By default it
returns a compact view. Request output or events only when you need them.

| Input | Default | Meaning |
| --- | --- | --- |
| `includeOutput` | `false` | Include bounded stdout, stderr, and finalMessage previews for each task. |
| `includeEvents` | `false` | Include bounded task events for each task. |
| `maxOutputChars` | `4000` | Maximum characters per task output field. Capped at 200000. |
| `maxEvents` | `25` | Maximum events per task. Capped at 300. |

## Judge + Result Advisor

The existing `ennodia_*_compare` tool names remain for compatibility. Their
public workflow is Judge + Result Advisor: the Judge analyzes the candidates,
then Result Advisor produces the final recommendation. Result Advisor can degrade
visibly to candidate-only advice when Judge analysis is unavailable.

### `ennodia_start_compare`

Runs a Judge pass and then a Result Advisor pass over completed Ennodia tasks or
caller-supplied responses.

| Input | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Original user task or question the candidates answer. |
| `taskIds` | `[]` | Completed Ennodia task IDs to compare. |
| `responses` | `[]` | Caller-supplied responses with IDs, labels, and text. |
| `judgeHarnessId` | Compare priority | Harness used for the Judge pass. |
| `judgeModel` | Judge default | Optional Judge model override. |
| `advisorHarnessId` | Judge harness | Harness used for the Result Advisor pass. |
| `advisorModel` | Result Advisor harness default | Optional Result Advisor model override. |
| `synthesizerHarnessId` | deprecated | Compatibility alias for `advisorHarnessId`. Ennodia rejects conflicting values. |
| `synthesizerModel` | deprecated | Compatibility alias for `advisorModel`. Ennodia rejects conflicting values. |
| `cwd` | server process cwd | Working directory for the Judge and Result Advisor tasks. |
| `timeoutMs` | `300000` | Timeout for each child task. Capped at 1 hour. |
| `maxOutputChars` | `80000` | Characters per task candidate loaded for Compare before the 24000-character Judge prompt cap. |
| `budget.maxEstimatedInputTokens` | none | Fail before starting if estimated Judge/Result Advisor input tokens exceed this value. |
| `budget.maxChildTasks` | none | Fail before starting if the Judge plus Result Advisor task count exceeds this value. |

Compare requests that the Judge map agreements, contradictions, unique insights,
blind spots, and risks. The Result Advisor uses that analysis plus the original
candidates to return a typed answer, basis, confidence, and open questions.
This is model-led comparison, not formal voting.

When one candidate fully answers the prompt as it stands, such as a complete
file, the Result Advisor names it in `chosenSourceId`. A caller can then use
that candidate's own text, not a rewrite. `ennodia_run` does this for you: its
final answer is the Advisor's reason, then the chosen candidate unchanged.
Ennodia keeps the field only when it names a listed candidate that the Advisor
saw in full. Otherwise it records an `advisor-choice-ignored` event. A blank
or null value means no choice.

### `ennodia_get_compare`

Returns comparison status, candidate inputs, Judge analysis, and typed Result
Advisor output, child task IDs, degradation events, timing, and ETA. Deprecated
`synthesis` fields remain available for compatibility.

| Input | Default | Meaning |
| --- | --- | --- |
| `compareId` | required | ID returned by `ennodia_start_compare` or `ennodia_run`. |
| `includeCandidates` | `true` | Include bounded candidate response previews. |
| `includeEvents` | `true` | Include bounded Judge and Result Advisor events. |
| `maxCandidateChars` | `8000` | Maximum characters per candidate. Capped at 200000. |
| `maxEvents` | `100` | Maximum comparison events. Capped at 300. |

### `ennodia_cancel_compare`

Cancels a running Judge + Result Advisor comparison and its active child task.

| Input | Default | Meaning |
| --- | --- | --- |
| `compareId` | required | ID returned by `ennodia_start_compare` or `ennodia_run`. |

### `ennodia_list_compares`

Lists recent Judge + Result Advisor comparisons started by the current MCP
server process.

| Input | Default | Meaning |
| --- | --- | --- |
| `includeCandidates` | `false` | Include bounded candidate response previews for each comparison. |
| `includeEvents` | `false` | Include bounded Judge and Result Advisor events. |
| `maxCandidateChars` | `2000` | Maximum characters per candidate. Capped at 200000. |
| `maxEvents` | `25` | Maximum events per comparison. Capped at 300. |

## Pragmatic run settings

In version 0.3.0, `ennodia_run`, `ennodia_estimate_budget`, `ennodia_start_compositional` and `ennodia_estimate_compositional_budget` accept optional `pragmatic: {recipe, acceptanceCriteria}`. Model and harness overrides remain optional.
Recipes are `investigate` and `patch`. Both instruct workers to avoid file changes.

Pragmatic preserves routing and comparison choices for one or more independent workers. Plan Advisor can propose tailored model and skill assignments. Retries are not automatic. Native harness permissions still apply.

Run views include the requested `model` and `pragmatic` settings.
See [Pragmatic mode](/docs/guides/pragmatic-mode/) for examples, evidence retrieval, and measurement limits.

### Execution deadlines

Task receipts include `deadlineAt` and `timeoutSource` (`caller` or
`task-manager-default`). The deadline is the process cutoff, not a prediction
of completion. Every child task receives its execution allowance and source.
It asks for useful partial findings before the cutoff and reports of
missing tools or permissions. Caller tools are not
automatically inherited. This notice does not grant access or extend deadlines.

Claude Code receives the notice as operator instructions through `--append-system-prompt`.
Other agents receive it as a tagged block after the task, marked as coming from Ennodia.
The task command shows the notice as `<ennodia-notice>`.

A timed-out task is an interrupted attempt. Review its captured
output, events, partial changes, scope, and access before deciding how to proceed.
A timeout does not establish model inability.

Opt-in Codex continuation is described below.

Cancellation is visible immediately. In version 0.3.0, the history snapshot
is saved after child processes finish and their output drains. Use a bounded
`ennodia_get_run.waitMs` call when you need to wait for the saved evidence.
The wait limit does not stop the child process or extend its execution limit.

### Persistent Codex workers

Set `persistSession: true` on `ennodia_run` to retain a native Codex session.
Use an explicit `harnessId: "codex"` and a persistent working directory.
Persistence cannot be combined with `isolateCwd`, parallel mode, or comparison.
The Codex adapter defaults to its read-only sandbox on each turn.

After the worker settles, inspect its task receipt. If `canContinue` is true,
pass that task ID as `continueTaskId` in the next run. The follow-up keeps the
harness and directory. It inherits the model and reasoning effort unless you
supply new values. Each follow-up has a new task ID and execution allowance.
An earlier turn cannot be used once a follow-up has started.

Continuation requires a task still held by the same running Ennodia server.
It does not import arbitrary native session IDs or restore ownership after
a server restart. Native session files remain under the harness's retention
policy. Ordinary runs remain ephemeral.

Preflight input estimates exclude the retained native context. Use each
turn's reported usage to assess cost. Persistence does not prove a cache hit
or a cost saving. An interrupted session may fail to resume, so preserve its
partial findings and files as evidence too.

### Compact status reads

Set `compact: true` on `ennodia_get_run` to omit the routing plan, budget
explanation, prompt preview, and skill metadata from repeated status reads.
Status, timing, task IDs, answers, errors, and diagnoses remain available.
The existing answer and event limits still apply. Use `compact: false` for
the full receipt. The default remains false.

For pending runs, use `waitMs: 30000`, `compact: true`, and
`includeEvents: false` when the installed schema supports these options.
A compact response is not a summary of the worker's findings. Inspect the
answer and any partial task evidence before drawing conclusions.

### Native subagent controls

`ennodia_run` and `ennodia_start` accept `nativeSubagents: "disabled"` for Codex
workers. Codex receives native feature flags disabling its built-in subagent
tools. Task receipts record the setting, and persistent follow-ups inherit it.
Other harnesses reject this setting before workers start. Omitting it preserves
native defaults. Judge and Advisor tasks do not receive this worker setting.

This controls built-in delegation tools. It does not prevent a shell command
from starting another program, grant file permissions, or account for nested
agent usage. Do not infer a complete cost total from a parent-only receipt.


### Native worker permissions

Set `nativeSandbox: "workspace-write"` on a normal Codex worker run only
when its assignment permits edits. Use `nativeSandbox: "read-only"` for
investigation. Omission defaults to read-only on every turn, including
continuations of write-enabled sessions. Write access is not inherited.

The setting uses the supported Codex sandbox option. Native configuration
still defines sandbox behavior and writable locations. This option does
not grant caller tools, deployment access, or permission bypasses.
Other adapters reject explicit sandbox settings. Pragmatic recipes reject
workspace-write. Judge and Advisor tasks keep their existing defaults.

Task receipts record the selected sandbox. Run receipts record the requested
setting.

### Evidence and operation limits in version 0.3.0

Compositional status separates lost stream capture (`captureTruncated`) from shortened output previews (`outputTruncated`).
Lost captures are listed in `truncatedTaskIds` and excluded from ready task IDs.
A compact preview can omit a complete retained answer without making the task unready.
Compare metadata identifies truncated evidence, including its prompt limit.
Preserve full patch artifacts and verify them before application.

`maxChildTasks` limits workers selected by the current operation.
A later Compare call and its Judge and Result Advisor have separate limits.
`includeCompareEstimate` includes an estimate, not a reserved spending balance.
Count these stages, retries and verification when reporting whole-task cost.