Unified Agent + reusable Go agent core.
docs: add ACP user documentation
+749
-28
+1
docs/README.md
+1
docs/README.md
+163
docs/acp.md
+163
docs/acp.md
···
1
+
# ACP
2
+
3
+
This page describes the user-facing ACP support now available in Mistermorph.
4
+
5
+
## What It Is
6
+
7
+
Mistermorph can delegate one isolated subtask to an external ACP agent.
8
+
9
+
Today that means:
10
+
11
+
- Mistermorph acts as an ACP client.
12
+
- The external agent runs as a local child process over `stdio`.
13
+
- The parent agent uses the explicit `acp_spawn` tool to start that subtask.
14
+
15
+
This is separate from `spawn`.
16
+
17
+
- `spawn` starts another local Mistermorph agent loop.
18
+
- `acp_spawn` starts an external ACP-compatible agent or adapter.
19
+
20
+
## Current Scope
21
+
22
+
The current implementation is intentionally narrow:
23
+
24
+
- client-only; Mistermorph is not an ACP server
25
+
- `stdio` transport only
26
+
- one synchronous session per call
27
+
- one prompt turn per call
28
+
- text prompts only
29
+
- `authenticate` when the agent advertises auth methods
30
+
- `session/set_config_option` when `session/new` advertises config option ids
31
+
- client callbacks for:
32
+
- `session/request_permission`
33
+
- `fs/read_text_file`
34
+
- `fs/write_text_file`
35
+
- `terminal/create`
36
+
- `terminal/output`
37
+
- `terminal/wait_for_exit`
38
+
- `terminal/kill`
39
+
- `terminal/release`
40
+
41
+
Not supported yet:
42
+
43
+
- MCP passthrough
44
+
- session reuse
45
+
- HTTP / SSE transport
46
+
- interactive approval UI
47
+
48
+
## Config
49
+
50
+
ACP support has two config surfaces:
51
+
52
+
1. Enable the explicit tool entry.
53
+
2. Define one or more ACP agent profiles.
54
+
55
+
Example:
56
+
57
+
```yaml
58
+
tools:
59
+
acp_spawn:
60
+
enabled: true
61
+
62
+
acp:
63
+
agents:
64
+
- name: "codex"
65
+
enable: true
66
+
type: "stdio"
67
+
command: "codex-acp"
68
+
args: []
69
+
env: {}
70
+
cwd: "."
71
+
read_roots: ["."]
72
+
write_roots: ["."]
73
+
session_options:
74
+
mode: "auto"
75
+
reasoning_effort: "low"
76
+
```
77
+
78
+
Field notes:
79
+
80
+
- `tools.acp_spawn.enabled` controls only the explicit `acp_spawn` tool entry.
81
+
- `acp.agents[].name` is the profile name the parent agent uses.
82
+
- `cwd`, `read_roots`, and `write_roots` constrain ACP file and terminal callbacks.
83
+
- `session_options` is passed into `session/new._meta`.
84
+
- If the ACP agent advertises config option ids in `session/new`, matching keys from `session_options` are also sent through `session/set_config_option`.
85
+
86
+
## How to Use It
87
+
88
+
At runtime, the parent agent must explicitly choose `acp_spawn`.
89
+
90
+
Typical prompt:
91
+
92
+
```text
93
+
Only call acp_spawn. Use the codex agent. Read ./README.md and summarize it in exactly 5 Chinese sentences. Do not call spawn. Do not read the file yourself.
94
+
```
95
+
96
+
The `acp_spawn` parameters are:
97
+
98
+
- `agent`: ACP profile name
99
+
- `task`: task text for the external agent
100
+
- `cwd`: optional working-directory override
101
+
- `output_schema`: optional structured-output label
102
+
- `observe_profile`: optional local observation hint
103
+
104
+
The result comes back in the same `SubtaskResult` envelope used by other isolated task paths.
105
+
106
+
## Execution Model
107
+
108
+
One `acp_spawn` call does this:
109
+
110
+
1. load the ACP profile
111
+
2. start the wrapper process
112
+
3. `initialize`
113
+
4. `authenticate` if needed
114
+
5. `session/new`
115
+
6. `session/set_config_option` for advertised option ids
116
+
7. `session/prompt`
117
+
8. serve ACP callbacks during the turn
118
+
9. collect final text and stop reason
119
+
10. close the session/process
120
+
121
+
This means the parent agent does not need to know whether the child path was local `spawn` or ACP `acp_spawn`. Both return the same top-level envelope.
122
+
123
+
## Security and Limits
124
+
125
+
Two limits matter here.
126
+
127
+
First, ACP permission requests are not the real security boundary. The real boundary is what Mistermorph actually implements in its client callbacks:
128
+
129
+
- allowed file roots
130
+
- allowed terminal working directories
131
+
- local write and process rules
132
+
133
+
Second, the wrapper process itself is still a local child process.
134
+
135
+
That means:
136
+
137
+
- ACP callback limits apply to ACP method calls
138
+
- they do not automatically sandbox arbitrary direct behavior inside the wrapper itself
139
+
140
+
So ACP support should be treated as controlled delegation, not a hard sandbox.
141
+
142
+
## Codex Adapter Notes
143
+
144
+
Current Codex integration is based on an external ACP adapter such as `codex-acp`.
145
+
146
+
Practical checks:
147
+
148
+
1. `codex` itself must already work on the machine.
149
+
2. `mistermorph tools` should show `acp_spawn`.
150
+
3. the ACP profile should point to `codex-acp`.
151
+
152
+
The repository also includes an opt-in live integration test:
153
+
154
+
```bash
155
+
MISTERMORPH_ACP_CODEX_INTEGRATION=1 go test ./internal/acpclient -run TestRunPrompt_CodexACPIntegration -v
156
+
```
157
+
158
+
## See Also
159
+
160
+
- [Tools](./tools.md)
161
+
- [Configuration](./configuration.md)
162
+
- [Feature Design](./feat/feat_20260410_acp_agent_support.md)
163
+
- [Implementation Progress](./feat/feat_20260410_acp_agent_support_impl.md)
+8
web/vitepress/docs/.vitepress/i18n.ts
+8
web/vitepress/docs/.vitepress/i18n.ts
+141
web/vitepress/docs/guide/acp.md
+141
web/vitepress/docs/guide/acp.md
···
1
+
---
2
+
title: ACP
3
+
description: Use external ACP agents through acp_spawn.
4
+
---
5
+
6
+
# ACP
7
+
8
+
Mister Morph can delegate one isolated task to an external ACP agent.
9
+
10
+
Today, ACP support is intentionally narrow:
11
+
12
+
- Mister Morph is an ACP client, not an ACP server.
13
+
- Transport is `stdio` only.
14
+
- Each `acp_spawn` call creates one synchronous session and one prompt turn.
15
+
- The external agent is started from `acp.agents`.
16
+
17
+
## When to Use ACP
18
+
19
+
Use ACP when the child task should run inside an external agent stack instead of another local Mister Morph loop.
20
+
21
+
Typical examples:
22
+
23
+
- run Codex through an ACP adapter
24
+
- run another ACP-compatible coding agent
25
+
- keep the parent loop simple while delegating file edits or command execution to a specialized external agent
26
+
27
+
If you only need another local Mister Morph loop, use [Subagents](/guide/subagents) and `spawn` instead.
28
+
29
+
## What Is Supported
30
+
31
+
Current support includes:
32
+
33
+
- `authenticate` when advertised by the ACP agent
34
+
- `session/new`
35
+
- `session/set_config_option` for option ids advertised by `session/new`
36
+
- `session/prompt`
37
+
- `session/request_permission`
38
+
- `fs/read_text_file`
39
+
- `fs/write_text_file`
40
+
- minimal `terminal/*`
41
+
42
+
Not supported yet:
43
+
44
+
- MCP passthrough
45
+
- session reuse
46
+
- HTTP / SSE transport
47
+
48
+
## Config
49
+
50
+
You need two pieces of config:
51
+
52
+
1. enable the explicit tool entry
53
+
2. define at least one ACP profile
54
+
55
+
```yaml
56
+
tools:
57
+
acp_spawn:
58
+
enabled: true
59
+
60
+
acp:
61
+
agents:
62
+
- name: "codex"
63
+
enable: true
64
+
type: "stdio"
65
+
command: "codex-acp"
66
+
args: []
67
+
env: {}
68
+
cwd: "."
69
+
read_roots: ["."]
70
+
write_roots: ["."]
71
+
session_options:
72
+
mode: "auto"
73
+
reasoning_effort: "low"
74
+
```
75
+
76
+
Notes:
77
+
78
+
- `tools.acp_spawn.enabled` controls only the `acp_spawn` entry.
79
+
- `session_options` is first passed through `session/new._meta`.
80
+
- If the ACP agent advertises config option ids, matching keys are also sent through `session/set_config_option`.
81
+
82
+
## Prompt Pattern
83
+
84
+
Tell the parent agent to use `acp_spawn` explicitly.
85
+
86
+
Example:
87
+
88
+
```text
89
+
Only call acp_spawn. Use the codex agent. Read ./README.md and summarize it in exactly 5 Chinese sentences. Do not call spawn. Do not read the file yourself.
90
+
```
91
+
92
+
`acp_spawn` accepts:
93
+
94
+
- `agent`
95
+
- `task`
96
+
- `cwd`
97
+
- `output_schema`
98
+
- `observe_profile`
99
+
100
+
The result comes back in the same `SubtaskResult` envelope used by other isolated task paths.
101
+
102
+
## Runtime Behavior
103
+
104
+
One `acp_spawn` call does this:
105
+
106
+
1. start the configured wrapper process
107
+
2. `initialize`
108
+
3. `authenticate` if needed
109
+
4. `session/new`
110
+
5. `session/set_config_option` for advertised options
111
+
6. `session/prompt`
112
+
7. serve ACP file, permission, and terminal callbacks
113
+
8. collect the final assistant text
114
+
115
+
## Security Notes
116
+
117
+
ACP callback permissions are not the whole boundary.
118
+
119
+
The real enforcement happens in the implemented client methods:
120
+
121
+
- allowed file roots
122
+
- allowed terminal working directories
123
+
- local write and process rules
124
+
125
+
Also, the wrapper itself is still a local child process. ACP callback limits do not automatically sandbox arbitrary direct behavior inside that wrapper.
126
+
127
+
## Codex via Adapter
128
+
129
+
Current Codex support is meant to work through an ACP adapter such as `codex-acp`.
130
+
131
+
Practical checks:
132
+
133
+
1. `codex` itself should already work.
134
+
2. `mistermorph tools` should list `acp_spawn`.
135
+
3. the ACP profile should point to `codex-acp`.
136
+
137
+
See also:
138
+
139
+
- [Subagents](/guide/subagents)
140
+
- [Built-in Tools](/guide/built-in-tools)
141
+
- [Config Fields](/guide/config-reference)
+12
-2
web/vitepress/docs/guide/built-in-tools.md
+12
-2
web/vitepress/docs/guide/built-in-tools.md
···
17
17
| Group | When available | Tools |
18
18
|---|---|---|
19
19
| Static tools | Available from config alone | `read_file`, `write_file`, `bash`, `url_fetch`, `web_search`, `contacts_send` |
20
-
| Engine tools | Available when an agent engine is assembled for a run | `spawn` |
20
+
| Engine tools | Available when an agent engine is assembled for a run | `spawn`, `acp_spawn` |
21
21
| Runtime tools | Available when the LLM or required context is available | `plan_create`, `todo_update` |
22
22
| Channel-specific tools | Available when the current channel is Telegram / Slack or another concrete channel runtime | `telegram_send_voice`, `telegram_send_photo`, `telegram_send_file`, `message_react` |
23
23
···
73
73
74
74
For parameter details, result envelope fields, test prompts, and the difference from `bash.run_in_subtask=true`, see [Subagents](/guide/subagents).
75
75
76
+
### `acp_spawn`
77
+
78
+
Starts an external ACP-compatible agent through a configured profile. The parent agent still waits synchronously, but the inner work runs through ACP instead of another local Mister Morph loop.
79
+
80
+
- Key limits: can be disabled via `tools.acp_spawn.enabled`; requires a matching profile under `acp.agents`; current transport is `stdio` only.
81
+
- Current behavior: one `acp_spawn` call creates one ACP session, serves file and terminal callbacks, and returns the same `SubtaskResult` envelope shape as other isolated task paths.
82
+
83
+
For profile config, runtime behavior, and practical Codex adapter notes, see [ACP](/guide/acp).
84
+
76
85
## Runtime Tools
77
86
78
87
These tools are injected dynamically while the agent is running.
···
136
145
read_file: ...
137
146
write_file: ...
138
147
spawn: ...
148
+
acp_spawn: ...
139
149
bash: ...
140
150
url_fetch: ...
141
151
web_search: ...
···
144
154
plan_create: ...
145
155
```
146
156
147
-
Console Setup / Settings and the `/api/settings/agent` payload use the same nested shape, for example `tools.spawn.enabled`.
157
+
Console Setup / Settings and the `/api/settings/agent` payload use the same nested shape, for example `tools.spawn.enabled` and `tools.acp_spawn.enabled`.
148
158
149
159
For the full configuration, see [Config Reference](/guide/config-reference.md).
+1
web/vitepress/docs/guide/docs-map.md
+1
web/vitepress/docs/guide/docs-map.md
+39
-8
web/vitepress/docs/guide/subagents.md
+39
-8
web/vitepress/docs/guide/subagents.md
···
12
12
- A shell command is slow or noisy, and you want its output isolated from the parent loop.
13
13
- The work is still multi-step, but you want the inner execution to operate with a narrower tool set.
14
14
- You want one compact final result instead of leaking raw intermediate output back to the parent.
15
+
- The child work should run inside an external ACP-compatible agent instead of another local Mister Morph loop.
15
16
16
17
Choose the entry like this:
17
18
···
21
22
22
23
## Overview
23
24
24
-
Mistermorph currently exposes two explicit subagent entries:
25
+
Mistermorph currently exposes three isolated-task entries:
25
26
26
27
| Entry | Starts another LLM loop | Best for | Returns |
27
28
|---|---|---|---|
28
29
| `spawn` | Yes | an inner agent that still needs tools and reasoning | `SubtaskResult` JSON envelope |
30
+
| `acp_spawn` | No local inner Mister Morph loop; starts an external ACP session instead | an external ACP-compatible agent or adapter | `SubtaskResult` JSON envelope |
29
31
| `bash.run_in_subtask=true` | No | one shell command with isolated execution/output | `SubtaskResult` JSON envelope |
30
32
31
33
Shared behavior:
32
34
33
-
- Both are synchronous. The parent waits until the inner run finishes.
34
-
- Both share the same depth limit.
35
-
- Both return the same top-level envelope shape.
35
+
- All three are synchronous. The parent waits until the inner run finishes.
36
+
- All three share the same depth limit.
37
+
- All three return the same top-level envelope shape.
36
38
- Neither path sends the raw inner transcript back into the parent loop by default.
37
39
40
+
ACP-specific note:
41
+
42
+
- `acp_spawn` still creates an inner agent boundary, but that boundary is handled by an external ACP agent process rather than another local Mister Morph engine.
43
+
38
44
This feature is about isolation and result collection. It is not a background job system yet.
39
45
40
46
## Current Implementation
···
58
64
- If no usable tool remains, the call fails.
59
65
- `spawn` is never re-exposed inside the inner agent, even if listed in `tools`.
60
66
67
+
### `acp_spawn`
68
+
69
+
`acp_spawn` is also an engine-scoped tool.
70
+
71
+
Parameters:
72
+
73
+
- `agent`: required ACP profile name from `acp.agents`
74
+
- `task`: required prompt for the external ACP agent
75
+
- `cwd`: optional working-directory override
76
+
- `output_schema`: optional structured-output label
77
+
- `observe_profile`: optional observer hint
78
+
79
+
Current behavior:
80
+
81
+
- one call creates one ACP session
82
+
- the current implementation uses `stdio` transport only
83
+
- the child path can serve ACP permission, file, and terminal callbacks
84
+
- the final result is normalized into the same `SubtaskResult` envelope used by `spawn`
85
+
86
+
For profile config and transport details, see [ACP](/guide/acp).
87
+
61
88
### `bash.run_in_subtask=true`
62
89
63
90
This is the lighter isolated-execution path.
···
90
117
91
118
### Result Envelope
92
119
93
-
Both entries return JSON in this shape:
120
+
All three entries return JSON in this shape:
94
121
95
122
```json
96
123
{
···
158
185
### Config and Embedding
159
186
160
187
- `tools.spawn.enabled` controls only the explicit `spawn` tool entry.
188
+
- `tools.acp_spawn.enabled` controls only the explicit `acp_spawn` tool entry.
189
+
- ACP profiles live under `acp.agents`.
161
190
- Direct isolated runs such as `bash.run_in_subtask=true` still work even if `tools.spawn.enabled=false`.
162
-
- `integration.Config.BuiltinToolNames` can include or omit `spawn`.
163
-
- If you build an engine directly with `agent.New(...)`, `spawn` is enabled by default. Disable it with `agent.WithSpawnToolEnabled(false)`.
191
+
- `integration.Config.BuiltinToolNames` can include or omit `spawn` and `acp_spawn`.
192
+
- If you build an engine directly with `agent.New(...)`, `spawn` is enabled by default and `acp_spawn` is disabled by default. Override them with `agent.WithSpawnToolEnabled(...)`, `agent.WithACPSpawnToolEnabled(...)`, and `agent.WithACPAgents(...)`.
164
193
165
194
Example:
166
195
167
196
```go
168
197
cfg := integration.DefaultConfig()
169
-
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
198
+
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn", "acp_spawn"}
170
199
cfg.Set("tools.spawn.enabled", true)
200
+
cfg.Set("tools.acp_spawn.enabled", true)
171
201
```
172
202
173
203
See also:
174
204
175
205
- [Built-in Tools](/guide/built-in-tools)
206
+
- [ACP](/guide/acp)
176
207
- [Create Your Own AI Agent: Advanced](/guide/build-your-own-agent-advanced)
177
208
- [Config Fields](/guide/config-reference)
+139
web/vitepress/docs/ja/guide/acp.md
+139
web/vitepress/docs/ja/guide/acp.md
···
1
+
---
2
+
title: ACP
3
+
description: acp_spawn で外部 ACP agent を使う。
4
+
---
5
+
6
+
# ACP
7
+
8
+
Mister Morph は、隔離した 1 つの子タスクを外部 ACP agent に委譲できます。
9
+
10
+
現在の実装は絞っています。
11
+
12
+
- Mister Morph は ACP client であり、ACP server ではありません。
13
+
- transport は `stdio` だけです。
14
+
- `acp_spawn` 1 回につき、同期 session を 1 つ作り、prompt turn も 1 回です。
15
+
- 外部 agent プロセスは `acp.agents` から起動します。
16
+
17
+
## ACP を使う場面
18
+
19
+
子タスクを「別のローカル Mister Morph loop」ではなく、「外部 agent の実行スタック」で走らせたいときに使います。
20
+
21
+
典型例:
22
+
23
+
- ACP adapter 経由で Codex を使う
24
+
- 別の ACP 対応 coding agent を使う
25
+
- 親 loop は調停だけ行い、ファイル操作やコマンド実行は外部 agent に任せる
26
+
27
+
別のローカル Mister Morph loop で十分なら、[Subagents](/ja/guide/subagents) の `spawn` を使ってください。
28
+
29
+
## 現在サポートしているもの
30
+
31
+
- `authenticate`
32
+
- `session/new`
33
+
- `session/new` が宣言した option id に対する `session/set_config_option`
34
+
- `session/prompt`
35
+
- `session/request_permission`
36
+
- `fs/read_text_file`
37
+
- `fs/write_text_file`
38
+
- 最小の `terminal/*`
39
+
40
+
まだ未対応:
41
+
42
+
- MCP passthrough
43
+
- session 再利用
44
+
- HTTP / SSE transport
45
+
46
+
## 設定
47
+
48
+
必要なのは 2 点です。
49
+
50
+
1. 明示的なツール入口を有効にする
51
+
2. 1 つ以上の ACP profile を定義する
52
+
53
+
```yaml
54
+
tools:
55
+
acp_spawn:
56
+
enabled: true
57
+
58
+
acp:
59
+
agents:
60
+
- name: "codex"
61
+
enable: true
62
+
type: "stdio"
63
+
command: "codex-acp"
64
+
args: []
65
+
env: {}
66
+
cwd: "."
67
+
read_roots: ["."]
68
+
write_roots: ["."]
69
+
session_options:
70
+
mode: "auto"
71
+
reasoning_effort: "low"
72
+
```
73
+
74
+
補足:
75
+
76
+
- `tools.acp_spawn.enabled` が制御するのは `acp_spawn` 入口だけです。
77
+
- `session_options` はまず `session/new._meta` に渡します。
78
+
- ACP agent が config option id を宣言した場合、同名キーは `session/set_config_option` でも送ります。
79
+
80
+
## Prompt パターン
81
+
82
+
親 agent には `acp_spawn` を明示的に使わせます。
83
+
84
+
例:
85
+
86
+
```text
87
+
Only call acp_spawn. Use the codex agent. Read ./README.md and summarize it in exactly 5 Chinese sentences. Do not call spawn. Do not read the file yourself.
88
+
```
89
+
90
+
`acp_spawn` の主な引数:
91
+
92
+
- `agent`
93
+
- `task`
94
+
- `cwd`
95
+
- `output_schema`
96
+
- `observe_profile`
97
+
98
+
返り値は既存の `SubtaskResult` envelope と同じ形です。
99
+
100
+
## 実行時の流れ
101
+
102
+
1 回の `acp_spawn` は次の順です。
103
+
104
+
1. wrapper プロセスを起動
105
+
2. `initialize`
106
+
3. 必要なら `authenticate`
107
+
4. `session/new`
108
+
5. 宣言済み option に `session/set_config_option`
109
+
6. `session/prompt`
110
+
7. turn 中の file / permission / terminal callback を処理
111
+
8. 最終テキストを回収
112
+
113
+
## セキュリティ上の注意
114
+
115
+
ACP の permission request だけが境界ではありません。
116
+
117
+
実際の制限は、実装済み client メソッド側で行われます。
118
+
119
+
- 許可したファイル root
120
+
- 許可した terminal の作業ディレクトリ
121
+
- ローカルの書き込み・プロセス実行ルール
122
+
123
+
もう 1 点重要なのは、wrapper 自体もローカル子プロセスだということです。ACP callback の制限は、wrapper 自身の任意の直接動作まで自動的にサンドボックス化しません。
124
+
125
+
## Adapter 経由の Codex
126
+
127
+
現在の Codex 連携は `codex-acp` のような ACP adapter を前提にしています。
128
+
129
+
確認ポイント:
130
+
131
+
1. まず `codex` 単体で動くこと
132
+
2. `mistermorph tools` に `acp_spawn` が出ること
133
+
3. ACP profile の `command` が `codex-acp` を指していること
134
+
135
+
関連ページ:
136
+
137
+
- [Subagents](/ja/guide/subagents)
138
+
- [組み込みツール](/ja/guide/built-in-tools)
139
+
- [設定フィールド](/ja/guide/config-reference)
+12
-2
web/vitepress/docs/ja/guide/built-in-tools.md
+12
-2
web/vitepress/docs/ja/guide/built-in-tools.md
···
17
17
| 分類 | いつ使えるか | ツール |
18
18
|---|---|---|
19
19
| 静的ツール | 設定だけで利用可能 | `read_file`、`write_file`、`bash`、`url_fetch`、`web_search`、`contacts_send` |
20
-
| Engine ツール | agent engine が 1 回組み上がると利用可能 | `spawn` |
20
+
| Engine ツール | agent engine が 1 回組み上がると利用可能 | `spawn`、`acp_spawn` |
21
21
| ランタイムツール | LLM や必要な文脈が利用可能なとき | `plan_create`、`todo_update` |
22
22
| チャネル専用ツール | 現在の Channel が Telegram / Slack などの具体的 runtime のとき | `telegram_send_voice`、`telegram_send_photo`、`telegram_send_file`、`message_react` |
23
23
···
73
73
74
74
引数の詳細、返り値 envelope の各フィールド、test prompt、`bash.run_in_subtask=true` との違いは [Subagents](/ja/guide/subagents) を参照してください。
75
75
76
+
### `acp_spawn`
77
+
78
+
設定済み profile を通して外部 ACP agent を起動します。親 agent は同期で待ちますが、内側の実行は別のローカル Mister Morph loop ではなく ACP 経由です。
79
+
80
+
- 主な制約: `tools.acp_spawn.enabled` で無効化できます。対応する profile が `acp.agents` に必要です。現在の transport は `stdio` のみです。
81
+
- 現在の挙動: 1 回の `acp_spawn` は 1 つの ACP session を作り、file / terminal callback を処理し、他の分離実行と同じ `SubtaskResult` envelope を返します。
82
+
83
+
profile 設定、実行時の流れ、Codex adapter の注意点は [ACP](/ja/guide/acp) を参照してください。
84
+
76
85
## ランタイムツール
77
86
78
87
これらのツールは、Agent 実行中に動的に注入されます。
···
136
145
read_file: ...
137
146
write_file: ...
138
147
spawn: ...
148
+
acp_spawn: ...
139
149
bash: ...
140
150
url_fetch: ...
141
151
web_search: ...
···
144
154
plan_create: ...
145
155
```
146
156
147
-
Console の Setup / Settings 画面と `/api/settings/agent` の `tools` payload も、`tools.spawn.enabled` のような同じ入れ子構造を使います。
157
+
Console の Setup / Settings 画面と `/api/settings/agent` の `tools` payload も、`tools.spawn.enabled` や `tools.acp_spawn.enabled` のような同じ入れ子構造を使います。
148
158
149
159
完全な設定は [設定フィールド](/ja/guide/config-reference.md) を参照してください。
+1
web/vitepress/docs/ja/guide/docs-map.md
+1
web/vitepress/docs/ja/guide/docs-map.md
+39
-8
web/vitepress/docs/ja/guide/subagents.md
+39
-8
web/vitepress/docs/ja/guide/subagents.md
···
12
12
- shell コマンドが長く、出力も多いので、親 loop から切り離したい。
13
13
- 処理自体は複数ステップだが、内側の実行に許すツールを絞りたい。
14
14
- 中間の生出力ではなく、最後に短い結果だけを親へ返したい。
15
+
- 子タスクを別のローカル Mister Morph loop ではなく、外部 ACP agent に委譲したい。
15
16
16
17
入口の選び方は次の通りです。
17
18
···
21
22
22
23
## Overview
23
24
24
-
Mistermorph には現在、明示的な Subagent 入口が二つあります。
25
+
Mistermorph には現在、三つの隔離タスク入口があります。
25
26
26
27
| 入口 | もう一度 LLM loop を起こすか | 向いている場面 | 返り値 |
27
28
|---|---|---|---|
28
29
| `spawn` | 起こす | 内側の agent 側でもツール利用と推論が必要 | `SubtaskResult` JSON envelope |
30
+
| `acp_spawn` | ローカル内側 Mister Morph loop は起こさず、外部 ACP session を開始する | 外部 ACP agent や adapter | `SubtaskResult` JSON envelope |
29
31
| `bash.run_in_subtask=true` | 起こさない | 1 本の shell コマンドを隔離して実行したい | `SubtaskResult` JSON envelope |
30
32
31
33
共通点:
32
34
33
-
- どちらも現状は同期実行で、親は内側の実行終了まで待ちます。
34
-
- どちらも同じ深さ制限を共有します。
35
-
- どちらも同じトップレベル envelope を返します。
35
+
- いずれも現状は同期実行で、親は内側の実行終了まで待ちます。
36
+
- いずれも同じ深さ制限を共有します。
37
+
- いずれも同じトップレベル envelope を返します。
36
38
- 内側の生 transcript はデフォルトで親 loop に戻しません。
37
39
38
40
これは隔離と結果回収の仕組みであって、まだバックグラウンド job システムではありません。
39
41
42
+
ACP の補足:
43
+
44
+
- `acp_spawn` も内側の agent 境界ですが、その境界は別のローカル Mister Morph engine ではなく、外部 ACP agent プロセスが担当します。
45
+
40
46
## 現在の実装
41
47
42
48
### `spawn`
···
58
64
- 最終的に使えるツールが 1 つも残らなければ失敗します。
59
65
- `tools` に `spawn` を入れても、内側の agent には再公開されません。
60
66
67
+
### `acp_spawn`
68
+
69
+
`acp_spawn` も engine スコープのツールです。
70
+
71
+
引数:
72
+
73
+
- `agent`: 必須。`acp.agents` の profile 名
74
+
- `task`: 必須。外部 ACP agent へのプロンプト
75
+
- `cwd`: 任意。作業ディレクトリ上書き
76
+
- `output_schema`: 任意。構造化出力ラベル
77
+
- `observe_profile`: 任意。観測ヒント
78
+
79
+
現在の挙動:
80
+
81
+
- 1 回の呼び出しで 1 つの ACP session を作ります
82
+
- transport は現状 `stdio` だけです
83
+
- 子タスク中は ACP の permission / file / terminal callback を処理できます
84
+
- 最終結果は `spawn` と同じ `SubtaskResult` envelope に正規化されます
85
+
86
+
profile 設定と transport の詳細は [ACP](/ja/guide/acp) を参照してください。
87
+
61
88
### `bash.run_in_subtask=true`
62
89
63
90
こちらはより軽い分離実行経路です。
···
90
117
91
118
### 返り値 Envelope
92
119
93
-
どちらの入口も最後は次の形の JSON を返します。
120
+
三つの入口はいずれも最後は次の形の JSON を返します。
94
121
95
122
```json
96
123
{
···
158
185
### 設定と組み込み
159
186
160
187
- `tools.spawn.enabled` が制御するのは明示的な `spawn` ツール入口だけです。
188
+
- `tools.acp_spawn.enabled` が制御するのは明示的な `acp_spawn` ツール入口だけです。
189
+
- ACP profile は `acp.agents` に置きます。
161
190
- `tools.spawn.enabled=false` でも、`bash.run_in_subtask=true` のような direct path は動きます。
162
-
- `integration.Config.BuiltinToolNames` には `spawn` を含めることも外すこともできます。
163
-
- `agent.New(...)` で直接 engine を作る場合、`spawn` はデフォルトで有効です。無効化したいなら `agent.WithSpawnToolEnabled(false)` を使います。
191
+
- `integration.Config.BuiltinToolNames` には `spawn` と `acp_spawn` を含めることも外すこともできます。
192
+
- `agent.New(...)` で直接 engine を作る場合、`spawn` はデフォルトで有効、`acp_spawn` はデフォルトで無効です。必要なら `agent.WithSpawnToolEnabled(...)`、`agent.WithACPSpawnToolEnabled(...)`、`agent.WithACPAgents(...)` を使います。
164
193
165
194
例:
166
195
167
196
```go
168
197
cfg := integration.DefaultConfig()
169
-
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
198
+
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn", "acp_spawn"}
170
199
cfg.Set("tools.spawn.enabled", true)
200
+
cfg.Set("tools.acp_spawn.enabled", true)
171
201
```
172
202
173
203
あわせて読む:
174
204
175
205
- [組み込みツール](/ja/guide/built-in-tools)
206
+
- [ACP](/ja/guide/acp)
176
207
- [自分の AI Agent を作る：上級編](/ja/guide/build-your-own-agent-advanced)
177
208
- [設定フィールド](/ja/guide/config-reference)
+141
web/vitepress/docs/zh/guide/acp.md
+141
web/vitepress/docs/zh/guide/acp.md
···
1
+
---
2
+
title: ACP
3
+
description: 通过 acp_spawn 调用外部 ACP agent。
4
+
---
5
+
6
+
# ACP
7
+
8
+
Mister Morph 现在可以把一个隔离子任务委托给外部 ACP agent。
9
+
10
+
当前实现刻意收得很窄：
11
+
12
+
- Mister Morph 只做 ACP client，不做 ACP server。
13
+
- 只支持 `stdio`。
14
+
- 每次 `acp_spawn` 都是一个同步 session，只跑一轮 prompt turn。
15
+
- 外部 agent 进程来自 `acp.agents` 配置。
16
+
17
+
## 什么时候用 ACP
18
+
19
+
当子任务应该跑在“外部 agent 执行栈”里，而不是另一个本地 Mister Morph loop 里时，用 ACP。
20
+
21
+
典型场景：
22
+
23
+
- 通过 ACP 适配层调用 Codex
24
+
- 接别的 ACP 兼容 coding agent
25
+
- 父 loop 只负责调度，把文件读写和命令执行交给外部专业 agent
26
+
27
+
如果你只是想再起一个本地 Mister Morph 子 agent，用 [Subagents](/zh/guide/subagents) 里的 `spawn`。
28
+
29
+
## 当前支持
30
+
31
+
现在已经支持：
32
+
33
+
- `authenticate`
34
+
- `session/new`
35
+
- 对 `session/new` 已声明 option id 的 `session/set_config_option`
36
+
- `session/prompt`
37
+
- `session/request_permission`
38
+
- `fs/read_text_file`
39
+
- `fs/write_text_file`
40
+
- 最小 `terminal/*`
41
+
42
+
暂时还不支持：
43
+
44
+
- MCP 透传
45
+
- session 复用
46
+
- HTTP / SSE transport
47
+
48
+
## 配置
49
+
50
+
要配两件事：
51
+
52
+
1. 打开显式工具入口
53
+
2. 定义至少一个 ACP profile
54
+
55
+
```yaml
56
+
tools:
57
+
acp_spawn:
58
+
enabled: true
59
+
60
+
acp:
61
+
agents:
62
+
- name: "codex"
63
+
enable: true
64
+
type: "stdio"
65
+
command: "codex-acp"
66
+
args: []
67
+
env: {}
68
+
cwd: "."
69
+
read_roots: ["."]
70
+
write_roots: ["."]
71
+
session_options:
72
+
mode: "auto"
73
+
reasoning_effort: "low"
74
+
```
75
+
76
+
补充说明：
77
+
78
+
- `tools.acp_spawn.enabled` 只控制 `acp_spawn` 这个显式入口。
79
+
- `session_options` 会先透传到 `session/new._meta`。
80
+
- 如果 ACP agent 在 `session/new` 里声明了 config option id，同名字段还会再通过 `session/set_config_option` 发一遍。
81
+
82
+
## Prompt 写法
83
+
84
+
要在父 agent 的任务里明确要求它调用 `acp_spawn`。
85
+
86
+
例如：
87
+
88
+
```text
89
+
只允许调用 acp_spawn。agent 用 codex。读取 ./README.md，并用中文写 5 句话总结。禁止调用 spawn，禁止自己读文件。
90
+
```
91
+
92
+
`acp_spawn` 支持这些参数：
93
+
94
+
- `agent`
95
+
- `task`
96
+
- `cwd`
97
+
- `output_schema`
98
+
- `observe_profile`
99
+
100
+
返回值沿用现有的 `SubtaskResult` envelope。
101
+
102
+
## 运行时行为
103
+
104
+
一次 `acp_spawn` 调用会做这些事：
105
+
106
+
1. 启动配置里的 wrapper 进程
107
+
2. `initialize`
108
+
3. 需要时 `authenticate`
109
+
4. `session/new`
110
+
5. 对已声明选项发 `session/set_config_option`
111
+
6. `session/prompt`
112
+
7. 在 turn 中处理文件、权限和终端回调
113
+
8. 收集最终文本输出
114
+
115
+
## 安全说明
116
+
117
+
ACP 的 permission 请求不是唯一边界。
118
+
119
+
真正的限制发生在已经实现的 client 方法里：
120
+
121
+
- 允许读取和写入的路径根
122
+
- 允许的终端工作目录
123
+
- 本地写入和进程执行规则
124
+
125
+
还有一点要看清：wrapper 本身仍是本地子进程。ACP 回调层的约束，不会自动把 wrapper 自己的直接行为也沙箱化。
126
+
127
+
## 通过适配层接 Codex
128
+
129
+
当前 Codex 的用法是通过 ACP 适配层，比如 `codex-acp`。
130
+
131
+
联调前先检查：
132
+
133
+
1. `codex` 自己先能正常工作
134
+
2. `mistermorph tools` 里能看到 `acp_spawn`
135
+
3. ACP profile 的 `command` 指向 `codex-acp`
136
+
137
+
另见：
138
+
139
+
- [Subagents](/zh/guide/subagents)
140
+
- [内置工具](/zh/guide/built-in-tools)
141
+
- [配置字段](/zh/guide/config-reference)
+13
-2
web/vitepress/docs/zh/guide/built-in-tools.md
+13
-2
web/vitepress/docs/zh/guide/built-in-tools.md
···
17
17
| 分组 | 什么时候出现 | 工具 |
18
18
|---|---|---|
19
19
| 静态工具 | 仅靠配置即可创建 | `read_file`、`write_file`、`bash`、`url_fetch`、`web_search`、`contacts_send` |
20
-
| Engine 工具 | 某次 agent engine 装配完成后可用 | `spawn` |
20
+
| Engine 工具 | 某次 agent engine 装配完成后可用 | `spawn`、`acp_spawn` |
21
21
| 运行时工具 | 当 LLM 或者依赖的上下文可用时 | `plan_create`、`todo_update` |
22
22
| 通道专属工具 | 当前正在使用 Telegram / Slack 等具体 Channel | `telegram_send_voice`、`telegram_send_photo`、`telegram_send_file`、`message_react` |
23
23
···
74
74
75
75
参数细节、返回 envelope 字段、测试 prompt，以及它和 `bash.run_in_subtask=true` 的差别，见 [Subagents](/zh/guide/subagents)。
76
76
77
+
### `acp_spawn`
78
+
79
+
通过配置好的 profile 启动一个外部 ACP agent。父 agent 仍然同步等待，但内部执行走的是 ACP，会话和回调也由 ACP client 处理，而不是再起一个本地 Mister Morph loop。
80
+
81
+
关键限制：可通过 `tools.acp_spawn.enabled` 关闭；必须能在 `acp.agents` 里找到对应 profile；当前只支持 `stdio`。
82
+
83
+
当前行为：一次 `acp_spawn` 调用会创建一个 ACP session，处理文件和终端回调，并返回和其他隔离任务路径相同的 `SubtaskResult` envelope。
84
+
85
+
profile 配置、运行时行为和 Codex 适配层示例，见 [ACP](/zh/guide/acp)。
86
+
77
87
## 运行时工具
78
88
79
89
这些工具会在 Agent 运行时动态注入。
···
138
148
read_file: ...
139
149
write_file: ...
140
150
spawn: ...
151
+
acp_spawn: ...
141
152
bash: ...
142
153
url_fetch: ...
143
154
web_search: ...
···
146
157
plan_create: ...
147
158
```
148
159
149
-
Console 的 Setup / Settings 页面，以及 `/api/settings/agent` 的 `tools` payload，也使用同一套嵌套结构，例如 `tools.spawn.enabled`。
160
+
Console 的 Setup / Settings 页面，以及 `/api/settings/agent` 的 `tools` payload，也使用同一套嵌套结构，例如 `tools.spawn.enabled` 和 `tools.acp_spawn.enabled`。
150
161
151
162
完整的配置请参考 [配置字段](/zh/guide/config-reference.md)。
+1
web/vitepress/docs/zh/guide/docs-map.md
+1
web/vitepress/docs/zh/guide/docs-map.md
+38
-6
web/vitepress/docs/zh/guide/subagents.md
+38
-6
web/vitepress/docs/zh/guide/subagents.md
···
12
12
- 一条 shell 命令很慢、输出很多，想把它和父 Loop 隔开。
13
13
- 一段工作还是多步的，但依然想要用内置工具和配套的体系。
14
14
- 希望任务只返回一个结果，而不是把中间噪声都回灌给父 Loop。
15
+
- 子任务应该跑在外部 ACP agent 里，而不是另一个本地 Mister Morph loop 里。
15
16
16
17
## Overview
17
18
18
-
Mister Morph 现在对外有两个显式 Subagent 入口：
19
+
Mister Morph 现在有三条隔离任务入口：
19
20
20
21
| 入口 | 会不会使用 LLM | 更适合什么 | 返回什么 |
21
22
|---|---|---|---|
22
23
| `spawn` | 会 | 内部 subagent 还要自己调用工具和做推理 | JSON |
24
+
| `acp_spawn` | 不会起本地内层 Mister Morph loop；会启动外部 ACP session | 外部 ACP agent 或 adapter | JSON |
23
25
| `bash.run_in_subtask=true` | 不会 | 单条 shell 命令，想隔离执行和输出 | JSON |
24
26
25
27
共同点：
26
28
27
-
- 两条路径现在都是同步阻塞，父 Loop 会等内部执行结束。
28
-
- 两条路径返回同一种 JSON envelope。
29
+
- 三条路径现在都是同步阻塞，父 Loop 会等内部执行结束。
30
+
- 三条路径返回同一种 JSON envelope。
29
31
- 都不会把内部执行的原始 transcript 发给父 Loop。
30
32
33
+
ACP 补充说明：
34
+
35
+
- `acp_spawn` 也是一条内层 agent 边界，只是这个边界由外部 ACP agent 进程处理，不是本地 Mister Morph engine。
36
+
31
37
Subagent 解决隔离、收敛和结果回传的问题，不是完整的后台任务系统
32
38
33
39
## `spawn` 工具
···
47
53
- 未知工具名或父 registry 里不存在的工具名会被忽略。
48
54
- 如果没有可用工具，调用会失败。
49
55
- `tools` 会忽略 `spawn`。
56
+
57
+
## `acp_spawn` 工具
58
+
59
+
`acp_spawn` 也是 engine 级工具。
60
+
61
+
参数：
62
+
63
+
- `agent`：必填，`acp.agents` 里的 profile 名
64
+
- `task`：必填，交给外部 ACP agent 的任务
65
+
- `cwd`：可选，工作目录覆盖
66
+
- `output_schema`：可选，结构化输出标识
67
+
- `observe_profile`：可选，观察提示
68
+
69
+
当前行为：
70
+
71
+
- 一次调用创建一个 ACP session
72
+
- 当前只支持 `stdio`
73
+
- 子任务过程中会处理 ACP 的 permission、文件和终端回调
74
+
- 最终结果会归一化成和 `spawn` 相同的 `SubtaskResult` envelope
75
+
76
+
profile 配置和传输细节见 [ACP](/zh/guide/acp)。
50
77
51
78
## `bash.run_in_subtask=true`
52
79
···
141
168
## 配置
142
169
143
170
- `tools.spawn.enabled` 只控制显式 `spawn` 工具入口。
171
+
- `tools.acp_spawn.enabled` 只控制显式 `acp_spawn` 工具入口。
172
+
- ACP profile 配在 `acp.agents`。
144
173
- 即使 `tools.spawn.enabled=false`，`bash.run_in_subtask=true` 这种 direct path 仍然可以工作。
145
174
146
175
## Integration 开发
147
176
148
-
- `integration.Config.BuiltinToolNames` 可以包含 `spawn`，也可以不包含。
149
-
- 如果你直接用 `agent.New(...)` 组 engine，`spawn` 默认开启；关闭时用 `agent.WithSpawnToolEnabled(false)`。
177
+
- `integration.Config.BuiltinToolNames` 可以包含 `spawn` 和 `acp_spawn`，也可以不包含。
178
+
- 如果你直接用 `agent.New(...)` 组 engine，`spawn` 默认开启，`acp_spawn` 默认关闭；可用 `agent.WithSpawnToolEnabled(...)`、`agent.WithACPSpawnToolEnabled(...)`、`agent.WithACPAgents(...)` 覆盖。
150
179
151
180
示例：
152
181
153
182
```go
154
183
cfg := integration.DefaultConfig()
155
-
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
184
+
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn", "acp_spawn"}
156
185
cfg.Set("tools.spawn.enabled", true)
186
+
cfg.Set("tools.acp_spawn.enabled", true)
157
187
```
188
+
189
+
另见 [ACP](/zh/guide/acp)。