Agent operation reference

Compact reference for the editor MCP server. Start with the skills catalog for task workflows or session tools for the user guide. tools/list is authoritative for the running version’s schemas; fields below omit JSON type boilerplate.

Notation: ? marks an optional argument; {} means no arguments. R is read-only, W changes editor/files/settings, X can execute/control programs, Q asks the user. These are descriptive categories: actual policy is selected per tool in Options > Agent Permissions. Read-only tools default to Enable; other tools default to Prompt. editor_settings can write, so even its read form uses that tool’s policy.

Buffers, files and search

Search: query is 1–256 characters on one line; offset 0–9999; limit 1–1000 (default 100). Skips binary/files over 1 MiB; caps the scan at 32 MiB and 10,000 files/matches. Inspect truncation flags. Filesystem mutations stay inside the project, refuse overwrite/dirty descendants, protect Git metadata and symlink endpoints, and do not recursively delete directories. Save uses disk-conflict checks. Private authority files and protected conversation contents are excluded or redacted across these surfaces.

workspace_project.cabalPlan reads only dist-newstyle/cache/plan.json; it does not invoke Cabal. status distinguishes available, missing, invalid, too-large, and unavailable. Available results include compiler/Cabal versions, plan modification time and age, package unit IDs/names/versions/type/style, local component references, and Cabal's depends/exeDepends edges. Nested Custom Setup components retain their separate dependencies. Package source roots are workspace-relative; external/protected paths, repository URLs, flags and compiler arguments are omitted.

freshness.status is stale when known manifests are newer or have unsaved edits, otherwise unknown: timestamps do not establish that a plan matches the current source or configuration. Check dependenciesKnown, graphComplete, omittedUnits and truncatedUnits before treating the result as complete. Reads stop at 8 MiB and inspect at most 4096 units; graph output is capped at 512 KiB and the full response at 1 MiB. Truncation removes whole units, retaining every reported unit's emitted dependency edges, which may refer to omitted units.

History

direction is undo (default) or redo. Preview offset 0–100, limit 1–10 (default 5); apply 1–100 steps (default 1). Insufficient history/stale revision fails without edits. Binary previews describe byte changes.

Haskell language service and Messages

Calls synchronize unsaved Haskell text. Editor input positions use 1-based Unicode code points; raw LSP results use 0-based UTF-16. Responses identify the source revision. Diagnostic messages are capped at 8192 characters. Code-action ranges default to the cursor; supply both end coordinates for a selection. A new action list expires previous IDs. Application requires the original source revision and unchanged affected files, excludes protected files and other projects, and never accepts caller-supplied edits or commands. Commands must be returned by the chosen action and advertised by that HLS process. A literal edit is applied before its command. HLS text edits affect buffers without saving; commands themselves can have server-side effects, such as evaluating doctests. File creation/deletion operations and unsolicited edits are refused.

Each command result includes succeeded, commandSucceeded, applied, appliedBatches, partial, error, and changed buffer revisions. A successful command response does not override a rejected edit. Each accepted edit batch is atomic; the whole command is not. Earlier accepted edits remain if a later batch, the command, or the waiting client fails. Every completed, failed, or canceled command retires that HLS process and invalidates its action IDs before another command can run. Relist actions on the new process; edit-only actions keep using the existing process. At most one command runs per project client, with at most 128 accepted edit batches and the existing 30-second request deadline. appliedBatches counts accepted batches, including empty or no-op batches; buffers lists only changed buffer revisions.

Build, test and execution

Builds require saved source buffers. Build/tests share one job slot. Read build output through read_buffer. Terminal output offsets refer to the retained tail; truncated reports discarded earlier output. Execution runs with the editor account’s access. UI privacy masks are not an OS execution sandbox.

test_status recognizes TAP 13 on stdout beginning with TAP version 13. It reports top-level test numbers, names, pass/fail, skip reasons, TODOs, and unexpected TODO successes. Each stream reports its planned and observed counts and whether it is complete, incomplete, invalid, or bailed out. Nested subtests and YAML diagnostics remain in the output buffer. Stderr never supplies test points. At most 500 cases and streams are returned, with truncation flags; failures beyond the case limit still fail the run. Missing/truncated output cannot establish completeness, and process failure always wins. Other runners retain suite-level results without guessed cases.

Debugging

follow: false keeps automatic stops in the background. follow: true follows future stops. An explicit view requires current generation; source/stack/scopes require a stopped, configured session. Reveal a view without changing follow mode by omitting follow. This does not launch or resume a separate debugger.

Refresh generation after execution changes. Stack/variable inspection requires a stopped target. Inspection pages default to 100 entries, maximum 1000. Breakpoints use 1-based lines, at most 1000. See the debugging skill, also published as thc-edit://debugging through MCP resources.

Git

Diff text is capped at 128 Ki characters. A path filter is a literal file path, not a Git glob/magic pathspec. Whole-repository diffs omit private authority files and Git-detected rename/copy destinations derived from them; omittedFiles reports a count without their names. Agent mouse/key input cannot open the unrestricted human Git review or commit dialog; use workspace_git for filtered review. workspace_search with trackedOnly: true searches tracked source. Commit-history search is not exposed as an agent tool.

Each Git tool has its own permission policy. Fetch shares the human Git operation slot, permits unsaved editor changes, and does not change working files. It accepts no remote URL, refspec, shell, or configuration overrides. Acceptance does not imply success: poll status for completion. The latest 16 agent jobs remain queryable for this session; omit jobId for the latest. busy also includes human Git operations. A launch failure has state: "failed" and a null exit code; a process exit reports its actual code. Transport output, URLs, and raw errors are not returned or placed in agent fetch output buffers. Normal Quit waits for the active operation; session teardown cancels and reaps the active Git process.

git_pull and git_merge use the same job slot. Both require saved editor buffers and a clean index/worktree, and refuse unfinished Git operations or hidden/sparse index entries. Pull fetches the configured default remote, then checks the configured upstream and performs an explicit fast-forward-only merge; it does not rebase or honor an automatic stash setting. Merge accepts a local or remote-tracking branch name (or its full refs/heads/ / refs/remotes/ name), not arbitrary revisions, URLs, refspecs, or options. Ambiguous and symbolic names are refused. Both pin the target commit and recheck the selected repository, HEAD, and authority policy before mutation. Typing while fetching prevents the merge; typing while Git runs preserves the unsaved buffer during reload.

Incoming protected paths, their ancestors, Git-detected private rename/copy sources, and changed symbolic links or submodules are refused. Unchanged tracked private configuration does not block safe changes. Protected differences between current HEAD and the target are also refused, even if a particular merge would leave them untouched; this prevents HEAD-side renames from redirecting incoming edits into private files. Agent merges disable Git's directory-rename propagation. Ignored local files are not overwritten. Normal configured Git hooks and merge drivers still execute; the path checks do not sandbox those programs. Status includes phase, head, fetchExitCode (pull only), and conflicts (count, or null if inspection failed). The ordinary exitCode is the merge exit, a failed fetch's exit, or null when preflight/launch prevented execution. A failed merge can leave conflict files and merge state; no automatic reset or abort discards them. A successful fetch remains effective even when the following merge is refused. No tool pushes.

git_review and git_commit also return acceptance and a job ID first. A review is a composite read operation: its successful exitCode: 0 denotes a completed review, not a single subprocess exit. Fetch and commit report actual process exit codes. A review covers staged, unstaged and untracked saved changes, with the same binary notices and content hashes as the human Git review. There is no partial commit or separate staging requirement. Both tools refuse dirty editor buffers. A review is refused if private changes (including Git-detected rename/copy lineage) would be omitted, its text exceeds 128 Ki characters, its private snapshot exceeds 1 MiB, or classification exceeds 10,000 files. An unchanged tracked private configuration does not block a safe review. No truncated or omitted review receives a committable ID; a clean repository has no commit ID.

Only the most recent complete review ID is valid. A commit attempt consumes it, rechecks the current privacy policy, and refuses changed HEAD, index or file contents. Raw snapshots remain server-side. Commit uses the existing whole-repo git add -A and normal Git hooks. Failure can leave reviewed changes staged; files are not rolled back. Ordinary hooks can alter files or the committed tree: reviewedTreeMatched: false reports a mismatch, and null means no successful comparison. head reports the observed resulting commit when available, including after a failed commit. A successful exit is retained even if that follow-up inspection fails. Hook output and raw errors are suppressed.

Windows, panels and binary navigation

Coordinates are 0-based character cells, text locations 1-based, byte offsets 0-based. Geometry obeys screen limits and docking; use returned rectangles. Files width is at least 16 cells; Messages height at least 3, within available screen space. Split windows share their buffer and undo history.

pin and unpin apply to terminal windows. Pinned terminals and Messages share one bottom panel; messagesHeight resizes it even when the Messages tab is hidden. editor_layout reports each window's pinned, visible and focused state and the panel's selectedWindowId (null for Messages). Focusing a hidden terminal selects its tab. Unpin before moving, resizing, zooming or splitting that window; tile/cascade leave pinned terminals in place. These operations preserve the running terminal and its IDs.

Screen and input

Input event forms:

{"type":"key","key":"F3","mods":[]}
{"type":"paste","text":"supplied text"}
{"type":"mouse","action":"down","x":10,"y":5,"button":0,"clicks":1,"mods":[]}
{"type":"mouse","action":"up","x":10,"y":5,"button":0}
{"type":"modifiers","mods":["ctrl"]}
{"type":"blur"}

Mouse actions: down, up, move, wheel-up, wheel-down; button 0 left, 2 right. Modifiers: ctrl, alt, shift. Keys: characters, Enter, Escape, Tab, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, Backspace, Delete, Insert, F1–F24. Paste is capped at 64 Ki characters per event. Input is not transactional: inspect partial results before retrying.

The host identifies input from an agent. Each batch starts without human clipboard, drag or key-prefix state; gestures may span events within the batch. Agent input cannot submit chat as the person, answer its own questions/approvals, modify agent settings/permissions or toggle Streamer mode. Generic reads and screen captures also protect drafts, authority files and session keys.

Screen capture is capped at 32,768 cells; PNG at 4 megapixels/2 MiB. PNG uses the bundled bitmap font, excluding OS chrome, CRT and native Unicode shaping. Clipboard text is capped at 1 MiB UTF-8 with no NUL; frontend permission can prevent OS export even after queueing succeeds.

Agent sessions and coordination

The primary conversation receives these tools through its authenticated editor server. Children receive an editor server for their own workspace and an agents server for coordination. Caller identity is assigned by the host; tool arguments cannot select another sender or redirect editor calls to another workspace.

Names are unique ignoring case, at most 80 characters without controls. Tasks and messages accept at most 65,536 characters. History pages default to 50 entries, maximum 100; search queries accept at most 4096 characters. Agent IDs remain stable when names change. A parent occupies its child's user seat; messages from other agents remain peer messages, not human instructions.

context defaults to fresh. fork requires sourceAgentId, caller ownership and actual provider fork support; it never silently starts a fresh conversation. Choose model and effort only from provider-advertised choices.

workspace defaults to {"mode":"shared"}. Use {"mode":"worktree"} with optional ref, branch and name for a separate Git checkout from committed source. Unsaved/uncommitted parent edits are not copied. Its editor runs without a display until opened, with separate buffers, build jobs, terminals and debugger. Shared children use their parent's editor and its existing job slots. Ending an agent does not delete its worktree.

Global [editor.agents] sets max_agents (default 8, range 1–64, including the primary) and max_subagents (default 4, range 0–64 direct children per agent). Project thc.toml may lower these ceilings; agents cannot raise them. Both limits are checked at spawn. See configuration.

Tools > Agents or Window > Agents opens the directory. Conversation shows live child messages, retained tool details and a protected human composer. Human messages to parent-controlled children retain peer attribution. Drafts, transcripts and view positions survive switching and editor recovery. Workspace opens the associated editor; Reconnect explicitly loads a recovered provider without replaying queued work. The human can change an idle child's advertised model/effort through its title menu and steer a reply when supported. Context usage is shown only when supplied by that child. These controls do not add a writable agent-settings MCP tool. agent_settings reports Primary's configuration and labels that scope, even when a child conversation is selected.

Conversation and settings

Questions: 1–4096 characters; up to 12 choices of 1–256 characters; allowMultiple must be false. One pending question, no human-answer timeout. Agent settings omit argument/environment values and session keys, returning only argument count and environment names; secret-labelled settings are redacted.

settings: appearance (light, dark, system), screenMode (3, 259), columns (40–512), rows (12–256), wordStar, blinkCursor, crtFilter, pixelateUnicode, materialIcons. Selecting a mode defaults to its 80×25/80×50 grid unless dimensions are supplied. defaults additionally accepts backend (terminal, auto, metal, vulkan, web, remote) and scale (1–8). Omitted fields remain unchanged. streamerMode is returned read-only. Current backend/pixel scale and agent settings are not changed by this tool.

Documentation

corpus is editor (default) or thc; compiler docs use the configured THC checkout. Paths are relative listed documentation paths. List/search page limit 1–100; read 1–500 lines, default 200. Search examines at most 256 files/16 MiB; reads accept UTF-8 documents up to 1 MiB and return at most 128 Ki characters. Use truncation and continuation flags. Start at docs/agent-skills.md for skills or this document for calls. Both are bundled for offline/site consumption.

Permissions and lifecycle

The host applies Enable/Prompt/Disable per invocation, including previously discovered tools. Policies live in [editor.mcp.permissions] in $XDG_CONFIG_HOME/thc/config.toml, falling back to ~/.config/thc/config.toml. Startup defaults use [editor.defaults]; precedence is CLI → environment → project defaults → global configuration. Project thc.toml can set defaults and agent context, but cannot override global permissions. See configuration.

A pending approval can be cancelled; cancellation does not undo an operation already executed. Long-running questions, HLS and debugger replies release the desktop lock while waiting. After a disconnect or uncertain reply, inspect current state before retrying a mutation. IDs belong to the editor session.

External clients connect with thc-edit --mcp-editor SESSION_ID. The bridge shares the session without taking over its display. Skills describe workflows; MCP tool schemas and host policy govern the actual calls.