Skip to main content

Tool Surface & Budgets

What an MCP session can actually call in Daintree: the 38 external tools, the Core and Full in-app tool sets, handback markers, reply waits and notices, mcp.surface, payload budgets, forge over MCP, resources, prompts and idempotency.

Updated
Reviewed

This page is the reference companion to MCP Server and Authorization & Approval. It covers what a session can call, how an orchestrator prompts agents and gets their replies back, what shape the results come back in, and the ceilings that keep those results transportable. The connect config and the audit log live on the hub page, and the authorization model on its own page.

Why the surface was cut

The external tool surface used to carry 100 tools and roughly 128 KB of schema. That is past what real MCP clients tolerate, and the failure mode was the problem: Cursor caps the tool count across every connected server and silently truncates the overflow, while GitHub Copilot's 128-tool cap is a hard blocking error. Either way the client was choosing which of Daintree's tools survived, and neither told anyone which ones it dropped.

v0.30 cut the external surface to a curated allowlist. The count is not the interesting part: the interesting part is that the choice moved back inside Daintree, where it can be reasoned about and tested, instead of being made silently by whichever client happened to connect. Each tool added since has had to argue for its slot against a fixed ceiling.

The surface is budgeted in both dimensions, because the failure is measured in bytes as much as in tools. A test asserts a ceiling of 38 external tools and a floor of 15: the floor guards the opposite failure, where a bad merge empties the list and makes every other assertion vacuous. A separate test bounds the summed descriptions across the external roster at 9,000 UTF-8 bytes, and every description at a readable floor of 120 bytes, because a few dozen tools carrying novel-length descriptions would reproduce the same truncation with a count that still looks fine.

Note

The November 2026 source snapshot (091308f2af, 0.51 plus unreleased work) declares 38 external tools, at the ceiling. The tables below reflect that snapshot; use tools/list and mcp.surface for your running version. Workspace binding can narrow the list further. The implementation lives in the external allowlist, the Core and Full tool sets and their authorization tests.

The external tool surface

These are the tools an API-key client sees in tools/list and may dispatch through tools/call. The two sets are identical by design: nothing is withheld from the listing while staying callable. Tools ending in Owned act only on a terminal or worktree this MCP session created; see Cleaning up a session's work.

ToolWhat it does
actions.listEnumerate the calling session's authorized action surface.
actions.searchA compact ranked shortlist of authorized actions, the answer when the tools/list schemas are too large to reason over.
actions.getSchemaOne action's manifest entry plus whatever schemas it publishes.
actions.getContextThe live habitat context: active project, worktree, focused terminal and panel state.
mcp.surfaceThis session's tool surface as versioned data with a stable hash.
workspace.listEvery project and scratch workspace Daintree knows, open or not, with the id the Daintree-Workspace-Id header binds to and whether a view is open. Identity only.
agent.launchLaunch an agent (built-in, user-defined or plugin-contributed) in a worktree, optionally with a first prompt, a system prompt, a handback request or a wait for its reply.
agent.listAvailableThe authoritative effective agent registry and live launchability. Nothing the caller's own shell can answer.
agent.listPresetsDiscover effective preset ids for an agent, including project presets. Returns identity and labels without environment variables, arguments, or flags.
agent.listAccountsAn agent's saved accounts: the ids agent.launch takes as accountId, and with a worktree, which account a launch there would use by default. Identity only, never the folder a login lives in.
fleet.getRunStatusA read-only supervision snapshot of the fleet broadcast run the user is running.
recipe.listList the workspace recipes available to this project.
recipe.runRun a recipe. Confirm-gated.
skills.searchSearch plugin-contributed skills.
skills.loadLoad a skill's markdown into the agent's context.
terminal.listEnumerate the terminal panels in the view. owned: true keeps only the ones this session created, and includeClientMetadata adds each one's client record.
terminal.newCreate a terminal panel.
terminal.getOutputRead one terminal's trailing output.
terminal.getStatusBatched agent and process state across many terminals, optionally with output tails and a send's delivery record.
terminal.sendCommandOwnedSubmit text to a terminal this session created. Returns once queued, not when the work finishes, unless it was asked to wait for the reply.
terminal.injectOwnedWrite the active worktree's prepared context into a terminal this session created, to hand its agent a large codebase context.
terminal.interruptOwnedStop the turn an agent is running, keeping the panel and the conversation.
terminal.readLastMessageOwnedRead the last reply a Claude Code agent wrote in its own transcript, including an unanswered question and its options.
terminal.revealOwnedBring the user to a panel this session created, switching workspace and raising the window if needed.
terminal.placeOwnedMove a panel this session created or was handed to the background, the dock or the grid. Its process keeps running, and the user's focus never moves.
terminal.restartOnPresetOwnedMove a panel this session launched to another preset of its agent, for a worker that hit a plan limit. Confirm-gated; scrollback is lost, and a handed-over panel is refused.
terminal.restartOnAccountOwnedThe same move to another of the agent's saved accounts. Confirm-gated, with the same refusals.
terminal.closeOwnedClose only a terminal this session created, using the usual trash and recovery behavior.
terminal.waitUntilIdleA bounded long-poll until an agent's state machine leaves working.
terminal.waitUntilIdleBatchThe same wait, fanned across several terminals.
terminal.setClientMetadataAttach the client's own JSON record (up to 2 KB) to a terminal, so a reconnecting client can tell panels apart. Shared by every external client, invisible in the UI, deleted with the panel, and it confers no ownership.
worktree.listList the project's worktrees.
worktree.getCurrentThe active worktree.
worktree.createWithRecipeCreate a worktree with Daintree's own creator (config copy, submodules, setup), optionally applying a recipe.
worktree.waitForPullRequestWait until a worktree has a detected pull request. Detection is a cached background poll: a PR seen, not proof its agent finished.
worktree.deleteOwnedDelete only a worktree this session created, with host confirmation and the normal deletion safeguards.
worktree.setActiveSwitch the active worktree, which moves what the user sees.
copyTree.generateAndCopyFileApply the project's CopyTree policy and put the bundle on the clipboard as a file.

Some arguments the in-app sessions use are left out of this listing, because only a caller with a pane of its own, or an assistant, can use them. agent.launch drops notify and replyLines, which ask for a notice typed into the caller's own prompt and shape it; an API-key client has no prompt. terminal.sendCommandOwned drops those two plus generation, whenBusy and queueTtlSeconds, and terminal.getStatus drops queuedSendToken: they address another assistant, or a worker the global Assistant steers, and hold a message for it, which only an assistant can do. terminal.interruptOwned and terminal.revealOwned drop generation for the same reason.

What is deliberately excluded

  • Every forge.*, git.*, file.*, project.* and browser id. An external agent driving Daintree sits in a terminal with its own shell and its own gh. The few of these that stay on MCP at all are in-app only, where no third-party client cap applies: the forge reads in Core, git activity and project checks in Full, and the assistant's own project.runCommand and project.links.* in Core.
  • Unscoped terminal input, terminal.close and worktree.delete. The external session can type into, interrupt, close and delete only what it created, through the *Owned tools. terminal.list returns the user's own shells and other agents' terminals too, and listing a resource does not grant authority over it.
  • The batch tools, composites and notices. agent.launchMany, agent.launchInNewWorktree, terminal.sendCommandMany, terminal.closeMany, terminal.notifyWhenIdle and worktree.retireOwned are in-app only. An external client loops over the single calls and waits with waitForReply or the idle waits.
  • Fleet broadcast. fleet.getRunStatus is read-only. To fan out, send one terminal.sendCommandOwned per terminal the session created and watch with a batched terminal.getStatus or a bounded terminal.waitUntilIdleBatch.
  • The github.* aliases, which were removed in v0.18 and do not exist at any tier.

Cleaning up a session's work

Daintree records ownership from successful creation results for terminal.new, agent.launch, recipe.run and worktree.createWithRecipe, and in-app for workflow.startWorkOnIssue (its agent terminal only, not the worktree it creates) and a panel agent.resumeOwned started. agent.launchInNewWorktree owns both halves through the create and launch it runs. Launching an agent into an existing worktree owns the new terminal only. A partially successful worktree creation can still record the worktree it left behind. Only those trusted results write the record: a caller cannot name a resource into it by passing its id.

For an API-key client, ownership is session-scoped. Keep the returned ids and clean up within the same MCP session. Disconnecting, or 30 minutes without MCP calls, ends the session and clears the ownership record but leaves the terminals and worktrees in place; a reconnected session cannot claim them by supplying their ids. Daintree says so in the result of a launch and of an owned listing, and when it refuses an *Owned call. An orchestrator that needs ownership to survive reconnects should run as an agent pane with Agent integrations on: a pane's credential owns what it creates until the pane exits or is relaunched.

A terminal the user hands to an orchestrating pane (right-click > Hand to orchestrator) counts as owned for sending, injecting, answering dialogs, interrupting, revealing and reading its last message, but not for closing: handing over a conversation is not handing over the right to destroy it.

Delete worktrees only after reviewing the result, and approve the host's contents preview when prompted. worktree.deleteOwned never forces past uncommitted or untracked changes, never deletes the branch, and closes no terminals at all: close your own panels with terminal.closeOwned first, because it refuses while any terminal process still runs in the worktree, a closed panel's included. See the ownership ledger and deletion and recovery guide.

The in-app tool sets

Daintree's own assistant and the agent panes a project connects to the server run at Core or Full. Core is 74 tools and the default; Full adds 45. Every tool in a set is re-sent to the model on each turn, which is why Core holds the orchestration loop (choosing work, launching and steering agents, confirming their pull requests landed green, cleaning up) and the rest waits in Full.

AreaCoreFull adds
Discovery and contextactions.getContext, actions.search, actions.getSchema, mcp.surface, workspace.list, slashCommands.listactions.list
Worktreesworktree.list, worktree.createWithRecipe, worktree.waitUntilReady, worktree.waitForPullRequest, worktree.delete¹, worktree.deleteOwned, worktree.retireOwnedworktree.getCurrent, worktree.setActive, worktree.reviewReadiness, worktree.resource.status, worktree.resource.provision, worktree.resource.pause, worktree.resource.resume, worktree.resource.teardown, worktree.setLabelColor, worktree.setCustomTitle
Issues and pull requestsforge.listIssues, forge.getIssue, forge.listIssueComments, forge.listPRs, forge.getPR, forge.getPRs, forge.getCIStatus, forge.getChecks
Agentsagent.launch, agent.launchMany, agent.launchInNewWorktree, agent.listAvailable, agent.listPresets, agent.createPreset, agent.updatePreset, agent.deletePreset, agent.listAccounts, agent.listModels, agentSessionHistory.list, agent.resumeOwnedagentSessionHistory.resume, agent.addAccount, canopy.openWindow
Terminalsterminal.list, terminal.getStatus, terminal.getOutput, terminal.readLastMessageOwned, terminal.sendCommand¹, terminal.sendCommandMany, terminal.waitUntilIdle, terminal.waitUntilIdleBatch, terminal.notifyWhenIdle, terminal.cancelQueuedSend, terminal.interruptOwned, terminal.sendKeys¹, terminal.close¹, terminal.closeMany, terminal.waitForExit, terminal.restartOnPresetOwned, terminal.restartOnAccountOwned, terminal.applyClaudeUpdateOwned, terminal.moveToWorktree, terminal.revealOwned, terminal.placeOwned, terminal.renameterminal.new, terminal.inject¹, terminal.kill², terminal.restart², terminal.startHeld², terminal.closeAll², terminal.setClientMetadata
Recipes and workflowsrecipe.listrecipe.run, workflow.startWorkOnIssue, workflow.prepBranchForReview
Commands, checks and gitproject.runCommand²project.detectRunners, project.runCheck, git.getProjectPulse
Context, skills and fleetcopyTree.generate, copyTree.injectToTerminal², copyTree.generateAndCopyFile, skills.search, skills.load, fleet.getRunStatus
Linksproject.links.list², project.links.add², project.links.update², project.links.remove²
Assistant sessionsassistant.list², assistant.start², assistant.resume², agent.readQuota²
Remote Hosts (registered only where Remote Hosts is available)host.list², host.call², host.status², host.ensureProject², host.settings², host.watch², host.bringBack²host.switch, project.openOnHost
Diagnostics and previewhelp.displayImage, diagnostics.openReview²browser.getConsoleMessages, devPreview.reloadPreview, devPreview.restart, errors.recent, notifications.recent
Plugin authoringplugin.validate, plugin.diagnostics, plugin.reloadProject, plugin.reloadPanel, plugin.capturePanel

¹ The Daintree Assistant's form. Every other session, an agent pane included, gets the *Owned form in its place (terminal.sendCommandOwned, terminal.injectOwned, terminal.sendKeysOwned, terminal.closeOwned, worktree.deleteOwned), which acts only on what that session created or was handed. The batch tools follow the same rule item by item.

² Reserved to the Daintree Assistant and withheld from agent panes at any tier.

So a project's assistant sees 74 tools at Core and 119 at Full, and an agent pane 56 and 96. Where Remote Hosts is not available, the seven Core host.* tools, host.switch and project.openOnHost are not registered, which leaves the assistant 67 and 110 and a pane 56 and 94. These are the static sets; what a session lists can be narrower, for example when it is bound to a workspace. A pane at Core lists everything a pane at Full holds, because a call above its tier asks you for approval rather than failing; see Agent panes. Git and forge writes, file reads, UI navigation and layout, theme and settings reads and writes, session bookmarks, the recipe editor, screenshot capture, fleet arming and bulk kills are in neither set.

What the less obvious groups do

  • Remote Hosts. host.list and host.call let the assistant see this machine's remote hosts and run a host's own Daintree tools there, under that host's own gates. host.status reads agents across projects and hosts in one call, host.ensureProject puts this project on a host without opening a window there, host.settings changes a host's named settings once you approve the preview, host.watch arms one notice for when a link or capacity condition is met or an agent starts waiting, and host.bringBack wakes a host whose link is down, where a wake is set up, and starts Daintree there if its Host mode is on. host.list includes this machine as local. They are offered from the start of every assistant session, whether or not you have hosts.
  • Links. project.links.* keep the project's entries in the links launcher. Adding one opens nothing, and the assistant can change only the links it added and you have not since edited.
  • Assistant sessions. assistant.list, assistant.start and assistant.resume let one assistant find another in the same project, open one in a vacant slot or reopen the conversation a stopped slot keeps, and then message it with the ordinary send tools. agent.readQuota reads this machine's Codex quota and, for each Claude Code limit, the last usage-limit message its terminals showed.
  • Running a command. project.runCommand runs one non-interactive shell command in the project root or a worktree, with no prompt or terminal attached, and returns its exit code and output. It does not ask first and runs as your user, not in a sandbox, so it is pinned with the deletes in the settings preview, and Daintree strips its own DAINTREE_ variables from it.
  • Presets, accounts and models. agent.createPreset, agent.updatePreset and agent.deletePreset edit your own presets, each confirm-gated with the exact change previewed; project, CCR and built-in presets stay read-only. agent.listAccounts and agent.listModels resolve the ids a launch takes, and agent.addAccount, in Full, asks every time, with a row per account naming its folder.
  • Bringing agents back. agentSessionHistory.list and agent.resumeOwned reopen a closed session into a panel the caller owns, which is why they sit in Core. agentSessionHistory.resume opens one the caller does not own, so it stays in Full. See Resume agents and history.
  • Steering panels. terminal.placeOwned parks or brings back a panel without moving you, terminal.waitForExit waits for the processes of panels this session closed before their worktree is deleted, terminal.cancelQueuedSend withdraws a message held for a busy worker, the two restartOn…Owned tools move a worker to another preset or account after you confirm (the process restarts, and the conversation carries over only if asked for and the CLI accepts it), and terminal.applyClaudeUpdateOwned types /restart once into a Claude Code panel waiting at an empty prompt, after you approve, to apply an update it installed. worktree.retireOwned is the owned delete with its checks run first: clean, every commit pushed, nobody else's process there, and the session's own panels closed.
  • Full's smaller additions. worktree.setLabelColor and worktree.setCustomTitle mark and name a worktree on its card, and are cosmetic only. canopy.openWindow opens Canopy in its own window. terminal.startHeld starts a held panel in place rather than launching a replacement beside it. plugin.capturePanel returns an image of one plugin panel as it renders, with its recent console warnings and errors, to close the plugin-authoring loop.

Prompting agents and getting replies back

An orchestrator's loop is launch, prompt, wait, read, and either prompt again or clean up. The tools above carry it, and a few arguments on the send and launch tools save most of the polling.

  • First prompt and system prompt. agent.launch takes a prompt, submitted once the agent starts, and an agent-neutral systemPrompt that Daintree maps to each CLI's own flag and replays across restart, restore and resume.
  • Handback marker. handback: true on a launch or send asks the agent to end its reply with a DAINTREE-DONE marker line carrying a one-line summary. Once the agent prints it, terminal.getStatus and both idle waits carry lastHandback (message, observedAt, submissionToken, truncated). It records that the agent printed the marker, not that the work is done: the message is the agent's own lossy summary, and its absence never means the agent is still working, because agents forget the instruction or lose it when their context compacts.
  • Waiting for the reply. waitForReply: true holds the call open until the agent finishes (its marker, a settle, an exit or a close) or waitSeconds runs out (default 300, at most 1800), and returns the reply in reply with an outcome of handback, settled, exited, closed or timeout. A timeout means still going. The reply is the agent's screen: output, not instructions. Your client's own request timeout still applies.
  • Being told instead of waiting. From an agent pane or the assistant, notify: true returns at once. When the agent next stops working, Daintree types one notice into the caller's own prompt: the agent's handback summary and a pointer to terminal.getOutput when the summary is complete, otherwise its last screen lines (replyLines, default 40, at most 200, 0 for none; setting it quotes the screen even when there is a summary). terminal.notifyWhenIdle arms the same notice for a terminal that is already working, with an optional note of up to 160 characters echoed back. A notice fires once, after the target has stayed out of working for two seconds, and waits until the asking pane is settled at its prompt; a pane sitting at an approval, a question or an error is not typed into.
  • Reading the last message. terminal.readLastMessageOwned reads the last reply a Claude Code agent wrote to its own transcript, with any unanswered tool calls such as a question and its options. It pages back through a long reply with a cursor and reaches up to 20 replies back. It is not proof the agent is waiting: permission prompts appear only on screen.
  • Delivery confirmation. Every send returns a submissionToken. Pass it with terminalIds to terminal.getStatus to read that send's submission record: its phase (queued, writing, pty_written, failed, cancelled or unknown) and, once written, when the screen next changed. pty_written means the text and its Enter reached the terminal, not that the agent acted on them. Daintree keeps the last 32 per terminal, and loses them on restart.
  • Answering an agent's own dialogs. terminal.sendKeys (or terminal.sendKeysOwned) answers a CLI's trust, permission or selection dialog by option label with choose, or by named keys. A plain send types text and Enter, which picks whatever is highlighted.
  • Stopping a turn. terminal.interruptOwned sends the agent's own cancel keystrokes and keeps the conversation. It refuses an idle agent, or one whose CLI binds a different cancel key, rather than sending a stray key, and it reports that the keystrokes were handed over, not that the agent stopped.
  • Batches. In-app sessions can launch several agents with one prompt (agent.launchMany), send a different message to each of several terminals (terminal.sendCommandMany), and close several at once (terminal.closeMany). Each item runs as the single call would, with its own notice, and results come back in order.

Reading your own surface with mcp.surface

A client written against an older surface has no way to notice it is talking to a newer one, until a call fails for a reason it cannot interpret. mcp.surface answers that at startup: it returns the session's tool surface as versioned data with a stable content hash, so a client can compare one string instead of diffing a tool list, and fail loudly rather than silently.

FieldMeaning
manifestVersionThe shape version of the payload, currently 4. Bumped by hand when a field is added, removed or given new meaning, never for a change in which tools the surface contains. Version 3 renamed the in-app tier values to core and full, and version 4 added role. A client reads this to know whether it can still parse the response at all.
appVersionThe running Daintree build, so a captured response is diagnosable on its own.
tierThe tier this call was admitted at, and the tier the rest of the response describes.
roleWhich kind of session the server took the connection for, settled from its credential at the handshake: global-assistant, project-assistant, agent-pane, external-client or relay. Part of the hash.
hashHex SHA-256 over the canonical form of the surface.
toolsSorted by id. Each entry carries id, tier (the smallest tool set that permits it, or external), kind, readOnlyHint, idempotentHint, and an optional deprecated object with a reason and a replacement.

Two decisions are worth knowing. Descriptions and schemas are deliberately omitted: they are already on tools/list, and re-sending them would make the cheap startup check as expensive as the thing it replaces. And prose is stripped before hashing: descriptions, titles and examples are removed from the schema preimage, so rewording a description never reads as a compatibility break, while an argument-schema edit always does. The hash covers the full argument schema, including value ranges the advertised schema leaves out for the model's benefit.

The manifest describes the static tier allowlist plus the session's own binding, exactly as tools/list does, not the transient per-tool approvals that can widen dispatch for a few minutes. Folding those in would make the hash flap as approvals come and go, and would describe a surface tools/list never showed. When a tier changes, the server fires notifications/tools/list_changed; a client that re-reads on that notification converges.

Workflow instructions at initialize

The MCP initialize result carries a static instructions string that clients fold into the model's system prompt at session start. It is the only place to establish cross-cutting rules before the model has picked a tool, so it deliberately does not restate any tool's own description. External clients and agent panes get four points:

  • Daintree drives IDE-owned worktrees, recipes and agent terminals. Use your own shell for repository, file, git and forge work; that is not license for an in-app session to route around its own tier.
  • Call only listed tools. actions.search finds one by intent and actions.getSchema gives its arguments; neither widens access.
  • Resolve worktree and terminal ids before scoped actions. A send returns once queued, not when the work is done. From an agent pane or the assistant, pass notify: true and end the turn; otherwise wait with terminal.waitUntilIdle, never a polling loop, and read idleReason before an irreversible step.
  • In-app sessions run Core or Full, and external is its own allowlist. A call outside the session's set returns TIER_NOT_PERMITTED, or from an agent pane asks the user; USER_REJECTED means they declined. Retry a retriable: false error only after something changes.

The string is budgeted by test rather than truncated at runtime: Claude Code hard-cuts instructions at 2 KiB and the authorization paragraph is the tail, so silently losing it would leave a model guessing at why a call was denied. The suite fails an author's edit instead, with 512 bytes held in reserve. Daintree's own assistant sessions get a one-line string instead, because their own instruction files carry these rules in fuller form, and Codex repeats a server's instructions inside every tool description it looks up.

Payload budgets

Before v0.30 a single tool call could return 31 MB. Every result path is now bounded, and the bounds are byte-based rather than token-based on purpose: tokenization is a client concern, and pinning the server to one vendor's tokenizer would be worse than a conservative fixed cap.

SurfaceCapBehavior at the cap
Tool result text50 KiBTruncated at a UTF-8 character boundary, with the notice prefixed rather than appended: a model reading top-down learns the body is incomplete before it starts parsing it.
structuredContentMeasured separatelyRe-derived by parsing the already-bounded text, so the two halves can never disagree. Dropped when the text was truncated, when nesting exceeds 100 levels, or when it re-serializes over the cap. Any dropped structured half flags the envelope isError: true.
Terminal tails50 KiB, shared across a callOutput tails in terminal.getOutput, terminal.getStatus and the scrollback resource are fitted to the cap before serialization and keep the newest lines, so a tail is never cut into unparseable JSON. recentOutputTruncated says older output was cut.
Resource text50 KiBA threshold rather than a hard ceiling; appends a [truncated] marker.
Project check outputTail-preservingKeeps the end of the run, where the failure is. Secret-scrubbed across an 8 KiB overlap so a credential straddling the cut is still redacted.
Commit subjects512 bytes per fieldCommit subjects and author names in git.getProjectPulse are truncated per field, so one pathological commit message cannot crowd out a whole result.
CopyTree content preview32 KiB read, 48 KiB serializedThe serialized budget is the one that decides: JSON escaping doubles newlines and quotes and expands control characters sixfold, so a 32 KiB head of the wrong file serializes to far more.
Waited and notified replies6,000 characters per terminalThe newest output is kept. A notice carries at most 20,000 characters across all its terminals, and a batch's waited replies at most 32,000.

Session history reads, the last-message read and the action manifest carry their own budgets on the same model. Two paths bypass the helper entirely: non-text content, and JSON-RPC protocol errors.

Alongside the budgets, every action result is parsed through its declared schema before it is returned, so the published shape is the delivered one. That parse is also a security boundary in its own right. See Security posture over MCP.

Forge over MCP

Forge tools are not on the external surface: an external caller has its own gh. In-app sessions reach eight forge reads at core, and so at full too, because choosing what to work on, triaging it and confirming that an agent's pull request landed green are part of the orchestration loop: forge.listIssues, forge.getIssue, forge.listIssueComments, forge.listPRs, forge.getPR, forge.getPRs, forge.getCIStatus and forge.getChecks. No forge write is on any tier, so nothing creates, merges or edits a pull request or issue over MCP. The assistant and agents do that with their own forge CLI in their own shell: the assistant's Claude Code session runs gh, glab and tea without a permission prompt, and its instructions have it file an issue only once you approve the repository, title and body. Daintree's own confirmation dialogs still cover everything that goes through MCP.

Writes

Forge write actions (pull requests: create, merge, comment, edit; issues: create, close, label; PR reviews: approve and request changes) still exist in Daintree for its own UI, and each returns the state it changed rather than void. None of them is reachable over MCP.

Reads

  • forge.getCIStatus returns the roll-up CI verdict for one pull request. Read the overall state for the answer: the accompanying counts cover required checks only, and a zero total also appears when the required-check list could not be read in full, so it is never evidence that nothing gates the merge. Values are provider-cached and can lag by around a minute.
  • forge.getChecks names the checks behind that verdict, the follow-up once the roll-up shows trouble.
  • forge.getPR reads one pull request, and forge.getPRs several in one call, keeping a failed lookup apart from a missing pull request; forge.listPRs, forge.listIssues and forge.getIssue list and read pull requests and issues, with the listing options below.
  • forge.listIssueComments reads an issue's comment thread, since forge.getIssue reports only how many comments there are.

forge.getPR, forge.getPRs, forge.getCIStatus and forge.getChecks advertise an MCP outputSchema, so a model can be held to the result shape rather than parsing prose.

Listing

Issue and PR lists take perPage (1–100, with a default that varies by provider; 100 is the tightest page ceiling across the provider roster), sort (created or updated), direction, an opaque cursor from the previous response's nextCursor, and a view that selects a summary or full projection. There is also a bypassCache escape hatch, because without it an out-of-band change (you running a forge CLI in a terminal, another agent closing an issue) stays invisible until the cached page ages out.

The schemas are strict: an unknown filter key is rejected rather than dropped. A silently ignored filter returned a plausible-looking but wrong set, and an agent then acted on it. A validation error naming the bad key is strictly more useful than a wrong answer.

Running a project's checks

project.runCheck (v0.30) runs one of a project's detected runners (a test command, a lint command) as a real child process and returns its real exit code, instead of the best-effort scrollback parse that preceded it. It executes in the main process rather than round-tripping to a renderer, because renderer dispatch is capped at 30 seconds, well under a real test suite, and an MCP abort signal does not cross IPC so a renderer-hosted run could never be cancelled. Because it never needs a project view, it also works for a workspace-bound session whose project has no window open.

It sits in the full tool set, beside project.detectRunners, which lists a project's runners without executing them. Neither is in core. It is not on the external surface: an external caller runs its own test command in its own shell. Don't confuse it with project.runCommand, the assistant's Core tool, which runs any command the assistant names rather than one the project declares, and is withheld from agent panes.

CopyTree returns a file handle

copyTree.generateAndCopyFile is the one deliberate exception to "drop what the caller can do itself", and it is worth stating why. A caller holding a terminal could pipe files through pbcopy itself. What it cannot reproduce is the deliverable: one call that applies the project's own CopyTree policy (ignore rules, budgets, format) and puts the bundle on the clipboard the same way on every platform (the file itself on macOS and Linux, its path on Windows). The alternative is a brittle shell-and-pipe reconstruction per platform.

It returns a file handle rather than the whole bundle, so a multi-megabyte context bundle never has to cross the transport. Its blast radius is a clipboard overwrite, which the risk banding already classifies as destructive-local and the tool advertises through destructiveHint. See CopyTree.

Terminal and agent metadata

terminal.getStatus is the batched polling path. Prefer it over listing terminals and then reading each one's output in turn. Name up to 256 terminals with terminalIds, or filter by worktree or location. Per entry it returns the terminal id, the detected or launched agent id, the agent state, the reason it is waiting, the timestamp of the last transition, and:

  • Process lifecycle. exitCode is set once the process exits and is absent while it runs (null for a signal with no numeric code); spawnedAt is the spawn time; hasPty turns false once the process exited or a kill was requested; agentIncarnation counts how many times a new agent took over the same terminal.
  • Screen and typing activity. With includeOutput, lastOutputChangeAt is when the visible screen last changed, ignoring spinner and timer redraws, so a frozen turn can be told from a long one, and lastTypedInputAt is when input was last typed, so a CLI's pre-filled suggestion can be told from input actually sent. recentOutput carries the tail. Neither timestamp is a hang verdict.
  • Parsed check results. lastCheckResult carries a parsed pass/fail verdict from a test, lint or build summary detected in the terminal. It is best-effort rather than authoritative: project.runCheck is the path that returns a real exit code.
  • Handback and delivery. lastHandback when the agent printed a requested marker, and a send's submission record when a submissionToken was passed; see Prompting agents and getting replies back.
  • Armed state. Whether fleet broadcast input reaches the terminal.

It never blocks and never fails as a whole: an unknown id returns a per-entry error instead of aborting the call. The result says which surface answered (renderer, or pty when the workspace has no open window) and lists the fields that surface cannot observe in unavailableFields, which means unknown rather than false. The idle waits add a trackingState (tracked, closed or unknown), so a finished agent can be told from a terminal Daintree no longer tracks; an untracked terminal returns idleReason: "unknown" at once, which is not proof a shell command finished.

terminal.restart and terminal.kill are in the full tool set for the Daintree Assistant only. Fleet arming and disarming, and browser.captureScreenshot, are on no tier: they are yours to drive from the UI.

Resources

Five resource kinds are exposed, under the URI scheme daintree://<host>/<id>/<verb>. Three support live subscriptions, which emit notifications/resources/updated with no payload: the client re-reads on each notification. A notification can be dropped without error, so the read is the authoritative half.

URIBacking actionSubscribable
daintree://workspace/current/bindingworkspace.listYes
daintree://worktree/{id}/pulsegit.getProjectPulseYes
daintree://terminal/{id}/scrollbackterminal.getOutput (last 200 lines)No
daintree://agent/{id}/stateterminal.listYes
daintree://project/current/issuesforge.listIssuesNo

The binding resource is a session's view of its own workspace binding: whether the bound workspace has a live view, when eviction last took one, and whether the user asked to keep it resident. It needs no renderer, so it is listed first and still answers when nothing else can; an unbound session reads unbound. In the agent state URI, {id} is an agent id such as claude, not a terminal id: the resource reports the terminal of that agent Daintree heard from most recently, and names it.

Resources authorize through their backing action, which has a consequence worth stating: because no forge.* or git.* id is on the external allowlist, an external session cannot read the pulse or issues resources. Binding, scrollback and agent state are available to it.

Prompts

The server registers three MCP prompts. Most clients surface them as slash commands in the input autocomplete.

PromptArgumentsWhat it renders
start_issueissue_number (required)A structured prompt to start work on an issue, with the active worktree and branch filled in, asking the model to summarize the goal, confirm the worktree is the right place, and outline the first two or three steps for sign-off before editing.
triage_failed_agentterminal_id (optional)A diagnosis prompt for a stuck or failed agent. Pass a terminal id and recent output is embedded; omit it to triage the current worktree without specific output.
triage_terminalsNoneA static watching recipe: how to batch terminal.getStatus, when to set includeOutput, how to read lastCheckResult and lastHandback, and how to pace the next round instead of holding a blocking wait open.

Idempotency dedup

Models replay tool calls during multi-step planning, especially across reconnects. A per-session dedup cache absorbs that for creation tools: within a 120-second TTL a duplicate call returns the original result instead of redispatching, with a 256-entry FIFO cap per session.

A caller can pass an explicit requestKey alongside _meta in the arguments; without one, the server hashes the action id and the argument object. An in-flight duplicate joins the original promise; a completed one returns the cached result and audits as dedup. A repeat with the same requestKey but different arguments is rejected as a collision rather than silently answered.

A tool earns a place on that allowlist only when all three hold: a retry after a transient error is realistic, the repeat would leave a durable or immediately visible artifact, and an intentional same-argument repeat inside the window is not a normal use case. That last condition is what bounds the list:

GroupMembers
Panel and agent spawnsterminal.new, agent.launch, recipe.run
Worktree and workflow creationworktree.createWithRecipe, workflow.startWorkOnIssue, agent.launchInNewWorktree, worktree.resource.provision

Both worktree deletes are deliberately absent. Worktree ids are paths, and create, delete, recreate with the same path is a supported workflow, so caching a delete could report success for a second deletion of a genuinely different worktree. The forge writes that used to sit on this list left MCP with the Core and Full split, so no replay of them can arrive.

Note

git.commit and git.push were deliberately removed from this list, before git writes left MCP entirely. Neither takes an argument a legitimate repeat varies: git.commit commits whatever the index holds, and git.push gets only a working directory and an upstream flag. So a second push after a new commit (or a repeated wip message) is a same-argument call that would be swallowed as a cached success for work that never happened.

Navigation actions, repeatable commands and idempotent state-sets are excluded for the mirror-image reason: they create no duplicate to suppress, so caching buys nothing and costs correctness. In a set → unset → set sequence, the third call matches the first, the cached success returns, and the state stays unset.

Argument and error conventions

  • Selectors. Scoped actions take worktreeId or worktreePath, and projectId or projectPath. cwd, rootPath and path survive as legacy aliases. Where a default would be silently wrong, the selector is required rather than inferred.
  • Pagination. limit plus cursor or offset, returning items with hasMore, nextCursor and sometimes a total. An empty cursor string is rejected rather than treated as page one.
  • Errors throw. A returned { ok: false } serializes as a successful tool result, so failures must throw to reach the caller as failures. Errors carry a retriable flag; retry a false only once the arguments, context or authorization have changed.
  • Short agent ids. An MCP launch that names no panel id gets a short readable one (such as claude-7f3a), because a model repeats the id in every send, notice and close.
  • MCP Server: enabling the server, connecting a client, the tier model, agent panes and the audit log.
  • Authorization & Approval: how sessions get a tier, agent panes, widening and host confirmation.
  • Daintree Assistant: the in-app client that reaches the Core and Full tool sets.
  • Code Forge: provider setup behind the forge.* tools.
  • CopyTree: what copyTree.generateAndCopyFile bundles.
  • Fleet: the broadcast runs fleet.getRunStatus reports on.