aiterm-mcp

Overview Schema Source Related Servers Discussions Admin

agent_launch

Launch coding agents into persistent sessions from a single entry point, run them in background, and collect results without blocking.

Instructions

エージェントを単一の標準入口から永続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起動も通常の回答回収も不要。親は作業を続けるかターンを終える。Cursor親にはparent_deliveryとwait_processが付く。作業を続ければ次のツール返りに回答が差し込まれ、ターンを終える前にwait_processを背景で起動するとidle中の完了でも起きられる。ポーリングとpty_read(agent_transcript:true)は不要。その他の親では、完了通知を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)。

Input Schema

TableJSON Schema

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

Output Schema

TableJSON Schema

Name	Required	Description
`schema`	Yes
`harness`	Yes
`startup`	Yes
`provider`	Yes	旧互換field。新規連携はharnessを使う
`session_id`	Yes
`write_scope`	No
`event_cursor`	Yes
`wait_command`	Yes
`wait_process`	Yes
`initial_prompt`	Yes
`submit_residue`	Yes
`parent_delivery`	No
`managed_completion`	Yes
`write_scope_enforcement`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.35.0Sep 10, 2026

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"
+]

Changed1 schema field changedv0.31.2Sep 8, 2026

addedInput schema / properties / image

Added value: +{
+  "description": "初手プロンプトへ添付する画像ファイルの絶対パス（png/jpg/jpeg/gif/webp）",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedv0.29.21Sep 2, 2026

addedInput schema / properties / throughline_supplement_file

Added value: +{
+  "description": "Throughline 0.10.8以降へそのまま渡すproject束縛済み長期記憶・知識の補足JSON path",
+  "minLength": 1,
+  "type": "string"
+}

Changed2 schema fields changedv0.29.8Aug 29, 2026

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"
+]

Addedv0.28.0Aug 23, 2026

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 carries the full burden and delivers exceptionally: it discloses that prompt returns immediately without waiting, that dispatched children are fire-and-forget, the full exit-code contract (0=done, 3=timeout/600s default, 4=closed, 7=error), that polling is unnecessary, that foreground execution does not block the parent turn, and that wait_command is display-only. It also covers delivery-mode differences per parent and the PowerShell 7 argument format quirk.

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?

Every sentence carries distinct, non-redundant information, so nothing is wasted, but the text is one dense unstructured paragraph with no sectioning or bullet hierarchy. Critical operational data (exit codes, timeout) is buried mid-paragraph rather than front-loaded, making it harder for an agent to parse than its information density justifies.

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 13-parameter, annotation-free, asynchronous launch tool with an output schema, the description is remarkably complete: it covers harness/model selection, shared context (HOME, cwd, MCP, plugins, permissions), injected sub-agent properties (delegation_allowed=true, parent session, lineage), completion correlation per parent type, receipt handling, exit semantics, and result collection via pty_read(agent_transcript:true). Return-value structure is reasonably deferred to the output schema, and no critical invocation detail appears 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 coverage is 100%, so the baseline is 3; the description adds genuine value beyond the schema by clarifying the harness/model relationship (model is the inference model chosen by the harness, a separate axis) and giving a concrete mapping example (Grok Composer = harness=grok-cli with model=grok-composer-2.5-fast). This resolves ambiguity the enum and string descriptions alone would leave open.

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 opening sentence states a specific verb and resource: 'エージェントを単一の標準入口から永続sessionへ起動する' (launch an agent from a single standard entry point into a persistent session). It distinguishes this from the per-harness siblings (claude_agent, codex_agent, grok_agent, composer_agent) by asserting it is THE unified entry point, and further disambiguates by explaining the harness/model axis and that Grok Composer is not a separate harness.

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 strong contextual guidance: 'single standard entry point' implies this tool supersedes per-harness siblings, and it provides detailed parent-type-specific flows (Codex/Claude Code auto-delivery, Cursor wait_process, other parents passing receipt fields to a separate API). However, it never names the sibling tools as alternatives or states explicit when-not-to-use conditions, so exclusion guidance is only implicit.

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

Deploy Server