Skip to main content
Glama
kitepon

aiterm-mcp

by kitepon
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

From any MCP client, launch Claude Code, Codex CLI, Grok CLI, or Cursor Agent CLI through one harness API inside a persistent interactive TUI.

Aiterm

CI npm weekly downloads node license: MIT

(日本語: README.ja.md)

Let your AI orchestrate other AIs. One agent_launch call selects the execution harness separately from its model and hands you a persistent session to drive. Cursor can run GPT, Claude, or Grok while Cursor still owns the session, hooks, and transcript.

What it is: one persistent MCP terminal your AI drives — and can launch other coding agents into. ssh, docker exec, a REPL, or another agent's TUI all nest inside that one terminal as just text you send in. The mechanism is deliberately plain — your MCP client drives the other agent's terminal turn by turn: no hidden protocol, no separate aiterm-owned shared-memory layer, no autonomous negotiation. Launched agents still read the normal project and harness memory/configuration that a direct CLI launch would use.

No human at a terminal required. aiterm is driven programmatically over MCP, so an AI can launch and drive another agent with no one sitting in the terminal — from an orchestration loop, a CI step, or a cron job.

MCP = Model Context Protocol — the open standard that lets tools like Claude Code plug capabilities into an AI.

Built and maintained by Quo at kitepon.dev.

Install in your MCP client

検出したClaude Code・Codex・Grok・Cursorのユーザー設定へ登録する標準入口:

npm install -g aiterm-mcp@latest
aiterm-setup --json

aiterm-setupは端末の依存準備、MCP経由の端末実行、登録と読戻しまでを一回で行う。 WindowsはwingetでPowerShell 7・Git for Windows・psmux、macOSはHomebrewでtmux、 Ubuntu／Debianはsudoとaptでtmuxを準備する。必要な公式package managerと実行権限は事前に必要。 他のLinuxでも既存tmuxを利用できるが、自動導入はunsupportedで停止する。 既存設定の他サーバーを保持し、JSON設定は変更前の.aiterm-backupを残す。 結果のstatusはready／unsupported／failed。未検出のAIはnot_detectedとし、全AI未検出は成功にしない。 登録先はglobal packageのNodeとMCP入口の絶対パスで、npm一時cacheやsource checkoutは登録しない。 更新後も同じ入口を実行し、MCP clientを再起動する。npm install自体はユーザー設定を変更しない。 公開JSONはschema: "aiterm.setup-result.v1"、全体のstatus、端末のbackend、 AI別のintegrationsを持つ。失敗時はreason_codeを付け、終了コードはreadyなら0、それ以外は2となる。

No clone or build is required. Each client launches the published package with:

npx -y aiterm-mcp

Requires Node.js ≥ 18 and a supported multiplexer backend: tmux on POSIX or psmux 3.3.8+ on native Windows. Driving Codex also requires the Codex CLI to be installed and authenticated.

Claude Code

Add it for your user account:

claude mcp add --scope user --transport stdio aiterm -- npx -y aiterm-mcp

Or commit this as a project-scoped .mcp.json:

{
  "mcpServers": {
    "aiterm": {
      "command": "npx",
      "args": ["-y", "aiterm-mcp"]
    }
  }
}

Claude Desktop

Add this server to claude_desktop_config.json:

{
  "mcpServers": {
    "aiterm": {
      "command": "npx",
      "args": ["-y", "aiterm-mcp"]
    }
  }
}

Cursor

Save this as .cursor/mcp.json for the project, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "aiterm": {
      "command": "npx",
      "args": ["-y", "aiterm-mcp"]
    }
  }
}

Ownership boundary: this repository owns installation, configuration, persistent PTYs, agent sessions, state/schema/migrations, diagnostics, recovery, updates, and releases. It can be cloned and operated on its own using this README and the product docs. dotagents optionally integrates Aiterm into the wider factory—host wiring, cross-product compatibility, and aggregate acceptance—but does not control Aiterm and is not a runtime dependency.

Measured, not claimed: in the recorded 203-test benchmark, a pty_read puts ~7.1× fewer tokens in your context than the raw log — and the pass/fail verdict survives the fold. → When to reach for it vs. the built-in shell

Eighteen tools: seven PTY tools — pty_open / pty_send / pty_read / pty_key / pty_close / pty_list / pty_observe — to open, drive, read, and observe one persistent terminal; one canonical agent launcher, agent_launch, which selects claude-code, codex-cli, grok-cli, or cursor-cli as the execution harness; agent_steer for an active Codex or Grok turn; four deprecated launcher aliases kept for migration; agent_configure; agent_approval; claude_turn; claude_approval; and diagnostics. The backend is tmux on POSIX and psmux on native Windows, so sessions survive even if the MCP server or the AI client restarts.

v0.28.0 separates the execution harness from the model. The harness owns the agent loop, authentication, hooks, session, and transcript; model is what that harness runs. Cursor Agent CLI can therefore select GPT, Claude, or Grok without changing the completion contract from Cursor hooks to another harness's. Grok Composer is a Grok CLI model preset, not another harness: use harness: "grok-cli", model: "grok-composer-2.5-fast". The old four launcher tools are thin compatibility aliases over the same implementation.

v0.25.2 stabilizes repeated in-place configuration changes, including Grok 4.6. If Grok Build 1.0.3 redraws before its /model success notice can be observed, aiterm confirms the requested model/effort from the persistent footer when that state was absent before the command. Callers do not retry, restart, or round a failure into success; explicit grok-4.6 launch and configuration still pass the live catalog check.

v0.25.0 gives Grok and Composer the same shared launcher controls. Their launchers now pass reasoning_effort, enforce write_scope: "read-only" with --sandbox read-only, and support in-place model/effort changes through agent_configure. Before creating a PTY, aiterm checks an explicit Grok/Composer model—and Composer's default model—against the live grok models catalog. An unavailable model fails visibly instead of letting the harness CLI fall back to another model.

v0.24.3 forwards explicitly selected launcher environment variables from the current MCP process. Pass variable names in env_vars; aiterm reads their current values at launch and injects only the present ones into that agent. This works even when the persistent multiplexer server predates the MCP process, so a stale backend-server environment cannot erase per-seat identity or workflow variables. It also recognizes Codex v0.147's optional fast token in long-lived model/effort footers, keeping agent_configure available on an idle medium fast · session without redraw, retry, or restart.

v0.24.2 keeps in-place configuration working in long-lived Codex sessions. Once the startup header has scrolled out of the captured pane, aiterm recognizes Codex by its persistent model/effort footer together with the input prompt. An idle session is therefore configured directly; callers do not need to redraw the TUI, retry, or restart the agent.

v0.24.0 adds in-place agent configuration. agent_configure uses each harness's native controls to change the model and/or reasoning effort of a running Codex or Claude session while preserving its PTY, harness session, and conversation context.

v0.23.0 adds a local, cross-harness portable fork. Pass throughline_source_session with a mission in prompt to any launcher, and aiterm asks the locally installed Throughline for that session's read-only handoff context before creating the PTY. The exact returned memory is prepended to the mission without moving or copying the source session's database ownership. If Throughline is missing or returns an invalid/empty result, launch fails visibly with no clean fallback. Omitting the field preserves the ordinary clean launch.

v0.22.0 makes launched agents full project collaborators. All four launchers now use the same normal HOME, working tree, harness home, project/user/local configuration, MCP servers, plugins, skills, permissions, trust, memory, and session history as a direct CLI launch. Aiterm isolates only its own per-launch completion correlation state. Every child is told that it is a sub-agent and receives its parent session, delegation depth, lineage, and delegation_allowed=true; a child may delegate further, while the lineage makes reflexive self-copy loops visible and avoidable. The historical managed_completion receipt field remains for API compatibility and means “completion correlation enabled,” not environment isolation.

v0.21.3 removes Codex Stop hooks from the completion path. Codex completion and final-message attribution now come from the root rollout transcript's durable task_complete.turn_id, observed after the dispatch byte boundary. A broken or stale hook executable can no longer strand aiterm-wait. v0.21.0 added explicit write_scope declarations for external-agent launchers; v0.21.3 also fixes their structured launch receipts so a supplied scope and its enforcement status are retained. v0.20.3 prevents concurrent correlated Claude/Fable sessions from turning one broken login into many competing login flows. Every new Claude launch verifies the harness-owned shared credential store before creating a PTY, while healthy credentials remain reusable across concurrent and repeated sessions. The v0.20 line also distinguishes a non-blocking aiterm-wait --timeout 0 observation (running, exit 5) from a real timed-out wait. The v0.19 line added the correlated Claude approval relay, preserved multiline shell delivery, and extended factory diagnostics on native Windows. As of v0.16/0.17 a parent agent never blocks on aiterm: agent sessionへの送信は非ブロックdispatchであり、Codex／Claude Code親には回答本文を自動配送する。 それ以外の親はreceiptのprocess起動情報でaiterm-waitを実行する。 終了コードは0=done、3=timeout、4=closed、待機しない照会の5=runningを表す。 Factory diagnostics and the local runtime-error store collect only when canonical dotagents config explicitly sets collection.enabled: true; collection is off by default and performs no network I/O. It ships via tag-triggered CI with npm provenance (OIDC Trusted Publishing); the GitHub Release re-registers the Official MCP Registry entry.

Status: actively maintained · current public release v0.35.1 · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible psmux on native Windows — no WSL required) · MIT · see the CHANGELOG.

Update and rollback

The npm package is the standalone distribution; dotagents is not involved. For a global install, update with npm install -g aiterm-mcp@latest and aiterm-setup --json. To roll back, install a known-good immutable version, for example npm install -g "aiterm-mcp@<known-good-version>", then restart the MCP client. setupを持つ版では再起動前にaiterm-setup --jsonを再実行する。For an npx configuration, use aiterm-mcp@latest to update or replace it with aiterm-mcp@<version> to pin or roll back. Check the CHANGELOG for state/schema compatibility before downgrading. Maintainer release and artifact rollback are specified in the product-owned release procedure.

Related MCP server: claude-tmux

Why now

A lot of 2026's agent tooling is converging on orchestration: a lead model delegating a mechanical refactor to Codex, running Composer on a bulk edit while it reviews the diff, fanning one task across several agents to spare its own context window. All of those agents already live in a terminal. aiterm makes that terminal a first-class, MCP-native tool — so the model doing the orchestrating can spawn and steer the others without a human wiring up panes.

Built with Codex and GPT-5.6 for OpenAI Build Week 2026

aiterm predates Build Week, so the event work is kept visible in dated commits. During the submission window (July 14–16, 2026), I extended it with safe serialized delivery for long PTY input, correlated operation IDs and bounded result recovery, machine-readable launch and idempotent close receipts, and a hardened readiness gate that prevents prompts from disappearing during TUI startup redraws. The public comparison from the pre-event release is v0.12.2...main.

I used Codex with GPT-5.6 as an engineering collaborator: it inspected the implementation, challenged the API and recovery contracts, generated focused regression cases, and helped verify race, security, timeout, and malformed-event paths. I reviewed the diffs and test evidence and retained the final product and architecture decisions. At that Build Week checkpoint, the regression suite contained 262 tests covering normal operation as well as failure and recovery behavior; current release receipts live in the CHANGELOG and release ADRs.

Two ways to use it

1. Drive SSH, containers, and REPLs in one persistent terminal — the primitive

This is the base, and it works with just the platform backend — tmux on POSIX or psmux on native Windows. pty_open grabs one local terminal; ssh host, docker exec -it x bash, or a REPL are just text you pty_send into it — once. Every command after that rides the same already-authenticated session. Session kind is never a tool-level distinction.

pty_open()                         → grab one local terminal
pty_send(id, "ssh 192.168.1.2")    → authenticate once, inside that terminal
pty_send(id, "uname -a")           → every later command rides the SAME session
pty_read(id, { wait: true })       → read the token-reduced output, completion detected

Origin. I built aiterm for exactly this. Driving my homelab from Claude Code one command at a time meant every SSH command became its own connect → authenticate → disconnect: re-typing the passphrase and one-time code each time, short-lived sessions piling up, and eventually my own defenses (fail2ban, MaxStartups/MaxSessions, account lockout) locking me out — the security meant to stop attackers ended up stopping me. Holding one authenticated session fixes all three at once. That pain is why the persistent terminal exists; launching whole other agents inside it is what it grew into.

2. Launch other coding agents into that terminal — the orchestration flagship

The same primitive hosts another agent's TUI. agent_launch starts a selected execution harness inside a fresh persistent terminal and returns a session_id. harness names the component that owns the agent loop, authentication, hooks, session, and transcript; model remains an independent choice. The launched process sees the same project and user environment as a direct CLI invocation: normal configuration, MCPs, plugins, skills, permissions, trust decisions, memory, and history are not copied, filtered, or replaced. Aiterm adds only completion correlation and a non-user sub-agent context containing role=subagent, the parent session, delegation depth, lineage, and delegation_allowed=true.

起動結果には正規harnessを含むaiterm.agent-launch-result.v1が付き、旧providerは互換fieldとして残る。同じharnessはagent dispatch、aiterm-wait、agent_configure、pty_listにも載る。Codexは通常rollout、Grokは通常session event、Claudeはlaunch固有Stop hook、Cursorは通常agent transcriptのturn_endedを完了正本に使う。agentへの送信は非ブロックdispatchで、harnessごとの完了境界を表す整数event_cursorを返す。Codex親は公式queue、Claude Code親は公式非同期hookで本文を自動受信する。他の親はaiterm-waitを使う。CursorのsubmitはadapterがCLIのextended keyboard protocolへ変換し、送信本文がcomposerへ残る場合は明示errorにする。

agent_launch, pty_send (agent dispatch), and agent_steer accept an optional image: an array of absolute paths to image files (png/jpg/jpeg/gif/webp). Aiterm appends an attachment block to the prompt, and every harness opens the path with its own file-reading tool and sees the image; the caller never learns harness-specific attachment tricks. Invalid paths are rejected before anything is sent.

agent_launch accepts an optional write_scope: either "read-only" or a human-readable description of writable paths. Codex/Grok use --sandbox read-only; Cursor uses its official read-only --mode ask. A path description remains declaration-only because these CLI launch surfaces provide no equivalent path allowlist flag.

Grok／Composerの無人起動は公式--trustで指定された作業フォルダを信頼登録し、確認画面を完了してから初回promptを送る。この登録はGrok CLIの信頼ストアへ保存され、フォルダ内のhook・MCP・LSPにも適用される。read-only sandboxの制限は維持する。画面に残る完了済みhookの結果は実行中と判定しない。

Grok／Composerがread-only sandboxの適用を拒否した場合、prompt送信時にGROK_SANDBOX_STARTUP_FAILEDとCLIの原因を返す。hookパスのシンボリックリンクなど、CLIが示した原因を設定の管理元で修正し、対象sessionをpty_closeして起動し直す。Aitermはsandboxを解除したりhookをコピーしたりしない。

この判定はGrok専用アダプターが所有し、同じCLIを使うComposerにも適用する。初回prompt付きのagent_launchと通常のpty_sendで、入力受付待ち中に拒否を検出すると未送信のエラーを返す。promptなし・trust_project指定なしの起動応答は入力受付を保証しない。trust_project:trueでは入力受付まで確認し、startup.statusを返す。Grokのprivacy notice起動設定も同アダプターが所有する。実装の責務分担はDESIGNを参照。

For a correlated Claude turn stopped at Do you want to proceed?, use claude_approval(action: "inspect", ...) to capture the active operation and SHA-256 screen digest, review the displayed command, then call respond with that exact digest and either approve_once or deny. The relay rechecks the operation and screen under the send lock, never exposes arbitrary input or permanent approval, keeps the active marker intact, and records a prompt-free owner-only receipt. pty_send(force: true) does not bypass this boundary.

agent_launch({ harness: "codex-cli", session_name: "codex1", cwd: "/repo",
              prompt: "port test/legacy.py to vitest",
              model: "gpt-5.6-sol", reasoning_effort: "high",
              write_scope: "test/ only; no commit" })
                                    → { session_id: "codex1", … }   # Codex now live in a persistent terminal
pty_read("codex1", { screen: true })   → read what it's doing (token-reduced)
pty_send("codex1", "also fix the imports it broke")
                                    → non-blocking dispatch; receipt carries event_cursor
# Codex／Claude Code親には回答が自動で届く。それ以外の親:
$ aiterm-wait --session codex1 --cursor <event_cursor>   # never in the parent's foreground; exit 0=done, 3=timeout (not done), 4=closed, 7=error (turn aborted by an API error)
pty_read("codex1", { agent_transcript: true })           → collect the full answer

The canonical harness choices are:

harness

Launches

Notes

claude-code

Claude Code CLI

Claude model and effort controls; correlated Stop hook

codex-cli

Codex CLI

OpenAI model and effort controls; durable rollout completion

grok-cli

Grok Build CLI

Grok or Composer model selected with model; live catalog check

cursor-cli

Cursor Agent CLI

GPT, Claude, Grok, or another Cursor catalog model; normal transcript completion

env_vars is an allowlist of environment-variable names, not a name/value map. At launch, aiterm reads each valid name from its current MCP process, shell-quotes present values, and places them on that one harness launch command. Missing names are omitted; invalid shell variable names fail before session creation. There is no implicit whole-environment copy, backend-server restart, retry, or fallback. Values do not enter the MCP tool arguments, but they are delivered through the PTY launch command and retained in aiterm's per-session .lastcmd; the launched harness and other processes with access to the same OS user may read them. Use this for non-secret seat identity and workflow variables, not as a secret transport.

The selected harness CLI must be installed and authenticated. Aiterm resolves CLAUDE_BIN / CODEX_BIN / GROK_BIN / CURSOR_AGENT_BIN, then the documented default binary, then PATH. Cursor resolution deliberately uses cursor-agent, never the ambiguous agent name. Claude and Cursor authentication are checked before a PTY exists, so a failed preflight leaves no session. All harnesses use their normal harness-owned credential and configuration stores in place. For Grok, Aiterm does not lock, inspect, or modify the credential. A non-empty inherited GROK_AUTH_PATH must be absolute and exist; Aiterm passes it unchanged to Grok. Grok owns its contents, permissions, and link handling. Absence of the default auth file is accepted only when XAI_API_KEY is set.

Portable fork is optional. When throughline_source_session is present, prompt is the required new mission and launch_operation_id cannot be combined with it. aiterm resolves Throughline via THROUGHLINE_BIN and then PATH, runs throughline handoff-context --session <id> --json, and places its returned context before a fixed separator and the mission. This route requires throughline >= 0.9.0; throughline_supplement_file requires Throughline 0.10.8 or later. Aiterm appends --supplement-file <path> without reading or interpreting the file. Throughline owns its project binding, validation, and shared context budget. The route reads source memory without changing database session ownership. No Throughline dependency is needed when the field is omitted.

Harness adapters translate model and reasoning_effort into each CLI's public controls. Explicit Grok models are checked against grok models; Cursor combines a base model such as gpt-5.6-luna with a separate effort such as high, checks the resulting current catalog ID, and uses Cursor's standard model picker for in-session changes. Missing models are errors, with no cache, retry, or fallback. Claude adds only launch-local Stop-hook settings, Codex reads its normal rollout store, Grok reads its normal session event/history, and Cursor binds its normal agent transcript with the launch ID. Pass an absolute cwd; ~ is not expanded.

There is no hidden protocol between agents: every launched harness is another user-visible persistent terminal session. The MCP client drives that TUI with ordinary PTY operations, and a human can attach to watch or take over.

Demo

Real captured output — each block below was just run through aiterm in this repo; the numbers, the elision marker, and every is_complete verdict are the tool's own, not mocked. The bracketed meta line is what pty_read appends; its labels are Japanese in the actual output, translated here for readability (the Japanese README shows them verbatim).

A long output folded head+tail — the middle is elided by the reducer, not by me (166 → 56 tokens):

→ pty_send("demo", "seq 1 150")
→ pty_read("demo", { wait: true })
← 1
  2
  3
  ⋮  (head runs to line 29 — abbreviated in this README)
  … ⟨102 lines elided · full=true, or line_range="A:B"⟩ …    ← the tool's own marker
  ⋮  (tail resumes at line 132 — abbreviated in this README)
  149
  150
  [aiterm demo: 51 lines / ~56 tok (raw 152 lines / ~166 tok); 102 lines hidden] [is_complete=True via quiescent]

A grep, folded by the per-command reducer to a count header plus just the hits:

→ pty_send("demo", "grep -rn capture-pane src/ test/")
→ pty_read("demo", { wait: true, rtk: true })
← 2 matches in 1 files:

  src/core.ts:159:// maxBuffer defaults to 1 MiB; capture-pane (large scrollback) … (line truncated here)
  src/core.ts:335:const args = ["capture-pane", "-p", "-J", "-t", name];
  [aiterm demo: rtk:grep applied / ~46 tok (raw ~53 tok)] [is_complete=True via quiescent]

Nesting is just text you send in — here a Python REPL inside the same PTY (an ssh host, a docker exec -it … bash, or a launched coding-agent TUI nests exactly the same way):

→ pty_send("demo", "python3")
→ pty_read("demo", { until: ">>>" })                # nested prompt = "the inner shell is ready"
→ pty_send("demo", "print(sum(range(1_000_000)))")
→ pty_read("demo", { wait: true, until: ">>>" })
← 499999500000                                      [is_complete=True via until]

The only edits to the captures above are the two ⋮ lines (a long head/tail run abbreviated for the README) and one over-long grep line truncated to fit — the ⟨…⟩ marker, the token counts, and every is_complete verdict are exactly what the tool printed. (Use until: ">>>" without a trailing space — the captured prompt is trimmed, so ">>> " would miss and fall through to timeout.) While nested, pass until (the inner prompt) or mark: true, because quiescence cannot fire there by design — see Completion detection and Known constraints. A human can attach to the same multiplexer backend and watch any of this live (see A human can watch).

First run (≈60 seconds)

aiterm-setup --jsonがreadyになったら、利用するMCP clientを再起動して接続を確認する。Claude Codeの場合:

/mcp        # aiterm should show as connected, exposing 18 tools

Your first session — four calls, one persistent terminal:

pty_open()                          → { session_id: "t1", attach: "<platform attach command>" }
pty_send("t1", "echo hello")        → command sent into the PTY
pty_read("t1", { wait: true })      → "hello"   (token-reduced, completion detected)
pty_close("t1")                     → terminal released

pty_close is idempotent and returns a structured closed / already_closed receipt, so durable callers can retry the same session_id after losing the MCP response.

That's it. The terminal in t1 is real and persistent — ssh, docker exec, a REPL, or a launched agent's TUI are just things that live inside it. To launch a worker agent instead, one call does it: agent_launch({ harness: "codex-cli" }) returns a session_id you drive with the same pty_read / pty_send.

Prefer a global install, or a different client?

# install globally, then register the command name
npm i -g aiterm-mcp
claude mcp add --scope user --transport stdio aiterm -- aiterm-mcp

This registers it in ~/.claude.json; you'll get an approval prompt the first time. For client-specific JSON, see Install in your MCP client.

Headless: no human at the terminal

Because an MCP client drives aiterm programmatically over stdio, everything above can run with nobody sitting at the terminal. Any MCP-capable orchestrator can call agent_launch — including a harness matching itself — then pty_read the result and act on it unattended. That makes aiterm a fit for exactly the places a human-driven terminal isn't:

  • Multi-agent orchestration — an orchestrator hands sub-tasks to Claude Code / Codex / Grok / Cursor harnesses, each in its own persistent session, and reads them all back. Composer remains a Grok CLI model preset.

  • CI — a job step can spin up an agent, drive it, and tear it down.

  • cron — a scheduled run can launch an agent and collect its output.

The terminal is real and shared, so a human can jump in (A human can watch) — but nothing requires one to.

How it works

flowchart LR
    AI["AI / MCP client<br/>(the orchestrator)"] -->|"pty_send · pty_observe · agent_launch · agent_steer · agent_configure · agent_approval · claude_turn · claude_approval<br/>legacy launcher aliases · diagnostics"| S["aiterm-mcp<br/>stdio MCP · 18 tools"]
    S -->|"pty_read<br/>token-reduced"| AI
    S -->|"tmux / psmux<br/>send · capture"| P["persistent PTYs<br/>survive restarts"]
    P -->|"ssh · docker · repl"| R["nested<br/>remote · container · REPL"]
    P -->|"launches a fresh PTY per agent"| A["another coding-agent harness<br/>Claude Code · Codex CLI · Grok CLI · Cursor CLI"]

One PTY is the only primitive. Everything else — SSH, containers, REPLs, and the launched agent TUIs — is just something interactive running inside a persistent terminal, driven with the same pty_send / pty_read. Each launcher opens its own fresh PTY. Because the PTYs live in tmux on POSIX or psmux on native Windows, sessions outlive the MCP server and the AI client.

When to reach for it vs. the built-in shell

Your MCP client already has a shell tool, and it wins on some jobs. aiterm wins on others. We measured both on the same commands in this repo, counting tokens the same way on each side (characters ÷ 4, aiterm's own estimator), so the comparison is apples-to-apples.

Start with the built-in tool for a light one-shot. git log --oneline -5 is one round-trip; aiterm is two — pty_send then pty_read — and that second round-trip costs more than a light command saves (~7 s vs ~13 s).

The second round-trip pays for itself once the output runs long, or the state has to outlive the call.

Command

Built-in shell

aiterm

Verdict

git log --oneline -5

1 call, ~7 s

2 calls, ~13 s

shell (fewer round-trips)

npm test (203 tests)

~4,292 tok

~607 tok

aiterm (~7.1× fewer, verdict kept)

find node_modules -type f

~500 tok¹

~456 tok

tokens tie; aiterm keeps head and tail + line_range

grep -rn "session" src/

~2,989 tok

~1,096 tok

aiterm (~2.7×; long lines get clipped²)

In the recorded 203-test benchmark the reduction is real and safe. The built-in tool drops the whole 223-line log — ~4,292 tokens — into context. aiterm folds its own capture of the run down to ~607:

[aiterm demo: 51 行 / ~607 tok (raw 223 行 / ~4292 tok); 172 行 hidden] [is_complete=True via mark]

行 = lines; the meta line is quoted verbatim from aiterm's real output.

That is about 7.1× fewer tokens reaching the model, and the verdict survives the fold: the tail still carries ℹ tests 203 / ℹ pass 203 / ℹ fail 0. The reduction drops the noise and keeps the line you opened the log for. Wall-clock effectively ties, so on a run this long the extra round-trip is a small part of the total.

aiterm also holds state across calls. The built-in tool runs each call in a fresh shell, so cwd resets between calls and the environment doesn't carry. Send cd /tmp && export BENCH_VAR=hello123, then read it back in a second, separate call:

built-in shell  →  var=                   # empty; env dropped, cwd back at project root
aiterm          →  cwd=/tmp var=hello123  # one persistent PTY holds both

cd then set env then build, ssh once then run ten commands on the authenticated session, drive a live REPL or a launched agent's TUI turn by turn — one persistent PTY holds all of it. Reach for aiterm when the terminal has to remember something.

¹ Today's harness auto-offloads the ~192 KB dump to a file and previews only a ~2 KB head, so the token counts nearly tie; aiterm reports the accurate line count and lets line_range="A:B" pull any slice later, head or tail. ² The rtk grep reducer truncates long lines (~80 chars) and folds the overflow into [+N more], which suits scanning; use the built-in tool when you need every full line.

vs. the alternatives

aiterm sits at the intersection of two families: terminal-driving MCP servers, and the newer "agents talk to each other through a shared terminal" idea (see Where aiterm fits). Here's how the axes line up — honestly, including where the others are strong.

aiterm-mcp

one-shot shell MCP(e.g. mcp-server-commands)

terminal / SSH / tmux MCPs(e.g. iterm-mcp, ssh-mcp, tmux-mcp)

shared-tmux agent-to-agent(e.g. smux)

Persistent session

✅ tmux / psmux, survives restarts

❌ new shell every call

⚠️ varies

✅ tmux

SSH / containers / REPLs

nest with one pty_send

reconnect every command

⚠️ often separate tools

✅ tmux (human drives)

Launch another agent in one call

✅ agent_launch(harness=…)

❌

❌

⚠️ agents join a human-run tmux via a CLI + skills

Headless (no human at a tmux)

✅ MCP-driven, programmatic

✅

⚠️ varies

❌ built around a human in the tmux

MCP-native (any MCP client)

✅ one claude mcp add

✅

✅ (they are MCPs)

❌ tmux config + CLI + Agent Skills

Token-reduced reads

✅ per-command reducers

❌ raw output

⚠️ rarely

❌ raw tmux

Completion detection

5-layer: exit / mark / until / quiescence / timeout

n/a (blocks per call)

⚠️ prompt-match, fragile

❌ agent reads the pane

Human can co-drive

✅ shared socket / namespace (attach)

❌

⚠️ varies

✅ (its core model)

Where aiterm fits

"AIs talking to each other through a shared terminal" is becoming its own category — and it's a genuinely good idea. The terminal is a universal interface every coding agent already speaks, so no bespoke agent-to-agent protocol is needed; the shell is the shared surface. smux (by @shawn_pana) popularized this framing as a one-command shared tmux environment a human sets up, that agents then join via a tmux-bridge CLI and Agent Skills. It's good at the in-the-loop, shared-pane workflow it's built for, and it has real traction.

aiterm takes the same core insight — the terminal as the meeting point — and makes three deliberate, different choices:

  1. Headless by construction. Because aiterm is driven programmatically over MCP, an AI can launch and drive another agent with no human sitting in the tmux — from an orchestration loop, a CI step, or a cron job. The shared-tmux tools lead with a human at the keyboard (their docs center on interactive pane navigation), so unattended operation isn't their native mode; aiterm's is.

  2. MCP-native, not a workflow you adopt. aiterm is a stdio MCP server: one claude mcp add line and it works as structured tools in any MCP client that speaks stdio (tested in Claude Code; Cursor, Cline, and Claude Desktop speak the same protocol and should work the same way). It doesn't ask you to adopt a tmux config, learn pane navigation, or install skills into your setup — the client already knows how to call tools.

  3. Launching an agent is one tool call — an orchestration primitive. agent_launch({ harness: "codex-cli" }) spawns Codex in a persistent terminal and returns a session you drive immediately. You don't arrange panes or paste between them by hand; the launch, the steering, and the reads are all tool calls the orchestrating model can make on its own.

On top of that sits a productized layer a raw tmux bridge doesn't have: token-reduced reads and 5-layer completion detection. None of this makes the human-in-the-tmux model wrong — it's a different, complementary bet on where the human is standing.

Tools

Session observation and startup

pty_open defaults to bash on POSIX and PowerShell 7 on Windows. Ordinary terminals and agents receive AITERM_SESSION_ID. Pass environment-variable names in env_vars to inherit ownership information from the MCP process. pty_list({ env_keys: ["JOB_OWNER"] }) returns only the requested non-secret values in environment; missing values are null. Its aiterm.pty-list-result.v1 receipt contains observed_at and sessions, whose entries include session_id, current_command, attached, width, height, harness, and environment. Existing text remains available.

pty_observe({ session_id, cursor? }) returns aiterm.pty-observe-result.v1 with exists, observed_at, state (busy/idle/blocked/dead/missing/unknown), reason, pane_alive, and harness_alive. pane_process and harness_process are separate identities. process_identity selects the harness for agents, or the unique child process-group leader for an ordinary terminal, using the pane when no child leader exists. An identity contains pid, process_group_id, started_identity, and argv_digest; unresolved identities are null. Windows PIDs are native and its process-group field is null. Start identity uses POSIX LC_ALL=C ps lstart or Windows UTC ISO milliseconds; the argv digest is SHA-256 hex.

Pass activity.cursor into the next observation to obtain output_changed and cpu_delta_seconds; first observations and recreated panes return null differences. cpu_seconds is the current subtree's cumulative CPU. If a process disappeared between observations, the delta covers only observed increments and cpu_delta_complete is false. background_cpu_seconds, background_cpu_delta_seconds, and background_cpu_delta_complete apply the same measurement only to descendants created at least 60 seconds after the pane, excluding startup MCP processes. token_hint is the latest displayed token count or null. Callers do not need raw argv or pane-text parsing.

agent_launch({ harness, cwd, trust_project: true }) completes known workspace, project-hook, and project-MCP startup consent even without a prompt, then verifies input readiness and harness liveness before returning startup.status="ready". A prompt-free launch without this option retains startup.status="not_checked". initial_prompt.status distinguishes not_requested, not_sent, submitted_unconfirmed, and started. Failure responses retain structured session information. Do not resend an unconfirmed prompt; observe or wait using its returned cursor.

For a live Codex approval, inspect with agent_approval({ action: "inspect", session_id }), review prompt and choices, then respond with observed_prompt_digest and approval_choice (approve_once or deny). Unknown or changed dialogs return status="blocked" and isError:true without sending input. Permanent approval is not exposed. Correlated Claude approvals continue to use claude_approval.

Tool

Role

Key args

pty_open

Open one terminal and return a session_id

name?, shell?, env_vars?

pty_send

Send text; on an agent session this is a non-blocking dispatch returning an event_cursor

session_id, text, enter=true, mark, force, rtk, raw

pty_read

Read output, token-reduced (incremental by default)

session_id, wait, until, until_regex, timeout, screen, full, lines, line_range, raw, rtk, agent_transcript, operation_id

pty_key

Send a control key

session_id, key (C-c/Enter/Up…)

pty_close

Close idempotently; return closed / already_closed

session_id

pty_list

Text and structured session list, with explicitly requested non-secret environment values

env_keys?

pty_observe

Pane/harness liveness, native process identity, state, and activity

session_id, cursor?

agent_launch

Canonical agent launch; harness and model are independent

harness, prompt?, model?, reasoning_effort?, cwd?, write_scope?, trust_project?, env_vars?, throughline_source_session?, throughline_supplement_file?

agent_approval

Inspect a Codex approval and submit a one-time approval or denial

action, session_id, approval_choice?, observed_prompt_digest?

agent_steer

Inject text into the active Codex or Grok turn; return idle without sending when no turn is active

session_id, text

claude_agent / codex_agent / grok_agent / composer_agent

Deprecated compatibility aliases

legacy launcher arguments

agent_configure

Change model/effort in a running Claude, Codex, Grok, Composer, or Cursor session without restarting it

session_id, model?, reasoning_effort?

claude_turn

Issue (dispatch-only) or recover one correlated Claude operation

action, session_id, operation_id, text?

claude_approval

Inspect or answer the current correlated Claude approval prompt

action, session_id, operation_id?, approval_choice?, observed_prompt_digest?

diagnostics

Read-only factory readiness as machine-readable JSON

(none)

diagnostics never starts a PTY or agent. It reports package version, MCP call readiness, a read-only PTY-list summary, bounded runtime-error-store status, and optional vendor-launcher availability. It deliberately excludes paths, environment values, credentials, command text, PTY output, and raw logs; normal unset optional dependencies are not_applicable, while an indeterminate probe is unverified.

Local runtime error snapshot

aiterm-runtime-errors snapshot exposes a machine-readable, product-owned local snapshot for the dotagents factory adapter. Collection is fail-closed unless the canonical dotagents factory-reporter config is schema-exact, its host profile matches the executing OS, and it contains the JSON boolean collection.enabled: true; reporting fields are schema-validated but endpoints and credential files are never contacted, and the store performs no network I/O. The only accepted observations are three fixed codes owned by the core boundary (PTY dependency, persistence, and optional vendor launcher). Stored data is limited to fixed templates and aggregate metadata (SHA-256 fingerprint, count, first/last seen, status, and monotonic sequence); exceptions, stderr/stdout, stacks, prompts, terminal/transcript/event bodies, paths, and arbitrary context cannot enter the API. Persisted JSON is revalidated with exact top/record fields and a recomputed fingerprint before explicit DTO projection.

Consumer flow is aiterm-runtime-errors snapshot, then aiterm-runtime-errors ack --cursor N after durable ingestion. Operators can use resolve|reopen --fingerprint SHA256. MCP collection and diagnostic reads run in timeout-bounded child processes, so a FIFO or stalled filesystem cannot block terminal work; child failure emits only the fixed store diagnostic. Store mutation uses a bounded bakery ticket queue: every waiter owns a never-reused ticket containing PID, process-start identity, and an owner token, so dead owners are removed by unique filename without fixed-path reclaim ABA. The queue deadline measures lack of progress by the same head owner, not total wait behind healthy predecessors; normal polling uses the native process-liveness check and validates process-start identity only when a blocker stalls. Worker deadlines use forced termination so a SIGTERM-ignoring child cannot mutate state after timeout. POSIX state is atomically replaced under $XDG_STATE_HOME/aiterm-mcp/ (default ~/.local/state/aiterm-mcp/) with owner/mode rechecked on every read. Windows native uses %LOCALAPPDATA%\aiterm-mcp\; each DACL is rebuilt and read back as one non-inherited FullControl ACE for the current SID. Windows path/DACL/timeout behavior is covered by pure tests in this change; no new Windows integration success is claimed.

Interactive agent harnesses

agent_launch starts a selected harness's interactive coding-agent TUI inside a fresh persistent PTY and returns its session_id. The harness owns the agent loop, authentication, hooks, session, and transcript; model is independent. The TUI is a full-screen app, so read it with pty_read({ screen: true }) for the rendered view.

agent_configure({ session_id, model?, reasoning_effort? }) changes a running Claude, Codex, Grok, Composer, or Cursor TUI through the harness's standard controls, preserving the PTY and conversation context.

harness

Launches

Model behavior

claude-code

Claude Code CLI

Claude catalog model; native effort controls

codex-cli

Codex CLI

OpenAI catalog model; native effort controls

grok-cli

Grok Build CLI

Grok/Composer catalog model; Composer is model: "grok-composer-2.5-fast"

cursor-cli

Cursor Agent CLI

Cursor catalog model, including GPT/Claude/Grok; effort uses model parameter override

The selected harness CLI must be installed and authenticated. Use each product owner's official installer and updater; Aiterm does not distribute alternate CLI tarballs. For Cursor Agent CLI, use curl https://cursor.com/install -fsS | bash on macOS/Linux/WSL or irm 'https://cursor.com/install?win32=true' | iex on native Windows, authenticate once with agent login, and update with agent update; Aiterm invokes the unambiguous cursor-agent binary. Missing binaries, invalid model/effort values, unavailable Grok catalog models, and nonexistent cwd fail before a session exists.

Set throughline_source_session together with a non-empty mission in prompt to prepend Throughline's read-only handoff context. This optional route requires throughline >= 0.9.0, cannot be combined with launch_operation_id, and leaves the source session's database ownership unchanged. Optional throughline_supplement_file is passed unchanged to Throughline and requires throughline_source_session and Throughline 0.10.8 or later; Aiterm does not read or classify the supplement. Throughline is resolved through THROUGHLINE_BIN and then PATH; a missing or invalid export fails before the PTY exists instead of silently launching clean.

When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lines), callers recover it in full with pty_read({ agent_transcript: true }). It returns the most recently completed turn's final assistant message in plain text with no re-prompting. The existing human-readable content keeps its diagnostic suffix; machine callers read the answer alone from structuredContent.text in aiterm.pty-read-result.v1. Claude reads the bounded owner-only result captured by the launch-correlated Stop hook and verifies its digest/byte count; it never reads Claude's private transcript. Durable machine callers should use claude_turn: issue sends once, recover never sends, pending is distinct from unsafe or malformed state, and only completed carries the exact verified raw_output. Codex uses the normal rollout transcript's task_complete.turn_id; Grok/Composer return the last non-empty assistant message after the last real user row, excluding tool-use preambles; Cursor uses the normal agent transcript bound to the launch ID and current turn. Missing or ambiguous attribution remains an explicit error.

Completion detection (5 layers)

For PowerShell over SSH, mark:true recognizes the current standard PS ...> prompt and emits PowerShell syntax even when Aiterm runs on macOS or Linux. A prompt left in earlier output is not used to select the syntax.

pty_read({ wait: true }) decides "is the command done?" via five layers: process exit / a mark:true sentinel / an until match / output quiescence with shell return / timeout. mark emits the shell's exit status on POSIX shells and 0 (success) or 1 (failure) on PowerShell; fish/csh/tcsh are rejected before send because they do not share either status syntax. When mark or until is active, that requested evidence takes precedence and a momentarily quiet shell cannot complete the read as quiescent. Agent sessions add a sixth exact layer: Codex observes normal rollout task_complete; Grok/Composer observe normal session turn_ended; Claude observes its additive launch-correlated Stop event; Cursor observes turn_ended(status:"success") in the launch-bound normal agent transcript. aiterm-wait --cursor performs that harness-specific observation without the parent blocking or polling. Pre-send readiness failures are MCP errors, and late completion remains recoverable without resending.

Completion push for parent agents (aiterm-wait)

Codex／Claude Code親には子の回答本文が自動で届く。 子を起動・dispatchした後は、別作業へ進むか親のturnを終える。Aitermが完了を観測し、加工前の本文を保存して親へ渡す。waiter、pty_readによる回答回収、子への返送指示は不要。子は全対応harnessから選べる。

自動配送のreceiptにはparent_deliveryが付き、wait_process／wait_commandはnullになる。pty_observeのparent_deliveriesでwaiting、ready、sending、submitted、failed、unknownを確認できる。submittedはCodexのキュー受付またはClaudeのhookへの本文出力を示し、modelの読了ではない。MCP再接続後は未送信の記録を再開し、出力中断で結果が分からない場合は本文を保持してunknownとする。自動再送はしない。

Use a Codex runtime that supplies MCP _meta.threadId and the official thread/queue API (verified with Codex CLI 0.154.0). aiterm-setup checks the installed queue entry point; Aiterm verifies the requesting thread before each dispatch. Codex native sub-agents reject external queue input and cannot be automatic-delivery parents. Ordinary CLI and Desktop parents use the same supported route.

Claude Codeは2.1.259以上の対話sessionに対応する。aiterm-setupが専用のPreToolUse、PostToolUse、SessionEndを登録するため、Channelsの起動flagは不要。公式asyncRewake hookだけが裏で待ち、親はその間も次のturnへ進める。回答はStop hook feedbackとして届く。hookのexit 2は親の再開信号であり、子の成功・失敗は本文のoutcomeで区別する。

/clear等の会話終了後は未送信の旧回答を送らず、本文を保存する。受信hookの上限は24時間。hookの終了・出力失敗・無効化を成功扱いせず、別の待機経路へ黙って切り替えない。Claude Desktopのチャット、Web、agent_id付きの会話（--agent起動とnative subagent）はこの受信契約に含めない。

hookを持たない旧版へ戻す時は、install前にaiterm-setup --remove-claude-parent-hooksを実行する。Aiterm専用hookだけを解除し、他製品のhookと設定は保持する。

Claudeをリンク経由のcwdから起動した場合も、実体パスに対応する会話記録を参照する。

For other parent hosts, dispatch and start the receipt's waiter in a separate process:

  1. Launch the child with agent_launch({ harness: ... }); every launch shares the normal project/user environment and adds only completion correlation plus lineage. Send a turn with plain pty_send (or claude_turn issue for durable Claude operations). The call returns immediately with an event_cursor in its structured receipt.

  2. Pass the receipt's wait_process.executable and wait_process.args unchanged to a true argv process API. PowerShell 7's Start-Process is the exception because it joins -ArgumentList arrays; pass windows_start_process_argument_list as its one ready-made argument string instead. This invokes the bundled waiter through the exact Node runtime that is already running aiterm, including on native Windows where npm's human-facing bin is a PowerShell script shim and install paths may contain spaces. wait_command remains a compatibility display string for humans. The waiter observes the harness-owned completion source, plus Claude's additive launch hook, as a pure reader and exits with a one-line aiterm.agent-wait-result.v1 receipt. Exit ≠ done: the receipt's outcome is authoritative (0 = done, 3 = timeout, 4 = closed, 1 = error).

  3. 親自身のforegroundでwaiterを実行しない。 receiptのprocess起動情報を、そのhostが持つバックグラウンドprocess APIへ渡す。親は別作業へ進むかturnを終え、process終了の通知で続行する。

  4. Collect the result exactly as before: pty_read(agent_transcript: true), or claude_turn recover for durable Claude operations. The waiter carries the signal, never the payload.

If your host has no completion push (no mechanism that re-invokes the agent when a background process exits), --timeout 0 is a one-shot check instead of a wait: it scans the event file once and returns running (exit 5) when the turn is still in flight, done (exit 0) when it finished, closed (exit 4) when the session is gone. It is deliberately absent from the receipts and tool descriptions — a host that does get pushed should be woken, not poll. An unknown session name is an error, never running, so a typo cannot masquerade as a child that is still working.

aiterm-wait takes no locks, never writes session state, and never dispatches — any number can run beside the MCP server and each other, and pty_close/concurrent sends are unaffected.

Token reduction

  • pty_read by default strips control characters, collapses repeated lines, and folds long output into head+tail (with a restore hint and a meta line).

  • pty_read({ rtk: true }) further shrinks the observed output with a per-command reducer (git status/git log/grep/pytest and more) — a self-contained reimplementation that needs no rtk binary.

  • pty_send({ rtk: true }) rewrites a known command into rtk form before sending, so reduction happens at the source if rtk exists there (passthrough otherwise).

Input and output

pty_send does not interpret command or prompt meaning; it delivers the requested text to the terminal. By default it sanitizes ESC and bracketed-paste terminators, while pty_read neutralizes control characters in returned output (raw: true keeps them unchanged). The shell, remote endpoint, or launched harness owns command authorization.

Each pty_send accepts at most 64 KiB of UTF-8 text. Sends to the same session are serialized across aiterm processes so chunks cannot interleave. Every OS pastes through its multiplexer in UTF-8-safe 256-byte chunks with a 10 ms drain interval; macOS, Linux, and WSL2 have all demonstrated silent middle/trailing loss when a long input is pushed without that boundary. Sanitized multiline text sent while a POSIX shell is in the foreground is encoded as one newline-free eval input: the shell receives the complete script before it runs the first line, so a pager or REPL started mid-script cannot consume later lines as interactive keystrokes. Single-line input, raw:true, and non-shell frontends remain direct PTY pastes. Agent dispatches additionally use the tmux-compatible bracketed-paste operation (paste-buffer -p): panes that requested bracketed-paste mode receive each chunk wrapped in ESC[200~/201~, hardening prompt injection against mid-word key-interpretation corruption and dropped submits. If a later chunk fails, aiterm reports the partial-send state and does not press Enter automatically. A lock left by a terminated sender fails closed before sending; use pty_list to confirm the affected session, close it with pty_close, then recreate the same session ID. There is no public kill-all tool.

A human can watch

Sessions live on a shared tmux socket on POSIX or a shared psmux namespace on native Windows. The attach line printed by pty_open and agent_launch lets a human attach to the same terminal and intervene, including a Claude/Codex/Grok/Cursor harness session: tmux -S … attach -t <id> on POSIX, or psmux -L <namespace> attach -t <id> on native Windows.

Requirements

  • Node.js >= 18

  • tmux or psmux (platform runtime prerequisite)

    • macOS / Linux / WSL2 run tmux directly. On macOS install it with brew install tmux (stock macOS ships none). If your MCP client is launched from the GUI rather than a terminal, Homebrew's bin (/opt/homebrew/bin on Apple Silicon, /usr/local/bin on Intel) may be off its PATH; aiterm auto-searches those locations, or set AITERM_TMUX=/path/to/tmux to point at it explicitly.

    • Native Windows has no tmux, so aiterm drives psmux — a tmux-CLI-compatible native terminal/session multiplexer — with a per-install -L namespace. psmux is not a shell. pty_open defaults to PowerShell 7 (pwsh.exe) and never falls back to Windows PowerShell 5.1, PowerShell 6, or cmd.exe; if only 5.1 is installed, use Microsoft's official installer or package manager first. Install psmux 3.3.8 or newer (winget install marlocarlo.psmux; 3.3.8 is the first release whose pipe-pane file sink, byte-exact paste-buffer wire, and foreground #{pane_current_command} behave the way aiterm's capture/dispatch paths rely on). Git for Windows remains required for the explicit Bash shell used internally by harness launchers; System32's bash.exe is the WSL launcher and is deliberately not used. Override multiplexer/Bash resolution with AITERM_PSMUX / AITERM_BASH. Other products consume persistent terminals through Aiterm's public API instead of depending on psmux directly.

  • For agent harnesses: the selected CLI, installed and authenticated through its product owner's official path — claude, codex, grok, or Cursor's cursor-agent. Portable fork additionally needs throughline >= 0.9.0; ordinary clean launch does not. (Not needed if you only use the PTY tools.)

  • Optional: the rtk binary (used by pty_send's rtk: true delegation; works fine without it)

Known constraints (by design, not bugs)

  • While nested (ssh / docker / REPL / a launched agent TUI), quiescence cannot fire by design, because the foreground command is no longer in the shell set (bash/sh/zsh/fish/dash). When nested with no until and no mark, pty_read({ wait: true }) returns early as is_complete=False via nested (rather than burning the full timeout, since no signal can confirm completion there) with a note to pass until (a literal substring by default; until_regex: true for a regex) or mark: true (an exit-code sentinel, auto-detected) for a confirmed completion. For a full-screen agent TUI, read { screen: true } once its output settles.

  • is_complete=False is not a failure. It means "completion was not observed within timeout." For long commands, raise timeout or use until/mark.

  • Agent harnesses run their real TUI; aiterm doesn't proxy the model API. The selected harness owns model choice, authentication, and behavior. There is no hidden inter-agent protocol; the MCP client drives the Claude/Codex/Grok/Cursor TUI with ordinary send/read operations.

  • pty_send({ rtk: true }) is single-line only and needs the external rtk binary (passthrough without it). The pty_read({ rtk: true }) reducer, by contrast, is self-contained and rtk-independent.

  • The pytest reducer matches rtk 0.42.0 on test counts, the rule line, and FAILURES-block formatting (locked by regression tests). It deliberately preserves the full failure reason on the FAILED summary lines (emitted under -ra/-rf), whereas rtk 0.42.0 truncates the reason at the first " - " — a readability choice, so those lines are intentionally not byte-identical to rtk. The [full output: …] tee-pointer line rtk appends on large output is not reproduced on the read side.

  • tmux is started with -f /dev/null, so it does not read ~/.tmux.conf (to keep behavior reproducible across machines).

  • All sessions share one multiplexer endpoint (claude.sock on POSIX, one psmux namespace on native Windows). The platform's kill-server command removes them all.

Development

npm install
npm run build      # tsc → dist/
npm test           # build, then the node:test regression suite (requires tmux or psmux)
npm link           # put `aiterm-mcp` on PATH locally

開発中は変更に直結する試験を先に実行する。GitHub Actionsは共通実装・CI自身・未分類の変更をMac・Linux・Windowsで検証し、 Windows固有だけの変更はLinuxとWindowsを選ぶ。版番号だけの変更はLinuxの配布情報・pack確認、文書だけなら文書検査を行う。 試験内容とOSの選択、週次・手動実行の範囲は公開手順に従う。 npm run release -- <version> syncs the version, commits, tags, and publishes the GitHub Release in one command; tag-triggered npm publishing checks only that the tagged commit is on origin/main and does not wait for another CI run. The native Windows runner needs psmux ≥ 3.3.8 and Git for Windows on its PATH, and must run as an interactive Windows user; NETWORK SERVICE lacks the per-user environment the pane shell and harness CLIs rely on and is not a valid runner identity.

Logic lives in src/core.ts (tmux control, reduction, completion detection, safety, agent launch) and src/rtk.ts (per-command reducers); src/index.ts is the MCP surface. The current architecture is in docs/DESIGN.md, the release procedure is in docs/RELEASE.md, and prototype/python/ remains the reducer's historical porting source (the pytest reducer is ported to match upstream rtk 0.42.0, except the deliberate FAILED-line difference noted above, and is locked by regression tests).

Try it

公開packageを導入して、検出したAIへ登録する。cloneやビルドは不要:

npm install -g aiterm-mcp@latest
aiterm-setup --json

If aiterm let your AI hand a task to another agent — or saved you a round-trip of tokens — star the repo. It's the cheapest way to help others find it.

Shared agent environment

All harnesses use the caller's normal project and user environment. Aiterm does not copy, symlink, filter, or replace harness configuration, authentication, MCP, plugin, skill, permission, trust, memory, or history stores. Cleanup removes only aiterm-owned launch metadata and completion correlation files.

The ordinary environment still comes from the persistent shell session. When a caller needs a value that belongs to the current MCP process rather than the older persistent multiplexer server, every harness accepts env_vars: ["NAME", ...]. Only those names are refreshed at launch; this is a narrow per-launch overlay, not a replacement environment or configuration snapshot.

License

MIT

Available Tools

18 tools
agent_approvalA

Codexの現在の承認をinspectし、digestへ束縛した単発許可または拒否をrespondする。恒久許可は選ばない。Claudeは既存claude_approvalを使う。未知dialogはblockedのtyped errorで返す。

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYes
session_idYes
approval_choiceNo
observed_prompt_digestNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
atYes
kindYes
actionYes
promptYes
reasonYes
schemaYes
statusYes
choicesYes
harnessYes
launch_idYes
session_idYes
prompt_digestYes
selected_choiceYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description must carry behavioral weight. It discloses that unknown dialogs become a typed 'blocked' error and that approvals are one-time digest-bound. It does not mention side effects of the 'respond' action or any authentication/authorization requirements, but the disclosed error behavior is meaningful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, action-oriented. The alternative to claude_approval and the error path are both packed into a short block. Dense but front-loaded; minor loss for punctuation/style overall not needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema and moderate complexity. The description covers the purpose, the error case, and the sibling alternative, but leaves 'session_id' semantics and when to use 'inspect' versus 'respond' undeclared. An agent still has to infer several usage details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter meaning. It states the digest-bound one-time approval/deny, which maps to 'observed_prompt_digest' and the enum choices, but it never explains 'session_id' or both possible action values. The agent is left to infer these from names and enums.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly names the resource (Codex approvals), the verbs (inspect/respond), and the outcome (digest-bound one-time approval or denial). It also distinguishes this tool from 'claude_approval' in the sibling list, so an agent can immediately tell it is the Codex-specific approval tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a direct alternative ('Claude uses existing claude_approval') and an explicit exclusion ('versus permanent approval is not chosen'). It does not explicitly state the general when-to-use condition, but the alternative and limitation provide clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agent_configureA

起動済みのClaude／Codex／Grok／Composer／Cursor agent sessionを再起動せず、会話contextを保ったままmodel／reasoning effortを変更する。各harnessのCLI標準model操作を使う。Cursorのreasoning_effort変更はmodelと同時指定する。

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo変更後のmodel。省略時はmodelを変更しない
session_idYes
reasoning_effortNo変更後のreasoning effort。省略時はeffortを変更しない

Output Schema

ParametersJSON Schema
NameRequiredDescription
modelYes
schemaYes
harnessYes
providerYes
session_idYes
reasoning_effortYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It explains that the operation is non-restarting, preserves conversation context, and mutates model/reasoning settings, with a useful Cursor-specific constraint. It does not mention failure modes or side effects, but the core behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: it states the core behavior first, then the method, then the special Cursor caveat. Every sentence adds information and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three parameters and available output schema, the description is sufficiently complete. It explains the operation context, the non-restart behavior, and the key harness-specific coupling. It could add a bit more guidance on failure conditions or where to get valid model identifiers, but the essential calling context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents model and reasoning_effort with 'omit means no change' semantics, and 67% of parameters have descriptions. The description adds the cross-parameter Cursor caveat that reasoning_effort must be changed together with model, but it does not provide value formats or allowed model identifiers beyond what the schema implies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action (change model/reasoning effort), the resource (already-started agent sessions for multiple harnesses), and the key constraint (no restart, context preserved). This distinguishes it from agent_launch and other session-oriented siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context: target existing sessions, avoid restarting, and use each harness's standard CLI model operation. It does not explicitly name alternatives or state when not to use the tool, but '起動済み' and '再起動せず' effectively separate it from launch/restart flows.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agent_launchA

エージェントを単一の標準入口から永続sessionへ起動する。harnessはagent loop・認証・hook・transcriptを所有する実行基盤、modelはそのharnessが選ぶ推論モデルであり別軸。Cursor harnessからGPT／Claude／Grok等を選んでも完了相関はCursor方式のまま。Grok Composerは別harnessではなく harness=grok-cli と model=grok-composer-2.5-fast で指定する。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。dispatch した子は投げっぱなしでよい＝親はここで待たない。Codex親とClaude Code親にはAitermが回答本文を自動配送する。parent_deliveryがある場合はwait起動も通常の回答回収も不要。親は作業を続けるかターンを終える。その他の親では、完了通知をreceiptの wait_process.executable と wait_process.args をそのまま親のターンを塞がない別プロセスAPIへ渡して受け、PowerShell 7のStart-Processだけは windows_start_process_argument_list を単一文字列として渡す。exit を完了通知として扱う（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了。ポーリング不要）。wait_command は人間向け互換表示でありprocess境界へ使わない。foreground実行で親のターンを塞がない。自動配送以外の結果回収は pty_read(agent_transcript:true)。

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo作業ディレクトリ（絶対パス・任意）
imageNo初手プロンプトへ添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）
modelNoharnessが選ぶモデル。provider名ではなくlive catalog上のmodel ID
promptNo起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る
harnessYesagent loop・session・hook・transcript・認証を所有する実行基盤
env_varsNo現在のMCP processから継承する環境変数名
write_scopeNo能力宣言。read-onlyは対応harnessの標準read-only面で実効禁止する
session_nameNoAiterm session名（省略で自動採番）
trust_projectNo対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める
reasoning_effortNoharness adapterが標準CLI表現へ変換する思考レベル。Cursorではmodel同時指定が必要
launch_operation_idNoClaude Codeのpromptなしexact replay相関だけで使用
throughline_source_sessionNo同一端末のThroughline sessionから読み取り専用contextを初手へ注入する
throughline_supplement_fileNoThroughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path

Output Schema

ParametersJSON Schema
NameRequiredDescription
schemaYes
harnessYes
startupYes
providerYes旧互換field。新規連携はharnessを使う
session_idYes
write_scopeNo
event_cursorYes
wait_commandYes
wait_processYes
initial_promptYes
submit_residueYes
parent_deliveryNo
managed_completionYes
write_scope_enforcementNo

TDQS

A3.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden — and it delivers comprehensively. It discloses fire-and-forget semantics, foreground execution not blocking the parent's turn, complete exit code meanings (0/3/4/7), default 600-second timeout, no-polling guarantee, per-parent-type delivery mechanisms, environment sharing (HOME/cwd/MCP/plugins/skills), and injection of sub-agent self-awareness with delegation_allowed=true. This is exemplary behavioral disclosure for a complex launch tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information-dense and front-loaded with the core purpose, but presented as an unstructured wall of Japanese text with no visual hierarchy (no bullets, sections, or breaks). Every sentence carries useful content, yet the density — particularly the exit code and delivery mechanism details — makes it harder for an agent to parse at a glance. The length is justified by the tool's complexity, but the structure is not.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 13 parameters, 1 required, complex delivery semantics, multiple exit codes, and an output schema, this description is nearly exhaustive. It covers launch semantics, delivery per parent type, exit code meanings, timeout behavior, result collection via pty_read, environment inheritance, and trust/permission handling. An output schema exists so return values need no explanation. Nothing an agent needs to correctly invoke and monitor this tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (all 13 parameters documented in the schema), so baseline is 3. The description adds conceptual enrichment for the harness and model parameters — explaining their orthogonal relationship, that reasoning_effort is transformed by the adapter, and that Grok Composer maps to specific harness/model values. This exceeds the bare baseline but doesn't systematically walk through each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

First sentence clearly states the purpose: launch an agent from a single standard entry point into a persistent session (verb+resource+destination). The harness vs model axis distinction is explicitly explained, which differentiates this from sibling tools like claude_agent, codex_agent, grok_agent, and composer_agent. However, it stops short of naming those siblings directly, so differentiation is conceptual rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides substantial usage context: fire-and-forget dispatch, parent_delivery scenarios, auto-delivery for Codex/Claude Code parents, and explicit 'wait_command is for human display, not process boundaries.' It also explains that Grok Composer is configured via harness=grok-cli rather than as a separate harness. However, it never explicitly states when to choose this tool over its siblings (e.g., claude_agent, composer_agent), leaving the routing decision partially implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agent_steerA

実行中のCodex/Grok agentへ追加メッセージを差し込み、現在のターンを誘導する。独立した次ターンを始める用途ではなく、idle時は文字を送らずdelivery=idleを返す。

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes現在のターンへ追加する文字列。UTF-8で最大64KiB
imageNo添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
schemaYes
vendorYes
harnessYes
deliveryYes
launch_idYes
session_idYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose an important edge-case behavior (idle delivery returns delivery=idle without sending text), which adds value beyond the schema. However, it does not describe the return behavior for the normal case, potential side effects, or permission requirements, leaving gaps for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler: the first states the core purpose and the second addresses a critical exception. The information is front-loaded and every clause adds value, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is moderately complex with three parameters and no output schema or annotations. The description explains the idle case but leaves out the normal-case return value, error behavior, and any permissions or prerequisites. Given the lack of output schema, more detail on expected responses would make it more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides descriptive text for the text and image parameters, including UTF-8 and max size for text and file types for images. The description adds minimal extra semantic nuance beyond labeling the action as 'adding a message to the current turn,' which is already implied by the schema. Thus it stays near the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('差し込み' / inject) and resource ('実行中のCodex/Grok agent'), and it specifically clarifies that it steers the current turn rather than starting a new one. This distinguishes it from potential sibling tools even without naming any.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: it is for adding to an ongoing turn, not for initiating an independent next turn. It also instructs that when the agent is idle no text should be sent and delivery=idle is returned, which guides when to call vs. avoid. It does not name alternative tools, but none are provided, so this is reasonably complete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

claude_agentB

【旧互換alias。新規連携は agent_launch(harness=claude-code)】Claude Codeの対話エージェントTUIを永続端末に起動する。claude -pではなく、同じ利用者可視sessionへpty_sendで継続入力する。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。通常settingsへlaunch固有Stop hook settingsを加算する。起動前に共有認証を構造化確認し、未認証ならsessionを作らない。dispatch した子は投げっぱなしでよい＝親はここで待たない。Codex親とClaude Code親にはAitermが回答本文を自動配送する。parent_deliveryがある場合はwait起動も通常の回答回収も不要。親は作業を続けるかターンを終える。その他の親では、完了通知をreceiptの wait_process.executable と wait_process.args をそのまま親のターンを塞がない別プロセスAPIへ渡して受け、PowerShell 7のStart-Processだけは windows_start_process_argument_list を単一文字列として渡す。exit を完了通知として扱う（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了。ポーリング不要）。wait_command は人間向け互換表示でありprocess境界へ使わない。foreground実行で親のターンを塞がない。自動配送以外の結果回収は pty_read(agent_transcript:true)。Claude の durable turn は claude_turn でも回収できる。

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo作業ディレクトリ（対象リポのルート等・任意）
modelNo起動モデル（例: claude-sonnet-4-6）。省略時はClaude CLI既定
promptNo起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る
env_varsNo起動したagentへ現在のMCP processから継承する環境変数名。値はtool引数へ渡さない
session_nameNoセッション名（省略で自動採番）
trust_projectNo対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める
reasoning_effortNoClaude Code reasoning effort。low/medium/high/xhigh/max。省略時はCLI既定
launch_operation_idNopromptなしClaude launchのexact replay相関ID。session_name必須
throughline_source_sessionNo同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する
throughline_supplement_fileNoThroughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path

Output Schema

ParametersJSON Schema
NameRequiredDescription
schemaYes
harnessYes
startupYes
providerYes
session_idYes
event_cursorYes
wait_commandYes
wait_processYes
initial_promptYes
submit_residueYes
parent_deliveryNo
managed_completionYes後方互換field。trueはaiterm完了相関が有効という意味で、project/user環境の隔離を意味しない

TDQS

B3.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden, and it discloses several behavioral traits: the launch is fire-and-forget (doesn't wait), exit codes meanings, the 'wait_command' is for humans only, and result retrieval via pty_read. It also mentions environment sharing and trust handling. This is thorough, but could be slightly improved by summarizing key side effects upfront.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and long, with many clauses that add complexity (e.g., 'PowerShell 7のStart-Processだけは...'). The core purpose is buried under implementation details, making it hard to parse. It tries to front-load the alias note but then dives into specifics. A more concise summary of behavior would improve usability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 params, launch operation, delegation), the description covers many necessary details: launch semantics, result retrieval, exit codes, and parent delivery. The output schema exists, but for a complex tool, the description is relatively complete. However, missing explicit notes on required auth steps or error handling for unsupported parents.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter. The description adds context for some parameters (e.g., prompt says 'send and return immediately', env_vars inherited from MCP process), but it doesn't significantly add meaning beyond the schema. Baseline 3 is appropriate as description reinforces but doesn't expand much.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool launches a Claude Code interactive agent TUI in a persistent terminal, and it mentions the deprecated alias and the preferred alternative (agent_launch). However, it is overloaded with extensive implementation details, making the core purpose less immediately graspable. While it distinguishes from `claude -p`, it could be clearer about what the tool essentially does at a high level.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly guides on when to use this tool (for interactive agent sessions vs. non-interactive) and provides context about parent-agent delegation and when not to wait. It also references alternative tools like claude_turn for result retrieval. The guidance is rich but could be more explicit about 'when not to use this tool' (e.g., when a non-interactive one-shot is needed).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

claude_approvalA

aiterm相関付きClaudeのactive turn中に表示された権限確認UIを、turn相関を保ったまま検査・応答する専用面。inspectで画面digestと安全な単発Yes/Noだけを取得し、respondは同じoperation・同じdigestが現在も表示中の場合だけ送信する。

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYes
session_idYes
operation_idNodurable operationのID。通常pty_send由来の匿名turnでは省略する
approval_choiceNorespondだけに指定する
observed_prompt_digestNo直前のinspectが返したdigest。respondだけに指定する

Output Schema

ParametersJSON Schema
NameRequiredDescription
atYes
actionYes
schemaYes
statusYes
choicesYes
session_idYes
operation_idYes
prompt_digestYes
selected_choiceYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that inspect returns only the screen digest and safe single Yes/No, and that respond is conditional on matching operation and current digest. This provides meaningful behavioral context, though it does not cover all error cases or side effects of responding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence that efficiently conveys the main purpose, actions, and safety condition without wasted words. It is compact and front-loaded, though the multiple clauses make it slightly complex to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. The description covers the two actions, what inspect returns, and the precondition for respond, which is sufficient for a specialized approval tool. It lacks details on mismatch handling or how to obtain session_id, but these are partially addressed by the schema hints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 60%, and the schema already documents the optional parameters (operation_id, approval_choice, observed_prompt_digest) with useful descriptions. The tool description adds context for the action enum (inspect vs respond) but does not elaborate on individual parameters beyond what the schema provides. It adds some value but not extensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function as a dedicated surface for inspecting and responding to permission confirmation UI during an active Claude turn, preserving turn correlation. It distinguishes itself from sibling PTY tools by focusing on the approval context and the specific inspect/respond actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies the intended scenario (permission UI during active Claude turn) and the safe usage pattern: inspect only retrieves a digest and simple Yes/No, while respond is only sent when the same operation and digest are still displayed. It implies this is the correct tool for approvals but does not explicitly name alternatives like pty_send or state exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

claude_turnB

aiterm相関付きClaude sessionのdurable operationを構造化issue／recoverするmachine-caller専用面。pending／unknown／completedを人間向けerror文字列の解析なしで返し、Observer固有ロジックは持たない。

ParametersJSON Schema
NameRequiredDescriptionDefault
textNoissueだけに指定するbounded turn本文
actionYes
session_idYes
operation_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
actionYes
reasonYes
schemaYes
statusYes
raw_outputYes
session_idYes
operation_idYes
submit_residueYes
parent_deliveryNo

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral disclosure burden. It does disclose that it returns structured pending/unknown/completed statuses and does not parse human-facing error strings, but it omits side-effect details: issuing or recovering durable operations is likely mutative, and there is no mention of idempotency, blocking behavior, or what 'durable' means concretely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence with no filler and front-loads the tool's purpose and caller type. It earns its space by differentiating from Observer logic and specifying the status output, though the heavy slash-notation and untranslated Japanese jargon reduce readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two actions, three required parameters, one conditional optional parameter, and no annotations, the description leaves action-selection rules, parameter relationships, and side effects largely implicit. An output schema exists, so return values need less explanation, but the agent still lacks enough guidance to safely choose recover vs issue or know when to provide text.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25%, and the description adds almost no parameter-level meaning. It never explains action='issue' vs action='recover', what session_id or operation_id represent beyond their names, or the conditional role of text, even though text is relevant only to issue. The schema enum and sha256 pattern help, but the prose does not compensate for the low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: it issues/recover durable operations for Claude sessions and returns pending/unknown/completed statuses structurally, without parsing human-facing error strings. It also explicitly says it has no Observer-specific logic, which helps separate it from pty_observe and diagnostics siblings, though terms like 'aiterm相関付き' and 'durable operation' are left unexplained.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'machine-caller専用面' and 'Observer固有ロジックは持たない' imply it is for automated callers that need structured status rather than for observers or humans reading error messages. However, it does not explicitly name alternatives or state when not to use it, so usage guidance is mostly left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codex_agentA

【旧互換alias。新規連携は agent_launch(harness=codex-cli)】Codexの対話エージェント TUI を永続端末に起動する。実装・レビュー・調査を対話で回す。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。委譲契約を使う完全な呼び出し例: codex_agent({"prompt":"<依頼>","model":"gpt-5.6-sol","reasoning_effort":"high","cwd":"/absolute/path/to/repo","write_scope":"read-only"})。turn は pty_send で送る（自動で非ブロック dispatch になる）。dispatch した子は投げっぱなしでよい＝親はここで待たない。Codex親とClaude Code親にはAitermが回答本文を自動配送する。parent_deliveryがある場合はwait起動も通常の回答回収も不要。親は作業を続けるかターンを終える。その他の親では、完了通知をreceiptの wait_process.executable と wait_process.args をそのまま親のターンを塞がない別プロセスAPIへ渡して受け、PowerShell 7のStart-Processだけは windows_start_process_argument_list を単一文字列として渡す。exit を完了通知として扱う（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了。ポーリング不要）。wait_command は人間向け互換表示でありprocess境界へ使わない。foreground実行で親のターンを塞がない。自動配送以外の結果回収は pty_read(agent_transcript:true)。model / reasoning_effort を引数で指定可（省略時は端末 config／CLI 既定を継承。実効値は起動応答に明示）。

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo作業ディレクトリ（対象リポのルート等・任意）
modelNo起動モデル（例: gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna）。省略時は端末 config／CLI 既定を継承（端末側のピンがそのまま効く。実効値は起動応答に明示される）
promptNo起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る
env_varsNo起動したagentへ現在のMCP processから継承する環境変数名。値はtool引数へ渡さない
write_scopeNo能力宣言。read-only、または書込みを許可するパスの説明文字列。対応harnessのread-onlyはCLI標準のread-only面で実効禁止する
session_nameNoセッション名（省略で自動採番）
trust_projectNo対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める
reasoning_effortNoreasoning effort（思考レベル）。low/medium/high/xhigh/max/ultra（CLI／model 版依存）。ultra は max 推論＋proactive 自動委譲 ON＝使用量急増注意（明示要求時のみ）。省略時は端末 config／CLI 既定。
throughline_source_sessionNo同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する
throughline_supplement_fileNoThroughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path

Output Schema

ParametersJSON Schema
NameRequiredDescription
schemaYes
harnessYes
startupYes
providerYes
session_idYes
write_scopeNo
event_cursorYes
wait_commandYes
wait_processYes
initial_promptYes
submit_residueYes
parent_deliveryNo
managed_completionYes後方互換field。trueはaiterm完了相関が有効という意味で、project/user環境の隔離を意味しない
write_scope_enforcementNo

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so richly: non-blocking dispatch, automatic answer delivery for certain parents, exit code semantics (0/3/4/7), 600-second timeout, no polling, sub-agent delegation injection, and config sharing. There is no contradiction with annotations since none were provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and deprecation, and its length is largely justified by the tool's asynchronous complexity. It is dense and somewhat repetitive — non-blocking behavior is stated multiple times and model/reasoning_effort detail duplicates the schema — so it falls short of a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything an agent needs to invoke and observe this tool correctly: how to send turns, whether to wait, how completion notifications arrive via receipt fields, exit codes, timeout behavior, transcript retrieval, and what counts as incomplete. Since an output schema exists, the description need not explain return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each parameter already has a detailed description, so the baseline is 3. The description adds a realistic full invocation example and clarifies model/reasoning_effort default inheritance, but does not substantially extend parameter-level meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States clearly that this launches the Codex interactive agent TUI in a persistent terminal, and immediately flags itself as a legacy alias with an explicit replacement (`agent_launch(harness=codex-cli)`). This differentiates it from sibling tools without requiring schema inspection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says new integrations should use agent_launch, names pty_send and pty_read as the interaction and result-collection channels, and instructs the caller not to wait or poll. It also warns that wait_command is not for process boundaries, giving clear guidance on when and how to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

composer_agentA

【旧互換alias。新規連携は agent_launch(harness=grok-cli, model=grok-composer-2.5-fast)】Grok BuildのComposerモデルを永続端末に起動する。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。turn は pty_send で送る（自動で非ブロック dispatch になる）。dispatch した子は投げっぱなしでよい＝親はここで待たない。Codex親とClaude Code親にはAitermが回答本文を自動配送する。parent_deliveryがある場合はwait起動も通常の回答回収も不要。親は作業を続けるかターンを終える。その他の親では、完了通知をreceiptの wait_process.executable と wait_process.args をそのまま親のターンを塞がない別プロセスAPIへ渡して受け、PowerShell 7のStart-Processだけは windows_start_process_argument_list を単一文字列として渡す。exit を完了通知として扱う（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了。ポーリング不要）。wait_command は人間向け互換表示でありprocess境界へ使わない。foreground実行で親のターンを塞がない。自動配送以外の結果回収は pty_read(agent_transcript:true)。model／reasoning_effortを引数で指定可。live catalogにComposer modelがなければGrokへfallbackせず明示エラー。read-only sandboxとagent_configureに対応。

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo作業ディレクトリ（対象リポのルート等・任意）
modelNo起動モデル。省略時は grok-composer-2.5-fast。既定／explicit modelを起動前にlive catalogへ照合し、不在ならfallbackせずエラー
promptNo起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る
env_varsNo起動したagentへ現在のMCP processから継承する環境変数名。値はtool引数へ渡さない
write_scopeNo能力宣言。read-only、または書込みを許可するパスの説明文字列。対応harnessのread-onlyはCLI標準のread-only面で実効禁止する
session_nameNoセッション名（省略で自動採番）
trust_projectNo対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める
reasoning_effortNoGrok Build reasoning effort。利用可能値はCLI／modelのlive catalogに従う。省略時はCLI／model既定。
throughline_source_sessionNo同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する
throughline_supplement_fileNoThroughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path

Output Schema

ParametersJSON Schema
NameRequiredDescription
schemaYes
harnessYes
startupYes
providerYes
session_idYes
write_scopeNo
event_cursorYes
wait_commandYes
wait_processYes
initial_promptYes
submit_residueYes
parent_deliveryNo
managed_completionYes後方互換field。trueはaiterm完了相関が有効という意味で、project/user環境の隔離を意味しない
write_scope_enforcementNo

TDQS

A4.1/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Extremely rich behavioral disclosure: environment sharing (HOME/cwd/MCP/plugins), sub-agent self-awareness, delegation_allowed=true injection, async fire-and-forget semantics, parent-delivery behavior for Code/Claude Code parents, exit-code meanings (0/3/4/7), explicit no-wait guidance, and read-only sandbox support. All disclosed without annotations to lean on, so this fully carries the transparency burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense, unstructured wall of text. Every clause carries information, but the lack of paragraphing or bullet structure makes it hard to scan; the critical legacy-alias warning and exit-code table are jammed together. Effective but not concise or well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Remarkably complete: covers launch semantics, parameter effects, async behavior, delivery alternatives, exit code meanings, timeout handling, and sandbox support. For a high-complexity tool, an agent has nearly everything needed to call it safely and correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions are brief but mostly self-explanatory; the description adds real meaning beyond them: model fallback behavior (no fallback, explicit error), env_vars passing semantics (values not forwarded), write_scope capability meaning, and throughline_session injection ordering. Adds value without being fully redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (launch) and resource (Composer model on a persistent terminal), and explicitly marks itself as a legacy alias pointing to agent_launch for new integrations. The core purpose is clear, but it's buried under a dense block of operational details, so it takes effort to extract.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the successor tool (agent_launch) and tells new integrations to use it, plus route guidance for waiting (receipt/exit codes) vs non-waiting (fire-and-forget) and result retrieval (pty_read). Clear exclusions and conditions are given, though not organized as a crisp when-to-use/avoid section.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

diagnosticsA

Factory 向け read-only 診断。安全な状態語彙だけを機械可読 JSON で返す（PTY 内容・認証情報・path・環境値は返さない）。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses read-only nature and explicitly states what data is not returned (PTY content, credentials, paths, environment values). Given no annotations, this provides sufficient behavioral transparency for a zero-parameter diagnostic tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no wasted words. The key point ('read-only diagnostics returning safe vocabulary') is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema tool with no annotations, the description is complete. It clearly defines scope, safety guarantees, and exclusions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist (schema coverage 100%), so the description does not need to add parameter meaning. The baseline of 4 applies as it adds no confusion.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Factory 向け read-only 診断' (Factory-oriented read-only diagnostics) and specifies that it returns only safe vocabulary in machine-readable JSON, explicitly listing excluded data types. This distinguishes it from sibling tools like pty_open or pty_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for Factory contexts via '向け' but does not provide explicit when-to-use or when-not-to-use guidance, nor does it name alternative tools. Usage context is implied but not fully elaborated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_agentA

【旧互換alias。新規連携は agent_launch(harness=grok-cli)】Grok BuildのGrokモデル（既定 grok-4.6）の対話エージェント TUIを永続端末に起動する。通常CLIと同じHOME・cwd・project/user/local設定・MCP・plugin・skill・permission/trustを共有する。aitermは完了相関stateだけをlaunch単位で所有する。起動されたagentにはsub-agent自己認識、親session、delegation depth/lineage、delegation_allowed=trueを注入し、必要な追加委譲は許可する。turn は pty_send で送る（自動で非ブロック dispatch になる）。dispatch した子は投げっぱなしでよい＝親はここで待たない。Codex親とClaude Code親にはAitermが回答本文を自動配送する。parent_deliveryがある場合はwait起動も通常の回答回収も不要。親は作業を続けるかターンを終える。その他の親では、完了通知をreceiptの wait_process.executable と wait_process.args をそのまま親のターンを塞がない別プロセスAPIへ渡して受け、PowerShell 7のStart-Processだけは windows_start_process_argument_list を単一文字列として渡す。exit を完了通知として扱う（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了。ポーリング不要）。wait_command は人間向け互換表示でありprocess境界へ使わない。foreground実行で親のターンを塞がない。自動配送以外の結果回収は pty_read(agent_transcript:true)。model／reasoning_effortを引数で指定可。read-only sandboxとagent_configureに対応。

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo作業ディレクトリ（対象リポのルート等・任意）
modelNo起動モデル。省略時は grok-4.6。explicit modelを起動前にlive catalogへ照合し、不在ならfallbackせずエラー
promptNo起動時に渡す初手プロンプト（任意）。送信後は待たずに即返る
env_varsNo起動したagentへ現在のMCP processから継承する環境変数名。値はtool引数へ渡さない
write_scopeNo能力宣言。read-only、または書込みを許可するパスの説明文字列。対応harnessのread-onlyはCLI標準のread-only面で実効禁止する
session_nameNoセッション名（省略で自動採番）
trust_projectNo対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める
reasoning_effortNoGrok Build reasoning effort。利用可能値はCLI／modelのlive catalogに従う。省略時はCLI／model既定。
throughline_source_sessionNo同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する
throughline_supplement_fileNoThroughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path

Output Schema

ParametersJSON Schema
NameRequiredDescription
schemaYes
harnessYes
startupYes
providerYes
session_idYes
write_scopeNo
event_cursorYes
wait_commandYes
wait_processYes
initial_promptYes
submit_residueYes
parent_deliveryNo
managed_completionYes後方互換field。trueはaiterm完了相関が有効という意味で、project/user環境の隔離を意味しない
write_scope_enforcementNo

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses shared HOME/cwd/config/MCP/plugin/skill/permission context, non-blocking dispatch semantics, exit code meanings (0/3/4/7), no-polling completion semantics, wait_command caveats, and read-only sandbox/agent_configure support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long and dense, but every sentence carries distinct operational information and the purpose/alias is front-loaded. It could be improved with structured bullets, but there is no wasted wording for a tool this complex.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters, full schema coverage, and an output schema, the description is complete: it covers lifecycle, parent integration, exit semantics, result retrieval, and capability flags. Nothing obviously needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 10 parameters. The description adds only a few parameter-related facts, such as the default model, that model/reasoning_effort can be specified, and that prompt returns immediately, but it does not need to compensate for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action: launching Grok Build's Grok model (default grok-4.6) dialogue agent TUI in a persistent terminal. It also explicitly identifies itself as a legacy compatibility alias and points to agent_launch(harness=grok-cli), which distinguishes it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent that new integrations should use agent_launch(harness=grok-cli) instead, reserving grok_agent for legacy compatibility. It also gives operational routing: send turns via pty_send, collect results via pty_read(agent_transcript:true), and follow parent-specific delivery/wait_process behavior.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pty_closeA

セッションを閉じ、ログ／読取位置を破棄する。同じsession_idへの再試行は安全で、closed／already_closedのstructured receiptを返す。

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
schemaYes
outcomeYes
session_idYes

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals that closing destroys logs and read position (destructive side effects), that retries are idempotent and safe, and that the tool returns a structured receipt with states 'closed' or 'already_closed'. This is rich, honest behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core action, and every phrase earns its place. It covers purpose, side effects, retry behavior, and return type without any filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one required parameter) and the presence of an output schema (structured receipt), the description is sufficiently complete. It covers the action, the destructive side effect, the idempotency behavior, and the return format, leaving no major gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only defines session_id as a string with no description (0% coverage). The description compensates by explaining that session_id is used for retry safety, and that the same value will yield a receipt indicating whether it was newly closed or already closed. This adds meaningful semantics beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'Close the session and discard logs/read position.' It uses a specific verb ('close') and resource ('session'), and distinguishes itself from sibling tools like pty_open, pty_send, pty_read, and pty_list by focusing solely on the closing lifecycle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (to close a PTY session) but does not explicitly contrast it with alternatives or provide exclusion criteria. It adds a safety note about retrying with the same session_id, but lacks explicit 'when to use vs. not use' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pty_keyA

制御キーを送る（C-c, C-d, Enter, Tab, Up, Down... の別名に対応）。aiterm相関付きClaude sessionではturn相関を守るためC-cだけを許可し、承認UIはclaude_approvalで操作する。

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesキー名（例 "C-c", "Enter", "Up"）
session_idYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a significant behavioral trait: in Claude sessions, only C-c is permitted to preserve turn correlation, and that approval actions should be routed to claude_approval. However, it does not discuss error handling or consequences of sending disallowed keys, though the restriction itself is valuable transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action and immediately followed by a key usage rule. Every word serves a purpose: examples clarify the key parameter, and the restriction clarifies boundary conditions. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no output schema and no annotations, the description covers purpose, parameter examples, and usage restrictions, and relates it to sibling tools. It does not explain session_id or return behavior, but these are less critical given the tool's straightforward nature and the presence of sibling tools like pty_list and pty_open that likely establish session context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers only 50% of parameters (key has a description, session_id does not). The description adds meaning to the key parameter by listing acceptable aliases (C-c, C-d, Enter, Tab, Up, Down) and specifying a contextual restriction (only C-c in Claude sessions), compensating for the schema gap. session_id remains undocumented in both, but its purpose is implied as a session identifier.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('送る' / send) and resource ('制御キー' / control keys), and provides concrete examples (C-c, C-d, Enter, Tab, Up, Down) that distinguish it from sibling tools like pty_send (which likely sends arbitrary text) and claude_approval (which handles approval UI).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool and provides an exclusion: 'In aiterm-correlated Claude sessions, only C-c is allowed to maintain turn correlation, and the approval UI is operated with claude_approval.' This names an alternative tool (claude_approval) and clarifies a key restriction, giving clear usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pty_listB

握っているセッション一覧（名前 / 現在の前面コマンド / attach 状態 / サイズ / agent 情報）。

ParametersJSON Schema
NameRequiredDescriptionDefault
env_keysNo帰属確認用の非秘密環境変数名。指定したキーだけを返す

Output Schema

ParametersJSON Schema
NameRequiredDescription
schemaYes
sessionsYes
observed_atYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of behavioral disclosure. It communicates that this is a listing operation and enumerates the output fields, but it does not explicitly state that it is read-only, whether it requires an active session, or how it behaves when no sessions exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact phrase that lists exactly what the tool returns. There is no filler, and the essential scoping word '握っている' (held) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with an output schema and a fully documented optional parameter, the description is largely sufficient. The main gap is the lack of guidance on when to choose pty_list over sibling observation tools, but that is a usage-guidance issue rather than a completeness blocker.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool description itself does not mention env_keys, but the input schema fully documents it as non-secret environment variable names for attribution confirmation and states that only specified keys are returned. Since schema coverage is 100%, the baseline of 3 applies; the description adds no extra parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource (held sessions) and the fields returned (name, current foreground command, attach state, size, agent info), which distinguishes it from action-oriented siblings like pty_open and pty_send. It lacks an explicit verb, presenting the purpose as a noun phrase rather than 'lists sessions', so it stops just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use pty_list versus related tools such as pty_observe or pty_read. The list nature of the tool makes the basic use case implicit, but the description never states exclusions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pty_observeA

指定sessionの存在、paneとharnessの生存、状態と理由、native process identity、画面変化とCPU活動を構造化して観測する。画面本文と生argvは返さない。

ParametersJSON Schema
NameRequiredDescriptionDefault
cursorNo前回のactivity.cursor。省略・session再作成時は活動差分をnullで返す
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
stateYes
existsYes
reasonYes
schemaYes
harnessYes
activityYes
launch_idYes
pane_aliveYes
session_idYes
token_hintYes
observed_atYes
pane_processYes
harness_aliveYes
harness_processYes
process_identityYes
parent_deliveriesNo

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full behavioral burden. It meaningfully discloses that the tool excludes screen body and raw argv and outlines exactly which observations are returned. It does not state whether the tool has side effects or what happens when the session is missing, but for an observation tool this is a solid transparency baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler: the first lists the exact observation dimensions, the second gives the crucial exclusion guarantee, making the scope self-contained. The tool description is front-loaded with the key purpose and all content earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema exists, so return shape is already documented. The description adds the observation scope and negative compared with it, and cursor semantics are given in the schema. Yet it doesn't mention that session_id must come from an existing would-be decoration (for example pty_open or pty_list), which is a small but practical gap for an agent that uses the tool in a conversation with no prior context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50%; session_id has no field description. The tool description adds nearly nothing about the parameters: it only re-states 'specified session' and never explains the cursor parameter or the session_id value format or origin. The cursor semantics are only documented in the schema, and the description does not reinforce or extend them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a precise verb and resource: it observes structured aspects of a specified PTY session — existence, pane/harness liveness, status and reason, process identity, screen changes, and CPU activity. It also explicitly states what it does not return (screen body and raw argv), which separates it from content-returning tools like pty_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended context is implied: use this when you need structured health and liveness observations rather than screen content. However, the description never explicitly names alternative tools such as pty_read or states when not to use this tool, leaving the choice to inference from the excluded 'screen body and raw argv'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pty_openA

ローカル永続端末（POSIXはtmux、Windows nativeはpsmux 3.3.8以上）を1個開き、session_id を返す。backend server常駐ゆえ本サーバや クライアントが再起動してもセッションは生存する。リモート操作は専用ツールにせず、開いた端末の中で pty_send(session_id, "ssh host") と打って入る。

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoセッション名（省略時は t1, t2... を自動採番）
shellNo起動シェル（既定 bash）bash
env_varsNo現在のMCP processからsessionへ継承する環境変数名

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must carry behavioral info. It discloses persistence, backend server residency, and survival across restarts. It does not mention resource cleanup or that pty_close should be used, but the core persistent behavior is well explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two focused sentences; state the purpose, key behavioral trait, and usage pattern without redundancy. Front-loaded with the essential action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple create-resource tool, it clarifies persistence, the tmux/psmux dependency, and how to use it with pty_send. It lacks explicit mention of return schema/output shape, but the description mentions session_id is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; the description adds no parameter-specific information beyond the schema. The return session_id is mentioned but not parameter behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb ('開き') and resource ('ローカル永続端末'), states it returns a session_id, and distinguishes itself from remote operations by directing those to pty_send.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: to open a persistent local terminal; and when not to use dedicated remote-operation tools, with the alternative (pty_send inside the opened terminal) clearly specified.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pty_readA

セッションの出力をトークン削減して読む（既定は前回読取位置からの増分）。削減: 制御文字除去 / 反復圧縮 / head+tail 折りたたみ＋復元ヒント＋メタ併記。agent_transcript:true は agent session の直近完了ターンの最終 assistant メッセージを公開されたharness記録から平文で返す。長い回答が screen tail で切れた時の回収用。

ParametersJSON Schema
NameRequiredDescriptionDefault
rawNo削減せず生テキスト
rtkNo直前コマンド別の自前 reducer(git/grep/pytest 等)で縮約
fullNo増分でなく全文
waitNo完了まで待つ（dead / mark sentinel 自動検出 / until / 出力静止∧シェル復帰 / timeout）
linesNo末尾 N 行のみ
untilNoこの文字列が出たら完了とみなす（既定はリテラル部分一致。`$ ` や `[..]` もそのまま探せる）
screenNo描画済みスクリーン(TUI 向け)
timeoutNowait の最大待ち秒数
line_rangeNo全文からの行範囲 "A:B"
session_idYes
until_regexNountil を正規表現として扱う（既定 false＝リテラル部分一致。メタ文字を使いたい時のみ true）
operation_idNoClaude operationの期待ID。agent_transcript:true時だけ指定し、古い別operationの結果を拒否する
agent_transcriptNoagent session の直近完了ターンの最終 assistant メッセージを返す。Claudeはlaunch相関付きStop hook result、他harnessは通常transcript／session historyを使う。長い回答がscreen tailで切れた時の回収用

Output Schema

ParametersJSON Schema
NameRequiredDescription
modeYes
textYes
schemaYes
vendorYes
harnessYes
turn_idYes
raw_charsYes
session_idYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does substantial work: it discloses the token-reduction pipeline (control-character removal, repetition compression, head+tail folding, restoration hints), the incremental read-offset default, and agent_transcript source semantics with operation_id rejection. It does not explicitly flag side effects like advancing the read cursor, but it is far from opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one dense paragraph but stays focused: main action, default behavior, reduction details, and the special agent_transcript mode. Each clause earns its place, and the core read action is front-loaded. It could be broken into bullets for scannability, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 13 parameters and an output schema, and the description supplies essential high-level context that the schema alone does not: the reduction pipeline, the default cursor behavior, and the recovery purpose of agent_transcript. It does not walk through every wait/until/timeout combination, but the schema's 92% coverage and existing output schema compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 92%, so the baseline is 3. The description reinforces the purpose of key parameters such as agent_transcript and the incremental-read default that clarifies full, but it mostly echoes what the detailed schema descriptions already state rather than adding new per-parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'セッションの出力をトークン削減して読む' – a clear verb (read), resource (session output), and qualifier (token-reduced). It goes on to define the default incremental behavior and the agent_transcript special mode, distinguishing it from pty_send/key/list which act on the session rather than read from it. The action–resource pairing is unambiguous even without naming a sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states a clear default (incremental from last read position) and names a concrete recovery scenario for agent_transcript: '長い回答が screen tail で切れた時の回収用'. It provides clear context without explicit exclusions or named alternatives, which fits the 'clear context, no exclusions' level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pty_sendA

セッションへテキストを送る。通常PTYへは送信のみ（出力は pty_read で取得）。agent session（launcher起動）への send は自動で dispatch になる: TUI の ready gate と submit 分離を通して即返り、receipt の event_cursor を返す。dispatch した子は投げっぱなしでよい＝親はここで待たない。Codex親とClaude Code親にはAitermが回答本文を自動配送する。parent_deliveryがある場合はwait起動も通常の回答回収も不要。親は作業を続けるかターンを終える。その他の親では、完了通知をreceiptの wait_process.executable と wait_process.args をそのまま親のターンを塞がない別プロセスAPIへ渡して受け、PowerShell 7のStart-Processだけは windows_start_process_argument_list を単一文字列として渡す。exit を完了通知として扱う（exit 0=done / 3=timeout（既定600秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了。ポーリング不要）。wait_command は人間向け互換表示でありprocess境界へ使わない。foreground実行で親のターンを塞がない。自動配送以外の結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。force:true は非Claude agent sessionへの手動介入用の素送信。aiterm相関付きClaudeの承認UIはclaude_approvalを使う。

ParametersJSON Schema
NameRequiredDescriptionDefault
rawNo送信前サニタイズを無効化
rtkNo既知コマンドを rtk 形へ委譲して送る（rtk 不在なら素通し）
markNo完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（POSIX shell と PowerShell に対応。SSH先の現在の標準PS promptも自動判定。PowerShell の rc は成功0／失敗1。fish/csh/tcsh は未対応として送信前に拒否）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key("Enter") で実行される）。
textYes送る文字列（コマンド／prompt）。UTF-8で最大64KiB
enterNo末尾で Enter を送る（agent dispatch では常に submit）
forceNo非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない
imageNo添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）。agent session への dispatch だけで使え、harness別の添付手順はaitermが吸収する。通常PTY送信やforce送信では指定できない
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
modeYes
schemaYes
vendorYes
harnessYes
launch_idYes
session_idYes
event_cursorYes
wait_processYes
submit_residueYes
parent_deliveryNo
pane_input_recoveryNo

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full behavioral burden. It discloses critical non-obvious behavior: auto-dispatch vs raw send, immediate return, no polling needed, exit-code semantics (0=done, 3=timeout, 4=closed, 7=error), non-blocking foreground execution, and that parent_delivery removes the need for waiting or answer collection. This is exceptional transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is front-loaded and clear, and nearly every sentence adds information. However, the body is a single dense paragraph with many embedded conditional flows and exit-code details, making it harder to scan. Bullet points or a short summary would significantly improve readability without losing content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters, 2 required, no annotations, and an output schema, the description covers the full lifecycle: dispatch mode selection, result collection strategy, completion signalling, non-blocking behavior, and alternative tool routing. Nothing an agent needs to correctly select and invoke the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 88%, so the baseline is 3. The description adds operational context beyond the schema, such as force:true being manual intervention for non-Claude agent sessions and receipt fields like wait_process.executable/args being used for completion notifications. It does not redundantly re-document parameters already well described in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with a specific verb+resource: 'セッションへテキストを送る' (send text to a session), clearly defining the tool's core action. It then differentiates normal PTY send, agent auto-dispatch, force raw send, and Claude-specific approval routing, making it distinguishable from siblings like pty_read, pty_key, claude_turn, and claude_approval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: normal PTY sends are fire-and-forget with output collected via pty_read; agent sessions auto-dispatch and should not be awaited; force:true is for manual non-Claude intervention; claude_approval is for approval UI; wait_command is explicitly marked as human-compatible display and not for process boundaries. This strongly routes the agent to the right tool and mode.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 11 tool updatesv0.35.0
    • Addedagent_approval
    • Changedagent_launch5 fields changed
      • addedInput schema / properties / trust_project
        Added value: +{
+  "description": "対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める",
+  "type": "boolean"
+}
      • addedOutput schema / properties / initial_prompt
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "not_requested",
+        "not_sent",
+        "submitted_unconfirmed",
+        "started"
+      ],
+      "type": "string"
+    },
+    "turn_started": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "status",
+    "reason",
+    "turn_started"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / parent_delivery
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "child_outcome": {
+      "anyOf": [
+        {
+          "enum": [
+            "done",
+            "closed",
+            "rate_limited",
+            "error"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "child_turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "error_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "queued_submission_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "ready",
+        "sending",
+        "submitted",
+        "failed",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "delivery_id",
+    "state",
+    "child_outcome",
+    "child_turn_id",
+    "queued_submission_id",
+    "error_code"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / startup
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "ready",
+        "not_checked",
+        "blocked"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "reason"
+  ],
+  "type": "object"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "harness",
-  "provider",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_process",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "initial_prompt",
+  "startup",
+  "harness",
+  "provider",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedclaude_agent5 fields changed
      • addedInput schema / properties / trust_project
        Added value: +{
+  "description": "対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める",
+  "type": "boolean"
+}
      • addedOutput schema / properties / initial_prompt
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "not_requested",
+        "not_sent",
+        "submitted_unconfirmed",
+        "started"
+      ],
+      "type": "string"
+    },
+    "turn_started": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "status",
+    "reason",
+    "turn_started"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / parent_delivery
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "child_outcome": {
+      "anyOf": [
+        {
+          "enum": [
+            "done",
+            "closed",
+            "rate_limited",
+            "error"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "child_turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "error_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "queued_submission_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "ready",
+        "sending",
+        "submitted",
+        "failed",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "delivery_id",
+    "state",
+    "child_outcome",
+    "child_turn_id",
+    "queued_submission_id",
+    "error_code"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / startup
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "ready",
+        "not_checked",
+        "blocked"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "reason"
+  ],
+  "type": "object"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "harness",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_process",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "initial_prompt",
+  "startup",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedclaude_turn1 field changed
      • addedOutput schema / properties / parent_delivery
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "child_outcome": {
+      "anyOf": [
+        {
+          "enum": [
+            "done",
+            "closed",
+            "rate_limited",
+            "error"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "child_turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "error_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "queued_submission_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "ready",
+        "sending",
+        "submitted",
+        "failed",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "delivery_id",
+    "state",
+    "child_outcome",
+    "child_turn_id",
+    "queued_submission_id",
+    "error_code"
+  ],
+  "type": "object"
+}
    • Changedcodex_agent5 fields changed
      • addedInput schema / properties / trust_project
        Added value: +{
+  "description": "対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める",
+  "type": "boolean"
+}
      • addedOutput schema / properties / initial_prompt
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "not_requested",
+        "not_sent",
+        "submitted_unconfirmed",
+        "started"
+      ],
+      "type": "string"
+    },
+    "turn_started": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "status",
+    "reason",
+    "turn_started"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / parent_delivery
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "child_outcome": {
+      "anyOf": [
+        {
+          "enum": [
+            "done",
+            "closed",
+            "rate_limited",
+            "error"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "child_turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "error_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "queued_submission_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "ready",
+        "sending",
+        "submitted",
+        "failed",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "delivery_id",
+    "state",
+    "child_outcome",
+    "child_turn_id",
+    "queued_submission_id",
+    "error_code"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / startup
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "ready",
+        "not_checked",
+        "blocked"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "reason"
+  ],
+  "type": "object"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "harness",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_process",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "initial_prompt",
+  "startup",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedcomposer_agent5 fields changed
      • addedInput schema / properties / trust_project
        Added value: +{
+  "description": "対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める",
+  "type": "boolean"
+}
      • addedOutput schema / properties / initial_prompt
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "not_requested",
+        "not_sent",
+        "submitted_unconfirmed",
+        "started"
+      ],
+      "type": "string"
+    },
+    "turn_started": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "status",
+    "reason",
+    "turn_started"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / parent_delivery
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "child_outcome": {
+      "anyOf": [
+        {
+          "enum": [
+            "done",
+            "closed",
+            "rate_limited",
+            "error"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "child_turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "error_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "queued_submission_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "ready",
+        "sending",
+        "submitted",
+        "failed",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "delivery_id",
+    "state",
+    "child_outcome",
+    "child_turn_id",
+    "queued_submission_id",
+    "error_code"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / startup
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "ready",
+        "not_checked",
+        "blocked"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "reason"
+  ],
+  "type": "object"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "harness",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_process",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "initial_prompt",
+  "startup",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedgrok_agent5 fields changed
      • addedInput schema / properties / trust_project
        Added value: +{
+  "description": "対象projectを信頼し、既知のworkspace・project hooks・MCP初期同意を起動中に進める",
+  "type": "boolean"
+}
      • addedOutput schema / properties / initial_prompt
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "not_requested",
+        "not_sent",
+        "submitted_unconfirmed",
+        "started"
+      ],
+      "type": "string"
+    },
+    "turn_started": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "status",
+    "reason",
+    "turn_started"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / parent_delivery
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "child_outcome": {
+      "anyOf": [
+        {
+          "enum": [
+            "done",
+            "closed",
+            "rate_limited",
+            "error"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "child_turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "error_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "queued_submission_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "ready",
+        "sending",
+        "submitted",
+        "failed",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "delivery_id",
+    "state",
+    "child_outcome",
+    "child_turn_id",
+    "queued_submission_id",
+    "error_code"
+  ],
+  "type": "object"
+}
      • addedOutput schema / properties / startup
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "ready",
+        "not_checked",
+        "blocked"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "reason"
+  ],
+  "type": "object"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "harness",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_process",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "initial_prompt",
+  "startup",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedpty_list2 fields changed
      • addedInput schema / properties / env_keys
        Added value: +{
+  "description": "帰属確認用の非秘密環境変数名。指定したキーだけを返す",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "observed_at": {
+      "type": "string"
+    },
+    "schema": {
+      "const": "aiterm.pty-list-result.v1",
+      "type": "string"
+    },
+    "sessions": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "attached": {
+            "type": "boolean"
+          },
+          "current_command": {
+            "type": "string"
+          },
+          "environment": {
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "harness": {
+            "anyOf": [
+              {
+                "enum": [
+                  "claude-code",
+                  "codex-cli",
+                  "grok-cli",
+                  "cursor-cli"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "height": {
+            "type": "number"
+          },
+          "session_id": {
+            "type": "string"
+          },
+          "width": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "session_id",
+          "current_command",
+          "attached",
+          "width",
+          "height",
+          "harness",
+          "environment"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "schema",
+    "observed_at",
+    "sessions"
+  ],
+  "type": "object"
+}
    • Addedpty_observe
    • Changedpty_open1 field changed
      • addedInput schema / properties / env_vars
        Added value: +{
+  "description": "現在のMCP processからsessionへ継承する環境変数名",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • Changedpty_send2 fields changed
      • changedInput schema / properties / mark / description
        Previous value: -"完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（POSIX shell と PowerShell に対応。PowerShell の rc は成功0／失敗1。fish/csh/tcsh は未対応として送信前に拒否）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"New value: +"完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（POSIX shell と PowerShell に対応。SSH先の現在の標準PS promptも自動判定。PowerShell の rc は成功0／失敗1。fish/csh/tcsh は未対応として送信前に拒否）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"
      • addedOutput schema / properties / parent_delivery
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "child_outcome": {
+      "anyOf": [
+        {
+          "enum": [
+            "done",
+            "closed",
+            "rate_limited",
+            "error"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "child_turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "error_code": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "queued_submission_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "state": {
+      "enum": [
+        "waiting",
+        "ready",
+        "sending",
+        "submitted",
+        "failed",
+        "unknown"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "delivery_id",
+    "state",
+    "child_outcome",
+    "child_turn_id",
+    "queued_submission_id",
+    "error_code"
+  ],
+  "type": "object"
+}
  2. 3 tool updatesv0.31.2
    • Changedagent_launch1 field changed
      • addedInput schema / properties / image
        Added value: +{
+  "description": "初手プロンプトへ添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • Changedagent_steer1 field changed
      • addedInput schema / properties / image
        Added value: +{
+  "description": "添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • Changedpty_send2 fields changed
      • addedInput schema / properties / image
        Added value: +{
+  "description": "添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）。agent session への dispatch だけで使え、harness別の添付手順はaitermが吸収する。通常PTY送信やforce送信では指定できない",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / pane_input_recovery
        Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  3. 8 tool updatesv0.29.21
    • Changedagent_launch1 field changed
      • addedInput schema / properties / throughline_supplement_file
        Added value: +{
+  "description": "Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path",
+  "minLength": 1,
+  "type": "string"
+}
    • Addedagent_steer
    • Changedclaude_agent1 field changed
      • addedInput schema / properties / throughline_supplement_file
        Added value: +{
+  "description": "Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedcodex_agent1 field changed
      • addedInput schema / properties / throughline_supplement_file
        Added value: +{
+  "description": "Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedcomposer_agent1 field changed
      • addedInput schema / properties / throughline_supplement_file
        Added value: +{
+  "description": "Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedgrok_agent1 field changed
      • addedInput schema / properties / throughline_supplement_file
        Added value: +{
+  "description": "Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedpty_read1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "harness": {
+      "anyOf": [
+        {
+          "enum": [
+            "claude-code",
+            "codex-cli",
+            "grok-cli",
+            "cursor-cli"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "mode": {
+      "enum": [
+        "terminal",
+        "agent_transcript"
+      ],
+      "type": "string"
+    },
+    "raw_chars": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "schema": {
+      "const": "aiterm.pty-read-result.v1",
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "text": {
+      "type": "string"
+    },
+    "turn_id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "vendor": {
+      "anyOf": [
+        {
+          "enum": [
+            "claude",
+            "codex",
+            "grok",
+            "composer",
+            "cursor"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "schema",
+    "mode",
+    "session_id",
+    "text",
+    "vendor",
+    "turn_id",
+    "harness",
+    "raw_chars"
+  ],
+  "type": "object"
+}
    • Changedpty_send1 field changed
      • changedInput schema / properties / force / description
        Previous value: -"破壊的コマンドゲートを越える。非Claude agent sessionではdispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"New value: +"非Claude agent sessionでは自動dispatchせず素送信する。aiterm相関付きClaudeのactive turnには使えない"
  4. 6 tool updatesv0.29.8
    • Changedagent_launch2 fields changed
      • addedOutput schema / properties / wait_process
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "args": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "executable": {
+          "type": "string"
+        },
+        "windows_start_process_argument_list": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "executable",
+        "args",
+        "windows_start_process_argument_list"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "harness",
-  "provider",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "harness",
+  "provider",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedclaude_agent2 fields changed
      • addedOutput schema / properties / wait_process
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "args": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "executable": {
+          "type": "string"
+        },
+        "windows_start_process_argument_list": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "executable",
+        "args",
+        "windows_start_process_argument_list"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "harness",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedcodex_agent2 fields changed
      • addedOutput schema / properties / wait_process
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "args": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "executable": {
+          "type": "string"
+        },
+        "windows_start_process_argument_list": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "executable",
+        "args",
+        "windows_start_process_argument_list"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "harness",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedcomposer_agent2 fields changed
      • addedOutput schema / properties / wait_process
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "args": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "executable": {
+          "type": "string"
+        },
+        "windows_start_process_argument_list": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "executable",
+        "args",
+        "windows_start_process_argument_list"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "harness",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedgrok_agent2 fields changed
      • addedOutput schema / properties / wait_process
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "args": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "executable": {
+          "type": "string"
+        },
+        "windows_start_process_argument_list": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "executable",
+        "args",
+        "windows_start_process_argument_list"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "harness",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_process",
+  "wait_command",
+  "submit_residue"
+]
    • Changedpty_send2 fields changed
      • addedOutput schema / properties / wait_process
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "args": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "executable": {
+          "type": "string"
+        },
+        "windows_start_process_argument_list": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "executable",
+        "args",
+        "windows_start_process_argument_list"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "mode",
-  "session_id",
-  "event_cursor",
-  "launch_id",
-  "vendor",
-  "harness",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "mode",
+  "session_id",
+  "event_cursor",
+  "wait_process",
+  "launch_id",
+  "vendor",
+  "harness",
+  "submit_residue"
+]
  5. 8 tool updatesv0.28.0
    • Changedagent_configure3 fields changed
      • addedOutput schema / properties / harness
        Added value: +{
+  "enum": [
+    "claude-code",
+    "codex-cli",
+    "grok-cli",
+    "cursor-cli"
+  ],
+  "type": "string"
+}
      • changedOutput schema / properties / provider / enum
        Previous value: -[
-  "claude",
-  "codex",
-  "grok",
-  "composer"
-]New value: +[
+  "claude",
+  "codex",
+  "grok",
+  "composer",
+  "cursor"
+]
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "session_id",
-  "provider",
-  "model",
-  "reasoning_effort"
-]New value: +[
+  "schema",
+  "session_id",
+  "provider",
+  "harness",
+  "model",
+  "reasoning_effort"
+]
    • Addedagent_launch
    • Changedclaude_agent2 fields changed
      • addedOutput schema / properties / harness
        Added value: +{
+  "const": "claude-code",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_command",
+  "submit_residue"
+]
    • Changedcodex_agent3 fields changed
      • changedInput schema / properties / write_scope / description
        Previous value: -"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codex／Grok／Composerのread-onlyはCLI sandboxで実効禁止する"New value: +"能力宣言。read-only、または書込みを許可するパスの説明文字列。対応harnessのread-onlyはCLI標準のread-only面で実効禁止する"
      • addedOutput schema / properties / harness
        Added value: +{
+  "const": "codex-cli",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_command",
+  "submit_residue"
+]
    • Changedcomposer_agent3 fields changed
      • changedInput schema / properties / write_scope / description
        Previous value: -"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codex／Grok／Composerのread-onlyはCLI sandboxで実効禁止する"New value: +"能力宣言。read-only、または書込みを許可するパスの説明文字列。対応harnessのread-onlyはCLI標準のread-only面で実効禁止する"
      • addedOutput schema / properties / harness
        Added value: +{
+  "const": "grok-cli",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_command",
+  "submit_residue"
+]
    • Changedgrok_agent3 fields changed
      • changedInput schema / properties / write_scope / description
        Previous value: -"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codex／Grok／Composerのread-onlyはCLI sandboxで実効禁止する"New value: +"能力宣言。read-only、または書込みを許可するパスの説明文字列。対応harnessのread-onlyはCLI標準のread-only面で実効禁止する"
      • addedOutput schema / properties / harness
        Added value: +{
+  "const": "grok-cli",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "provider",
-  "session_id",
-  "managed_completion",
-  "event_cursor",
-  "wait_command",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "provider",
+  "harness",
+  "session_id",
+  "managed_completion",
+  "event_cursor",
+  "wait_command",
+  "submit_residue"
+]
    • Changedpty_read1 field changed
      • changedInput schema / properties / agent_transcript / description
        Previous value: -"agent session の直近完了ターンの最終 assistant メッセージを返す。Claudeはlaunch相関付きStop hook result、他vendorは通常transcriptを使う。長い回答がscreen tailで切れた時の回収用"New value: +"agent session の直近完了ターンの最終 assistant メッセージを返す。Claudeはlaunch相関付きStop hook result、他harnessは通常transcript／session historyを使う。長い回答がscreen tailで切れた時の回収用"
    • Changedpty_send3 fields changed
      • addedOutput schema / properties / harness
        Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "claude-code",
+        "codex-cli",
+        "grok-cli",
+        "cursor-cli"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
      • changedOutput schema / properties / vendor / anyOf
        Previous value: -[
-  {
-    "enum": [
-      "claude",
-      "codex",
-      "grok",
-      "composer"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "claude",
+      "codex",
+      "grok",
+      "composer",
+      "cursor"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
      • changedOutput schema / required
        Previous value: -[
-  "schema",
-  "mode",
-  "session_id",
-  "event_cursor",
-  "launch_id",
-  "vendor",
-  "submit_residue"
-]New value: +[
+  "schema",
+  "mode",
+  "session_id",
+  "event_cursor",
+  "launch_id",
+  "vendor",
+  "harness",
+  "submit_residue"
+]
  6. 1 tool updatev0.27.9
    • Changedpty_send1 field changed
      • changedInput schema / properties / mark / description
        Previous value: -"完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（ネスト中や非シェル前面でも効く確実な完了検出。手で until を組む必要なし）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"New value: +"完了 sentinel(終了コード付き)で包む。pty_read(wait:true) が until 無しでも自動検出して完了確定する（POSIX shell と PowerShell に対応。PowerShell の rc は成功0／失敗1。fish/csh/tcsh は未対応として送信前に拒否）。 enter:false と併用すると sentinel が実行されず完了検出が発火しない（送信後に pty_key(\"Enter\") で実行される）。"
  7. 5 tool updatesv0.27.0
    • Addedagent_configure
    • Changedclaude_agent1 field changed
      • addedInput schema / properties / env_vars
        Added value: +{
+  "description": "起動したagentへ現在のMCP processから継承する環境変数名。値はtool引数へ渡さない",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • Changedcodex_agent3 fields changed
      • addedInput schema / properties / env_vars
        Added value: +{
+  "description": "起動したagentへ現在のMCP processから継承する環境変数名。値はtool引数へ渡さない",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedInput schema / properties / reasoning_effort / description
        Previous value: -"reasoning effort（思考レベル）。low/medium/high/xhigh/max/ultra（CLI 版依存）。ultra は max 推論＋proactive 自動委譲 ON＝使用量急増注意（明示要求時のみ）。省略時は端末 config／CLI 既定。"New value: +"reasoning effort（思考レベル）。low/medium/high/xhigh/max/ultra（CLI／model 版依存）。ultra は max 推論＋proactive 自動委譲 ON＝使用量急増注意（明示要求時のみ）。省略時は端末 config／CLI 既定。"
      • changedInput schema / properties / write_scope / description
        Previous value: -"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codexのread-onlyだけはCLI sandboxで実効禁止する"New value: +"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codex／Grok／Composerのread-onlyはCLI sandboxで実効禁止する"
    • Changedcomposer_agent4 fields changed
      • addedInput schema / properties / env_vars
        Added value: +{
+  "description": "起動したagentへ現在のMCP processから継承する環境変数名。値はtool引数へ渡さない",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedInput schema / properties / model / description
        Previous value: -"起動モデル。省略時は grok-composer-2.5-fast"New value: +"起動モデル。省略時は grok-composer-2.5-fast。既定／explicit modelを起動前にlive catalogへ照合し、不在ならfallbackせずエラー"
      • changedInput schema / properties / reasoning_effort / description
        Previous value: -"指定不可（grok CLI の --effort は headless 専用で、対話 TUI では警告の上無視される。composer は effort 自体非対応）。指定すると起動前にエラーを返す"New value: +"Grok Build reasoning effort。利用可能値はCLI／modelのlive catalogに従う。省略時はCLI／model既定。"
      • changedInput schema / properties / write_scope / description
        Previous value: -"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codexのread-onlyだけはCLI sandboxで実効禁止する"New value: +"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codex／Grok／Composerのread-onlyはCLI sandboxで実効禁止する"
    • Changedgrok_agent4 fields changed
      • addedInput schema / properties / env_vars
        Added value: +{
+  "description": "起動したagentへ現在のMCP processから継承する環境変数名。値はtool引数へ渡さない",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedInput schema / properties / model / description
        Previous value: -"起動モデル。省略時は grok-4.5"New value: +"起動モデル。省略時は grok-4.6。explicit modelを起動前にlive catalogへ照合し、不在ならfallbackせずエラー"
      • changedInput schema / properties / reasoning_effort / description
        Previous value: -"指定不可（grok CLI の --effort は headless 専用で、対話 TUI では警告の上無視される。composer は effort 自体非対応）。指定すると起動前にエラーを返す"New value: +"Grok Build reasoning effort。利用可能値はCLI／modelのlive catalogに従う。省略時はCLI／model既定。"
      • changedInput schema / properties / write_scope / description
        Previous value: -"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codexのread-onlyだけはCLI sandboxで実効禁止する"New value: +"能力宣言。read-only、または書込みを許可するパスの説明文字列。Codex／Grok／Composerのread-onlyはCLI sandboxで実効禁止する"
  8. 4 tool updatesv0.23.0
    • Changedclaude_agent1 field changed
      • addedInput schema / properties / throughline_source_session
        Added value: +{
+  "description": "同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedcodex_agent1 field changed
      • addedInput schema / properties / throughline_source_session
        Added value: +{
+  "description": "同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedcomposer_agent1 field changed
      • addedInput schema / properties / throughline_source_session
        Added value: +{
+  "description": "同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する",
+  "minLength": 1,
+  "type": "string"
+}
    • Changedgrok_agent1 field changed
      • addedInput schema / properties / throughline_source_session
        Added value: +{
+  "description": "同一端末のThroughline sessionから所有権を変えずに記憶を読み、promptのmissionより前へ注入する",
+  "minLength": 1,
+  "type": "string"
+}
  9. 9 tool updatesv0.22.0
    • Addedclaude_agent
    • Addedclaude_turn
    • Changedcodex_agent4 fields changed
      • addedInput schema / properties / write_scope
        Added value: +{
+  "description": "能力宣言。read-only、または書込みを許可するパスの説明文字列。Codexのread-onlyだけはCLI sandboxで実効禁止する",
+  "minLength": 1,
+  "type": "string"
+}
      • addedOutput schema / properties / managed_completion / description
        Added value: +"後方互換field。trueはaiterm完了相関が有効という意味で、project/user環境の隔離を意味しない"
      • addedOutput schema / properties / write_scope
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / write_scope_enforcement
        Added value: +{
+  "enum": [
+    "enforced_read_only",
+    "declaration_only_unsupported"
+  ],
+  "type": "string"
+}
    • Changedcomposer_agent4 fields changed
      • addedInput schema / properties / write_scope
        Added value: +{
+  "description": "能力宣言。read-only、または書込みを許可するパスの説明文字列。Codexのread-onlyだけはCLI sandboxで実効禁止する",
+  "minLength": 1,
+  "type": "string"
+}
      • addedOutput schema / properties / managed_completion / description
        Added value: +"後方互換field。trueはaiterm完了相関が有効という意味で、project/user環境の隔離を意味しない"
      • addedOutput schema / properties / write_scope
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / write_scope_enforcement
        Added value: +{
+  "enum": [
+    "enforced_read_only",
+    "declaration_only_unsupported"
+  ],
+  "type": "string"
+}
    • Addedgrok_agent
    • Addedpty_close
    • Addedpty_key
    • Addedpty_read
    • Addedpty_send
  10. 6 tool updatesv0.20.2
    • First observedclaude_approval
    • First observedcodex_agent
    • First observedcomposer_agent
    • First observeddiagnostics
    • First observedpty_list
    • First observedpty_open
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 18 tools

Disambiguation3/5

The pty_* tools are clearly distinct, and agent_launch consolidates launching. However, claude_agent/codex_agent/grok_agent/composer_agent are redundant aliases for agent_launch, and claude_turn overlaps with pty_read(agent_transcript:true) while agent_steer overlaps with pty_send for agent sessions. Descriptions are detailed enough to resolve most ambiguity.

Naming Consistency4/5

Most tools follow a clear prefix convention: pty_* for terminal primitives, agent_* for agent lifecycle, and vendor-specific *_agent aliases. Minor inconsistency: claude_turn vs claude_agent vs claude_approval, and agent_approval vs claude_approval, break a single predictable pattern.

Tool Count4/5

18 tools is slightly above the ideal 3-15 range but justified by the dual scope of terminal control and multi-vendor agent orchestration. The four legacy alias tools inflate the count; consolidation into agent_launch would make it tighter.

Completeness4/5

The terminal lifecycle (open/send/read/list/observe/close/key) and agent operations (launch/configure/steer/approval/turn retrieval) are well covered. Minor gaps like terminal resize or an explicit generic status/wait tool are workarounds through existing observe/read mechanisms.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers