@enderfga/claw-orchestrator 5.1.0 → 6.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -26
- package/dist/bin/cli.js +107 -1
- package/dist/bin/cli.js.map +1 -1
- package/dist/src/acp-server.d.ts +5 -5
- package/dist/src/acp-server.js +3 -3
- package/dist/src/acp-server.js.map +1 -1
- package/dist/src/autoloop/dispatcher.d.ts +22 -0
- package/dist/src/autoloop/dispatcher.js +71 -13
- package/dist/src/autoloop/dispatcher.js.map +1 -1
- package/dist/src/autoloop/messages.d.ts +10 -0
- package/dist/src/autoloop/messages.js.map +1 -1
- package/dist/src/autoloop/runner.js +6 -0
- package/dist/src/autoloop/runner.js.map +1 -1
- package/dist/src/constants.d.ts +0 -6
- package/dist/src/constants.js +0 -6
- package/dist/src/constants.js.map +1 -1
- package/dist/src/council.d.ts +15 -0
- package/dist/src/council.js +48 -35
- package/dist/src/council.js.map +1 -1
- package/dist/src/dashboard/index.html +191 -6
- package/dist/src/embedded-server.js +132 -9
- package/dist/src/embedded-server.js.map +1 -1
- package/dist/src/fanout.d.ts +30 -1
- package/dist/src/fanout.js +32 -3
- package/dist/src/fanout.js.map +1 -1
- package/dist/src/index.js +359 -4
- package/dist/src/index.js.map +1 -1
- package/dist/src/kernel/agent-step.d.ts +59 -0
- package/dist/src/kernel/agent-step.js +100 -0
- package/dist/src/kernel/agent-step.js.map +1 -0
- package/dist/src/kernel/conditions.d.ts +11 -0
- package/dist/src/kernel/conditions.js +24 -0
- package/dist/src/kernel/conditions.js.map +1 -0
- package/dist/src/kernel/engine.d.ts +319 -0
- package/dist/src/kernel/engine.js +1047 -0
- package/dist/src/kernel/engine.js.map +1 -0
- package/dist/src/kernel/exec.d.ts +43 -0
- package/dist/src/kernel/exec.js +112 -0
- package/dist/src/kernel/exec.js.map +1 -0
- package/dist/src/kernel/file-lock.d.ts +50 -0
- package/dist/src/kernel/file-lock.js +135 -0
- package/dist/src/kernel/file-lock.js.map +1 -0
- package/dist/src/kernel/nodes/agent.d.ts +4 -0
- package/dist/src/kernel/nodes/agent.js +35 -0
- package/dist/src/kernel/nodes/agent.js.map +1 -0
- package/dist/src/kernel/nodes/autoloop.d.ts +78 -0
- package/dist/src/kernel/nodes/autoloop.js +75 -0
- package/dist/src/kernel/nodes/autoloop.js.map +1 -0
- package/dist/src/kernel/nodes/council.d.ts +12 -0
- package/dist/src/kernel/nodes/council.js +88 -0
- package/dist/src/kernel/nodes/council.js.map +1 -0
- package/dist/src/kernel/nodes/fanout.d.ts +11 -0
- package/dist/src/kernel/nodes/fanout.js +63 -0
- package/dist/src/kernel/nodes/fanout.js.map +1 -0
- package/dist/src/kernel/nodes/human-gate.d.ts +4 -0
- package/dist/src/kernel/nodes/human-gate.js +7 -0
- package/dist/src/kernel/nodes/human-gate.js.map +1 -0
- package/dist/src/kernel/nodes/index.d.ts +12 -0
- package/dist/src/kernel/nodes/index.js +21 -0
- package/dist/src/kernel/nodes/index.js.map +1 -0
- package/dist/src/kernel/nodes/router.d.ts +4 -0
- package/dist/src/kernel/nodes/router.js +12 -0
- package/dist/src/kernel/nodes/router.js.map +1 -0
- package/dist/src/kernel/nodes/subflow.d.ts +13 -0
- package/dist/src/kernel/nodes/subflow.js +38 -0
- package/dist/src/kernel/nodes/subflow.js.map +1 -0
- package/dist/src/kernel/nodes/ultraapp.d.ts +60 -0
- package/dist/src/kernel/nodes/ultraapp.js +62 -0
- package/dist/src/kernel/nodes/ultraapp.js.map +1 -0
- package/dist/src/kernel/nodes/verifier.d.ts +14 -0
- package/dist/src/kernel/nodes/verifier.js +84 -0
- package/dist/src/kernel/nodes/verifier.js.map +1 -0
- package/dist/src/kernel/projections.d.ts +42 -0
- package/dist/src/kernel/projections.js +133 -0
- package/dist/src/kernel/projections.js.map +1 -0
- package/dist/src/kernel/repo.d.ts +13 -0
- package/dist/src/kernel/repo.js +64 -0
- package/dist/src/kernel/repo.js.map +1 -0
- package/dist/src/kernel/secrets.d.ts +25 -0
- package/dist/src/kernel/secrets.js +48 -0
- package/dist/src/kernel/secrets.js.map +1 -0
- package/dist/src/kernel/store.d.ts +225 -0
- package/dist/src/kernel/store.js +838 -0
- package/dist/src/kernel/store.js.map +1 -0
- package/dist/src/kernel/templates/index.d.ts +140 -0
- package/dist/src/kernel/templates/index.js +266 -0
- package/dist/src/kernel/templates/index.js.map +1 -0
- package/dist/src/kernel/types.d.ts +326 -0
- package/dist/src/kernel/types.js +19 -0
- package/dist/src/kernel/types.js.map +1 -0
- package/dist/src/run-ledger.d.ts +57 -3
- package/dist/src/run-ledger.js +45 -2
- package/dist/src/run-ledger.js.map +1 -1
- package/dist/src/session-manager.d.ts +176 -129
- package/dist/src/session-manager.js +652 -603
- package/dist/src/session-manager.js.map +1 -1
- package/dist/src/types.d.ts +33 -3
- package/dist/src/ultraapp/build.d.ts +117 -3
- package/dist/src/ultraapp/build.js +319 -3
- package/dist/src/ultraapp/build.js.map +1 -1
- package/dist/src/ultraapp/contract.d.ts +52 -0
- package/dist/src/ultraapp/contract.js +83 -0
- package/dist/src/ultraapp/contract.js.map +1 -0
- package/dist/src/ultraapp/conventions.js +9 -2
- package/dist/src/ultraapp/conventions.js.map +1 -1
- package/dist/src/ultraapp/fix-on-failure.d.ts +21 -2
- package/dist/src/ultraapp/fix-on-failure.js +46 -62
- package/dist/src/ultraapp/fix-on-failure.js.map +1 -1
- package/dist/src/ultraapp/manager.d.ts +107 -2
- package/dist/src/ultraapp/manager.js +305 -86
- package/dist/src/ultraapp/manager.js.map +1 -1
- package/dist/src/verify/baseline.d.ts +73 -0
- package/dist/src/verify/baseline.js +186 -0
- package/dist/src/verify/baseline.js.map +1 -0
- package/dist/src/verify/contract.d.ts +116 -0
- package/dist/src/verify/contract.js +142 -0
- package/dist/src/verify/contract.js.map +1 -0
- package/dist/src/verify/evidence.d.ts +61 -0
- package/dist/src/verify/evidence.js +133 -0
- package/dist/src/verify/evidence.js.map +1 -0
- package/dist/src/verify/runner.d.ts +63 -0
- package/dist/src/verify/runner.js +317 -0
- package/dist/src/verify/runner.js.map +1 -0
- package/openclaw.plugin.json +8 -0
- package/package.json +2 -2
- package/skills/SKILL.md +120 -79
- package/skills/references/acp.md +17 -17
- package/skills/references/autoloop.md +139 -65
- package/skills/references/claude-cli-tracking.md +4 -4
- package/skills/references/cli.md +101 -59
- package/skills/references/council.md +109 -37
- package/skills/references/dashboard.md +34 -6
- package/skills/references/getting-started.md +13 -13
- package/skills/references/inbox.md +4 -4
- package/skills/references/mcp.md +39 -34
- package/skills/references/multi-engine.md +51 -47
- package/skills/references/observability.md +88 -28
- package/skills/references/openai-compat.md +39 -39
- package/skills/references/sessions.md +43 -25
- package/skills/references/tools.md +402 -309
- package/skills/references/ultra.md +45 -45
- package/skills/references/ultraapp.md +126 -50
- package/skills/references/verification.md +187 -0
- package/skills/references/workflow.md +362 -0
- package/dist/src/ultraapp/fix-on-failure-session.d.ts +0 -23
- package/dist/src/ultraapp/fix-on-failure-session.js +0 -51
- package/dist/src/ultraapp/fix-on-failure-session.js.map +0 -1
|
@@ -8,74 +8,74 @@ All tools are registered as Claw Orchestrator plugin tools. In standalone mode,
|
|
|
8
8
|
|
|
9
9
|
Start a persistent coding session with full CLI flag support.
|
|
10
10
|
|
|
11
|
-
| Parameter
|
|
12
|
-
|
|
13
|
-
| `name`
|
|
14
|
-
| `cwd`
|
|
15
|
-
| `engine`
|
|
16
|
-
| `model`
|
|
17
|
-
| `permissionMode`
|
|
18
|
-
| `sandboxMode`
|
|
19
|
-
| `effort`
|
|
20
|
-
| `allowedTools`
|
|
21
|
-
| `disallowedTools`
|
|
22
|
-
| `maxTurns`
|
|
23
|
-
| `maxBudgetUsd`
|
|
24
|
-
| `systemPrompt`
|
|
25
|
-
| `appendSystemPrompt`
|
|
26
|
-
| `agents`
|
|
27
|
-
| `agent`
|
|
28
|
-
| `bare`
|
|
29
|
-
| `worktree`
|
|
30
|
-
| `fallbackModel`
|
|
31
|
-
| `resumeSessionId`
|
|
32
|
-
| `jsonSchema`
|
|
33
|
-
| `mcpConfig`
|
|
34
|
-
| `settings`
|
|
35
|
-
| `ultracode`
|
|
36
|
-
| `noSessionPersistence`
|
|
37
|
-
| `betas`
|
|
38
|
-
| `enableAgentTeams`
|
|
39
|
-
| `enableAutoMode`
|
|
40
|
-
| `customEngine`
|
|
41
|
-
| `crossSessionInbound`
|
|
42
|
-
| `includeHookEvents`
|
|
43
|
-
| `forwardSubagentText`
|
|
44
|
-
| `permissionPromptTool`
|
|
45
|
-
| `excludeDynamicSystemPromptSections` | boolean
|
|
46
|
-
| `enablePromptCaching1H`
|
|
47
|
-
| `debug`
|
|
48
|
-
| `debugFile`
|
|
49
|
-
| `fromPr`
|
|
50
|
-
| `channels`
|
|
51
|
-
| `dangerouslyLoadDevelopmentChannels` | string \| string[]
|
|
52
|
-
| `forkSubagent`
|
|
53
|
-
| `enableToolSearch`
|
|
54
|
-
| `otelLogUserPrompts`
|
|
55
|
-
| `otelLogRawApiBodies`
|
|
56
|
-
| `bedrockServiceTier`
|
|
57
|
-
| `effort`
|
|
11
|
+
| Parameter | Type | Description |
|
|
12
|
+
| ------------------------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
13
|
+
| `name` | string | Session name (auto-generated if omitted) |
|
|
14
|
+
| `cwd` | string | Working directory |
|
|
15
|
+
| `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'grok'` \| `'opencode'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `grok` wraps xAI Grok Build and reports its own per-turn cost. `opencode` wraps sst/opencode (pass model as `provider/model`). Use `custom` with `customEngine` for any CLI. (`'gemini'` and `'cursor'` are still accepted for existing callers but are legacy — not version-tracked; use `agy` for Google and `grok` in place of Cursor.) |
|
|
16
|
+
| `model` | string | Model alias or full name |
|
|
17
|
+
| `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
|
|
18
|
+
| `sandboxMode` | `'read-only'` \| `'workspace-write'` \| `'danger-full-access'` | Sandbox policy. Codex supports all values. `read-only` is enforced on every other built-in engine too: Claude → plan mode; Antigravity → its plan mode; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`. **`grok` refuses a read-only session** rather than approximate one — its enforcement has not been adversarially verified. A `custom` engine must map it via `permissionModes`, or the session refuses to start. Persisted across session resume. |
|
|
19
|
+
| `effort` | string | `low`, `medium`, `high`, `max`, `auto` |
|
|
20
|
+
| `allowedTools` | string[] | Tools to auto-approve |
|
|
21
|
+
| `disallowedTools` | string[] | Tools to deny |
|
|
22
|
+
| `maxTurns` | number | Max agent loop turns |
|
|
23
|
+
| `maxBudgetUsd` | number | Max API spend (USD). Enforced by the runtime on every engine: once the session's cumulative cost reaches the cap, further sends are refused before the engine is spawned. See [observability.md](observability.md) for the accuracy caveat on engines that estimate token counts. |
|
|
24
|
+
| `systemPrompt` | string | Replace system prompt |
|
|
25
|
+
| `appendSystemPrompt` | string | Append to system prompt |
|
|
26
|
+
| `agents` | object | Custom sub-agents JSON |
|
|
27
|
+
| `agent` | string | Default agent to use |
|
|
28
|
+
| `bare` | boolean | Skip hooks, LSP, auto-memory, CLAUDE.md |
|
|
29
|
+
| `worktree` | string \| boolean | Run in git worktree |
|
|
30
|
+
| `fallbackModel` | string | Fallback when primary overloaded |
|
|
31
|
+
| `resumeSessionId` | string | Resume existing session by ID |
|
|
32
|
+
| `jsonSchema` | string | JSON Schema for structured output. Claude: `--json-schema` (inline). Codex: `--output-schema` (written to a temp file, requires Codex 0.132+). Other engines ignore it. |
|
|
33
|
+
| `mcpConfig` | string \| string[] | MCP server config file(s) |
|
|
34
|
+
| `settings` | string | Settings.json path or inline JSON |
|
|
35
|
+
| `ultracode` | boolean | Claude only. Enable "ultracode" / dynamic workflows — Claude plans a JS orchestration script per substantive task and fans out to subagents. Injected as the `ultracode:true` settings key (merged into `settings`), **not** a `--effort` value (the CLI rejects `--effort ultracode`). |
|
|
36
|
+
| `noSessionPersistence` | boolean | Do not save session to disk |
|
|
37
|
+
| `betas` | string \| string[] | Custom beta headers |
|
|
38
|
+
| `enableAgentTeams` | boolean | Enable experimental agent teams |
|
|
39
|
+
| `enableAutoMode` | boolean | Enable auto permission mode |
|
|
40
|
+
| `customEngine` | object | Custom engine config (required when `engine='custom'`). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-enginecustom). |
|
|
41
|
+
| `crossSessionInbound` | string | `accept` / `hold` / `refuse` — policy for peer messages from other Claude Code sessions on this machine (Claude engine). Delivered as a settings key; there is no CLI flag. Without it the CLI holds messages whose two sides run different permission modes, which is the usual orchestrated-session-to-human-terminal case |
|
|
42
|
+
| `includeHookEvents` | boolean | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events |
|
|
43
|
+
| `forwardSubagentText` | boolean | Forward subagent text and thinking into the output stream (Claude engine, CLI 2.1.211+). Without it the parent stream stays quiet while a subagent works |
|
|
44
|
+
| `permissionPromptTool` | string | MCP tool name to delegate permission prompts to (non-interactive use) |
|
|
45
|
+
| `excludeDynamicSystemPromptSections` | boolean | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true` |
|
|
46
|
+
| `enablePromptCaching1H` | boolean | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true` |
|
|
47
|
+
| `debug` | string | Debug categories to enable (comma-separated, e.g. `"api,mcp"`) |
|
|
48
|
+
| `debugFile` | string | File path to write debug output to |
|
|
49
|
+
| `fromPr` | string \| number | Resume a session linked to a GitHub PR number or URL |
|
|
50
|
+
| `channels` | string \| string[] | MCP channel subscription spec (research preview) |
|
|
51
|
+
| `dangerouslyLoadDevelopmentChannels` | string \| string[] | Development MCP channel subscriptions (research preview) |
|
|
52
|
+
| `forkSubagent` | boolean | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`) |
|
|
53
|
+
| `enableToolSearch` | boolean | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`) |
|
|
54
|
+
| `otelLogUserPrompts` | boolean | OpenTelemetry: log user prompts (sets `OTEL_LOG_USER_PROMPTS=1`) |
|
|
55
|
+
| `otelLogRawApiBodies` | boolean | OpenTelemetry: log raw API request/response bodies (sets `OTEL_LOG_RAW_API_BODIES=1`); debug only |
|
|
56
|
+
| `bedrockServiceTier` | `'default'` \| `'flex'` \| `'priority'` | AWS Bedrock service tier (sets `ANTHROPIC_BEDROCK_SERVICE_TIER`); only effective when routing through Bedrock |
|
|
57
|
+
| `effort` | `'low'` \| `'medium'` \| `'high'` \| `'xhigh'` \| `'max'` \| `'auto'` | Reasoning effort level. `xhigh` is Opus 4.7-only (between `high` and `max`); triggers `ultrathink` prefix on user messages, same as `high` and `max`. |
|
|
58
58
|
|
|
59
59
|
### `session_send`
|
|
60
60
|
|
|
61
61
|
Send a message and get the response.
|
|
62
62
|
|
|
63
|
-
| Parameter | Type
|
|
64
|
-
|
|
65
|
-
| `name`
|
|
66
|
-
| `message` | string
|
|
67
|
-
| `effort`
|
|
68
|
-
| `plan`
|
|
69
|
-
| `timeout` | number
|
|
70
|
-
| `stream`
|
|
63
|
+
| Parameter | Type | Required | Description |
|
|
64
|
+
| --------- | ------- | -------- | ---------------------------------- |
|
|
65
|
+
| `name` | string | yes | Session name |
|
|
66
|
+
| `message` | string | yes | Message to send |
|
|
67
|
+
| `effort` | string | | Override effort for this message |
|
|
68
|
+
| `plan` | boolean | | Enable plan mode |
|
|
69
|
+
| `timeout` | number | | Timeout in ms (default 300000) |
|
|
70
|
+
| `stream` | boolean | | Collect streaming chunks in result |
|
|
71
71
|
|
|
72
72
|
### `session_stop`
|
|
73
73
|
|
|
74
74
|
Graceful shutdown (SIGTERM, then SIGKILL after 3s).
|
|
75
75
|
|
|
76
|
-
| Parameter | Type
|
|
77
|
-
|
|
78
|
-
| `name`
|
|
76
|
+
| Parameter | Type | Required |
|
|
77
|
+
| --------- | ------ | -------- |
|
|
78
|
+
| `name` | string | yes |
|
|
79
79
|
|
|
80
80
|
### `session_list`
|
|
81
81
|
|
|
@@ -93,56 +93,56 @@ Dashboard view: all sessions with ready/busy/paused state, cost, context %, last
|
|
|
93
93
|
|
|
94
94
|
Detailed status: tokens, cost, context %, tool calls, uptime. (Renamed from `session_status` in v3.2 to avoid collision with OpenClaw's built-in `session_status` tool.)
|
|
95
95
|
|
|
96
|
-
| Parameter | Type
|
|
97
|
-
|
|
98
|
-
| `name`
|
|
96
|
+
| Parameter | Type | Required |
|
|
97
|
+
| --------- | ------ | -------- |
|
|
98
|
+
| `name` | string | yes |
|
|
99
99
|
|
|
100
100
|
**Returned stats fields** (selected):
|
|
101
101
|
|
|
102
|
-
| Field
|
|
103
|
-
|
|
104
|
-
| `retries`
|
|
105
|
-
| `lastRetryError` | string \| undefined | Error message from the most recent retry (if any)
|
|
102
|
+
| Field | Type | Description |
|
|
103
|
+
| ---------------- | ------------------- | ------------------------------------------------------- |
|
|
104
|
+
| `retries` | number | Number of API retries that occurred during this session |
|
|
105
|
+
| `lastRetryError` | string \| undefined | Error message from the most recent retry (if any) |
|
|
106
106
|
|
|
107
107
|
### `session_grep`
|
|
108
108
|
|
|
109
109
|
Regex search over session event history.
|
|
110
110
|
|
|
111
|
-
| Parameter | Type
|
|
112
|
-
|
|
113
|
-
| `name`
|
|
114
|
-
| `pattern` | string | yes
|
|
115
|
-
| `limit`
|
|
111
|
+
| Parameter | Type | Required | Description |
|
|
112
|
+
| --------- | ------ | -------- | ------------------------ |
|
|
113
|
+
| `name` | string | yes | Session name |
|
|
114
|
+
| `pattern` | string | yes | Regex pattern |
|
|
115
|
+
| `limit` | number | | Max results (default 50) |
|
|
116
116
|
|
|
117
117
|
### `session_compact`
|
|
118
118
|
|
|
119
119
|
Reclaim context window via `/compact`.
|
|
120
120
|
|
|
121
|
-
| Parameter | Type
|
|
122
|
-
|
|
123
|
-
| `name`
|
|
124
|
-
| `summary` | string |
|
|
121
|
+
| Parameter | Type | Required |
|
|
122
|
+
| --------- | ------ | -------- |
|
|
123
|
+
| `name` | string | yes |
|
|
124
|
+
| `summary` | string | |
|
|
125
125
|
|
|
126
126
|
### `session_update_tools`
|
|
127
127
|
|
|
128
128
|
Update tool permissions at runtime. Restarts session with `--resume`.
|
|
129
129
|
|
|
130
|
-
| Parameter
|
|
131
|
-
|
|
132
|
-
| `name`
|
|
133
|
-
| `allowedTools`
|
|
134
|
-
| `disallowedTools` | string[] | New disallowed tools
|
|
135
|
-
| `removeTools`
|
|
136
|
-
| `merge`
|
|
130
|
+
| Parameter | Type | Description |
|
|
131
|
+
| ----------------- | -------- | -------------------------------------- |
|
|
132
|
+
| `name` | string | Session name |
|
|
133
|
+
| `allowedTools` | string[] | New allowed tools (replaces or merges) |
|
|
134
|
+
| `disallowedTools` | string[] | New disallowed tools |
|
|
135
|
+
| `removeTools` | string[] | Tools to remove from lists |
|
|
136
|
+
| `merge` | boolean | Merge with existing (default: replace) |
|
|
137
137
|
|
|
138
138
|
### `session_switch_model`
|
|
139
139
|
|
|
140
140
|
Hot-swap model mid-conversation. Restarts with `--resume`.
|
|
141
141
|
|
|
142
|
-
| Parameter | Type
|
|
143
|
-
|
|
144
|
-
| `name`
|
|
145
|
-
| `model`
|
|
142
|
+
| Parameter | Type | Required |
|
|
143
|
+
| --------- | ------ | -------- |
|
|
144
|
+
| `name` | string | yes |
|
|
145
|
+
| `model` | string | yes |
|
|
146
146
|
|
|
147
147
|
---
|
|
148
148
|
|
|
@@ -152,11 +152,11 @@ Hot-swap model mid-conversation. Restarts with `--resume`.
|
|
|
152
152
|
|
|
153
153
|
Wraps `claude project purge` (CLI 2.1.126+). Deletes Claude Code state for a project — transcripts, tasks, file history, config entry. **Defaults to dry-run for safety**; pass `dry_run=false` to actually delete. The CLI's confirmation prompt is bypassed by default (`--yes`) since the wrapper has no TTY; safety is enforced upstream via the dry-run default.
|
|
154
154
|
|
|
155
|
-
| Parameter | Type
|
|
156
|
-
|
|
157
|
-
| `path`
|
|
158
|
-
| `all`
|
|
159
|
-
| `dry_run` | boolean |
|
|
155
|
+
| Parameter | Type | Required | Description |
|
|
156
|
+
| --------- | ------- | -------- | --------------------------------------------------------------------- |
|
|
157
|
+
| `path` | string | | Project path to purge. Resolved to absolute. Ignored when `all=true`. |
|
|
158
|
+
| `all` | boolean | | Purge state for every project. Mutually exclusive with `path`. |
|
|
159
|
+
| `dry_run` | boolean | | List what would be deleted without deleting. **Defaults to `true`.** |
|
|
160
160
|
|
|
161
161
|
Returns `{ ok, stdout, stderr, dryRun }`.
|
|
162
162
|
|
|
@@ -170,9 +170,9 @@ Tools targeting Claude Code's CLI. `plugin_details` is a one-shot wrapper. The `
|
|
|
170
170
|
|
|
171
171
|
Wraps `claude plugin details <name>` (CLI 2.1.139+). Prints the plugin's component inventory (commands, hooks, MCP servers, agents, skills) plus the per-session token cost of loading it.
|
|
172
172
|
|
|
173
|
-
| Parameter | Type
|
|
174
|
-
|
|
175
|
-
| `name`
|
|
173
|
+
| Parameter | Type | Required | Description |
|
|
174
|
+
| --------- | ------ | -------- | -------------------------------------------------------------------------- |
|
|
175
|
+
| `name` | string | yes | Plugin name (e.g. `superpowers` or `superpowers@claude-plugins-official`). |
|
|
176
176
|
|
|
177
177
|
Returns `{ ok, stdout, stderr }`.
|
|
178
178
|
|
|
@@ -180,11 +180,11 @@ Returns `{ ok, stdout, stderr }`.
|
|
|
180
180
|
|
|
181
181
|
Set a completion condition on a claude session (CLI 2.1.139+). Claude Code keeps working across turns until the condition is met, evaluating after each turn via Haiku. Sends `/goal <objective>` as a normal user message — the CLI's slash-command parser routes it to the goal subsystem. **Requires `engine: "claude"`.**
|
|
182
182
|
|
|
183
|
-
| Parameter
|
|
184
|
-
|
|
185
|
-
| `name`
|
|
186
|
-
| `objective` | string | yes
|
|
187
|
-
| `timeout`
|
|
183
|
+
| Parameter | Type | Required | Description |
|
|
184
|
+
| ----------- | ------ | -------- | ------------------------------------------------------- |
|
|
185
|
+
| `name` | string | yes | Session name. |
|
|
186
|
+
| `objective` | string | yes | Completion condition (e.g. "all tests in tests/ pass"). |
|
|
187
|
+
| `timeout` | number | | Timeout in ms for the resulting turn (default 300000). |
|
|
188
188
|
|
|
189
189
|
Returns the regular `session_send` turn result. Unlike Codex's `/goal`, Claude does not emit a separate goal-state notification — the only surface is the assistant's reply text. Use `claude_goal_status` to query later.
|
|
190
190
|
|
|
@@ -192,10 +192,10 @@ Returns the regular `session_send` turn result. Unlike Codex's `/goal`, Claude d
|
|
|
192
192
|
|
|
193
193
|
Send `/goal clear` to remove the active goal. Requires `engine: "claude"`.
|
|
194
194
|
|
|
195
|
-
| Parameter | Type
|
|
196
|
-
|
|
197
|
-
| `name`
|
|
198
|
-
| `timeout` | number |
|
|
195
|
+
| Parameter | Type | Required |
|
|
196
|
+
| --------- | ------ | -------- |
|
|
197
|
+
| `name` | string | yes |
|
|
198
|
+
| `timeout` | number | |
|
|
199
199
|
|
|
200
200
|
Returns the regular turn result.
|
|
201
201
|
|
|
@@ -203,10 +203,10 @@ Returns the regular turn result.
|
|
|
203
203
|
|
|
204
204
|
Send bare `/goal` to query the active goal (objective, elapsed time, turns, tokens). Requires `engine: "claude"`.
|
|
205
205
|
|
|
206
|
-
| Parameter | Type
|
|
207
|
-
|
|
208
|
-
| `name`
|
|
209
|
-
| `timeout` | number |
|
|
206
|
+
| Parameter | Type | Required |
|
|
207
|
+
| --------- | ------ | -------- |
|
|
208
|
+
| `name` | string | yes |
|
|
209
|
+
| `timeout` | number | |
|
|
210
210
|
|
|
211
211
|
Returns the regular turn result; goal info is in the assistant's reply text.
|
|
212
212
|
|
|
@@ -222,14 +222,14 @@ Tools targeting OpenAI's `codex` CLI. The `codex_resume` and `codex_review` tool
|
|
|
222
222
|
|
|
223
223
|
Resume a previously recorded Codex thread by UUID/name, or pick the most recent with `last=true`. Spawns `codex exec resume` with `--json` and parses the JSONL output into structured fields. Independent of session manager state.
|
|
224
224
|
|
|
225
|
-
| Parameter
|
|
226
|
-
|
|
227
|
-
| `session_id` | string
|
|
228
|
-
| `last`
|
|
229
|
-
| `message`
|
|
230
|
-
| `cwd`
|
|
231
|
-
| `model`
|
|
232
|
-
| `timeout`
|
|
225
|
+
| Parameter | Type | Required | Description |
|
|
226
|
+
| ------------ | ------- | -------- | ------------------------------------------------------- |
|
|
227
|
+
| `session_id` | string | | Codex thread UUID/name. Mutually exclusive with `last`. |
|
|
228
|
+
| `last` | boolean | | Resume the most recent recorded session. |
|
|
229
|
+
| `message` | string | yes | Prompt to send after resuming. |
|
|
230
|
+
| `cwd` | string | | Working directory. |
|
|
231
|
+
| `model` | string | | Override model. |
|
|
232
|
+
| `timeout` | number | | Timeout in ms (default 300000). |
|
|
233
233
|
|
|
234
234
|
> Note: `codex exec resume` does not accept `--sandbox` or `-C` (sandbox policy and cwd are inherited from the original session). The `cwd` parameter only sets the spawn's working directory so `--last`'s session-picker scopes correctly.
|
|
235
235
|
|
|
@@ -239,16 +239,16 @@ Returns `{ ok, text, threadId?, usage?, events }`.
|
|
|
239
239
|
|
|
240
240
|
Run a non-interactive Codex code review (`codex review`). Pick exactly one diff scope.
|
|
241
241
|
|
|
242
|
-
| Parameter
|
|
243
|
-
|
|
244
|
-
| `prompt`
|
|
245
|
-
| `cwd`
|
|
246
|
-
| `uncommitted` | boolean | Review staged + unstaged + untracked.
|
|
247
|
-
| `base`
|
|
248
|
-
| `commit`
|
|
249
|
-
| `title`
|
|
250
|
-
| `model`
|
|
251
|
-
| `timeout`
|
|
242
|
+
| Parameter | Type | Description |
|
|
243
|
+
| ------------- | ------- | ---------------------------------------------- |
|
|
244
|
+
| `prompt` | string | Custom review instructions. |
|
|
245
|
+
| `cwd` | string | Repository to review. |
|
|
246
|
+
| `uncommitted` | boolean | Review staged + unstaged + untracked. |
|
|
247
|
+
| `base` | string | Review changes against this base branch. |
|
|
248
|
+
| `commit` | string | Review changes introduced by this commit SHA. |
|
|
249
|
+
| `title` | string | Optional commit title shown in review summary. |
|
|
250
|
+
| `model` | string | Override model. |
|
|
251
|
+
| `timeout` | number | Timeout in ms (default 600000). |
|
|
252
252
|
|
|
253
253
|
Returns `{ ok, stdout, stderr }`.
|
|
254
254
|
|
|
@@ -256,11 +256,11 @@ Returns `{ ok, stdout, stderr }`.
|
|
|
256
256
|
|
|
257
257
|
Set a long-horizon objective. Sends `/goal <objective>` via the app-server. **Requires `engine: "codex-app"`.**
|
|
258
258
|
|
|
259
|
-
| Parameter
|
|
260
|
-
|
|
261
|
-
| `name`
|
|
262
|
-
| `objective` | string | yes
|
|
263
|
-
| `timeout`
|
|
259
|
+
| Parameter | Type | Required |
|
|
260
|
+
| ----------- | ------ | -------- |
|
|
261
|
+
| `name` | string | yes |
|
|
262
|
+
| `objective` | string | yes |
|
|
263
|
+
| `timeout` | number | |
|
|
264
264
|
|
|
265
265
|
Returns `{ ok, text, goal }` where `goal` is `{ objective, status: "active"|"paused"|"budgetLimited"|"complete", tokensUsed, timeUsedSeconds, tokenBudget?, ... }` or `null`.
|
|
266
266
|
|
|
@@ -268,9 +268,9 @@ Returns `{ ok, text, goal }` where `goal` is `{ objective, status: "active"|"pau
|
|
|
268
268
|
|
|
269
269
|
Read the cached goal state. Pure read — does not send a turn.
|
|
270
270
|
|
|
271
|
-
| Parameter | Type
|
|
272
|
-
|
|
273
|
-
| `name`
|
|
271
|
+
| Parameter | Type | Required |
|
|
272
|
+
| --------- | ------ | -------- |
|
|
273
|
+
| `name` | string | yes |
|
|
274
274
|
|
|
275
275
|
Returns `{ ok, goal }` (`null` if no goal active).
|
|
276
276
|
|
|
@@ -278,10 +278,10 @@ Returns `{ ok, goal }` (`null` if no goal active).
|
|
|
278
278
|
|
|
279
279
|
Send `/goal pause`, `/goal resume`, or `/goal clear` respectively. Requires `engine: "codex-app"`.
|
|
280
280
|
|
|
281
|
-
| Parameter | Type
|
|
282
|
-
|
|
283
|
-
| `name`
|
|
284
|
-
| `timeout` | number |
|
|
281
|
+
| Parameter | Type | Required |
|
|
282
|
+
| --------- | ------ | -------- |
|
|
283
|
+
| `name` | string | yes |
|
|
284
|
+
| `timeout` | number | |
|
|
285
285
|
|
|
286
286
|
Returns `{ ok, text, goal }`.
|
|
287
287
|
|
|
@@ -291,14 +291,14 @@ Returns `{ ok, text, goal }`.
|
|
|
291
291
|
|
|
292
292
|
Codex app-server v2 RPCs (require `engine: "codex-app"`). Method names + param shapes verified against `codex app-server generate-json-schema` (Codex 0.137).
|
|
293
293
|
|
|
294
|
-
| Tool
|
|
295
|
-
|
|
296
|
-
| `codex_interrupt` | `turn/interrupt`
|
|
297
|
-
| `codex_steer`
|
|
298
|
-
| `codex_fork`
|
|
299
|
-
| `codex_rollback`
|
|
300
|
-
| `codex_models`
|
|
301
|
-
| `codex_threads`
|
|
294
|
+
| Tool | RPC | Params | Returns |
|
|
295
|
+
| ----------------- | ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
296
|
+
| `codex_interrupt` | `turn/interrupt` | `name` | `{ ok, interrupted }` — cancels the in-flight turn (no-op if idle) |
|
|
297
|
+
| `codex_steer` | `turn/steer` | `name`, `message` | `{ ok, steered, turnId? , text? }` — adds input to the in-flight turn; falls back to a normal turn when idle |
|
|
298
|
+
| `codex_fork` | `thread/fork` | `name` | `{ ok, threadId }` — branches the thread; returns the forked id |
|
|
299
|
+
| `codex_rollback` | `thread/rollback` | `name`, `numTurns` | `{ ok, numTurns }` — drops the last N turns |
|
|
300
|
+
| `codex_models` | `model/list` | `name` | `{ ok, models }` — incl. each model's `supportedReasoningEfforts` |
|
|
301
|
+
| `codex_threads` | `thread/list` | `name`, `searchTerm?`, `cwd?`, `archived?`, `cursor?`, `limit?` | `{ ok, data, nextCursor }` — list threads with filters + pagination |
|
|
302
302
|
|
|
303
303
|
To **resume** a codex-app thread, start a session with `engine: "codex-app"` and
|
|
304
304
|
`resumeSessionId: "<threadId>"` — it loads the existing thread via `thread/resume` instead of
|
|
@@ -312,10 +312,10 @@ opening a fresh one.
|
|
|
312
312
|
|
|
313
313
|
Wraps `claude agents --json` — lists Claude Code background agent sessions (state/model/title/progress). One-shot spawn, not tied to a managed session. (`claude continue/respawn/stop/logs` do not exist as headless subcommands; use `resumeSessionId` on `session_start` to resume.)
|
|
314
314
|
|
|
315
|
-
| Parameter | Type
|
|
316
|
-
|
|
317
|
-
| `all`
|
|
318
|
-
| `cwd`
|
|
315
|
+
| Parameter | Type | Description |
|
|
316
|
+
| --------- | ------- | --------------------------------------------------------- |
|
|
317
|
+
| `all` | boolean | Include completed sessions (`--all`). |
|
|
318
|
+
| `cwd` | string | Scope to sessions started under this directory (`--cwd`). |
|
|
319
319
|
|
|
320
320
|
Returns `{ ok, agents }`.
|
|
321
321
|
|
|
@@ -323,20 +323,20 @@ Returns `{ ok, agents }`.
|
|
|
323
323
|
|
|
324
324
|
## Fan-out (3)
|
|
325
325
|
|
|
326
|
-
Run one task across N engine/model agents **in parallel** and collect their answers, with an optional synthesis pass. Cross-engine best-of-N / diverse-perspective primitive — no rounds, votes, or git worktrees. For isolated parallel
|
|
326
|
+
Run one task across N engine/model agents **in parallel** and collect their answers, with an optional synthesis pass. Cross-engine best-of-N / diverse-perspective primitive — no rounds, votes, or git worktrees. For isolated parallel _editing_, use Council.
|
|
327
327
|
|
|
328
328
|
### `fanout_start`
|
|
329
329
|
|
|
330
|
-
| Parameter
|
|
331
|
-
|
|
332
|
-
| `task`
|
|
333
|
-
| `projectDir`
|
|
334
|
-
| `agents`
|
|
335
|
-
| `synthesize`
|
|
336
|
-
| `synthesisModel` / `synthesisEngine` | string
|
|
337
|
-
| `agentTimeoutMs`
|
|
338
|
-
| `maxTurnsPerAgent`
|
|
339
|
-
| `maxBudgetUsd`
|
|
330
|
+
| Parameter | Type | Required | Description |
|
|
331
|
+
| ------------------------------------ | ------- | -------- | -------------------------------------------------------------------------------------- |
|
|
332
|
+
| `task` | string | yes | Shared prompt sent to every agent (unless an agent overrides via its own `prompt`). |
|
|
333
|
+
| `projectDir` | string | yes | Working directory all agents run in. |
|
|
334
|
+
| `agents` | array | yes | Specs: `{ name, engine?, model?, prompt?, baseUrl?, permissionMode?, customEngine? }`. |
|
|
335
|
+
| `synthesize` | boolean | | Run a final synthesis pass over the successful results (needs ≥2). |
|
|
336
|
+
| `synthesisModel` / `synthesisEngine` | string | | Model/engine for the synthesis pass (default engine `claude`). |
|
|
337
|
+
| `agentTimeoutMs` | number | | Per-agent timeout (default 600000). |
|
|
338
|
+
| `maxTurnsPerAgent` | number | | Max agent loop turns (default 30). |
|
|
339
|
+
| `maxBudgetUsd` | number | | Per-agent spend cap. |
|
|
340
340
|
|
|
341
341
|
Runs in the background; returns `{ ok, id, status, ... }`. Poll with `fanout_status`.
|
|
342
342
|
|
|
@@ -356,27 +356,27 @@ Abort a running fan-out by `id` (already-started agents finish; synthesis is ski
|
|
|
356
356
|
|
|
357
357
|
List agent definitions from `.claude/agents/` (project + global). (Renamed from `agents_list` in v3.2 to avoid collision with OpenClaw's built-in `agents_list` tool.)
|
|
358
358
|
|
|
359
|
-
| Parameter | Type
|
|
360
|
-
|
|
361
|
-
| `cwd`
|
|
359
|
+
| Parameter | Type |
|
|
360
|
+
| --------- | ------ |
|
|
361
|
+
| `cwd` | string |
|
|
362
362
|
|
|
363
363
|
### `team_list`
|
|
364
364
|
|
|
365
365
|
List teammates in an agent team session.
|
|
366
366
|
|
|
367
|
-
| Parameter | Type
|
|
368
|
-
|
|
369
|
-
| `name`
|
|
367
|
+
| Parameter | Type | Required |
|
|
368
|
+
| --------- | ------ | -------- |
|
|
369
|
+
| `name` | string | yes |
|
|
370
370
|
|
|
371
371
|
### `team_send`
|
|
372
372
|
|
|
373
373
|
Send message to a specific teammate.
|
|
374
374
|
|
|
375
|
-
| Parameter
|
|
376
|
-
|
|
377
|
-
| `name`
|
|
378
|
-
| `teammate` | string | yes
|
|
379
|
-
| `message`
|
|
375
|
+
| Parameter | Type | Required |
|
|
376
|
+
| ---------- | ------ | -------- |
|
|
377
|
+
| `name` | string | yes |
|
|
378
|
+
| `teammate` | string | yes |
|
|
379
|
+
| `message` | string | yes |
|
|
380
380
|
|
|
381
381
|
---
|
|
382
382
|
|
|
@@ -386,49 +386,49 @@ Send message to a specific teammate.
|
|
|
386
386
|
|
|
387
387
|
Start a multi-agent council. Runs in background, returns session ID immediately.
|
|
388
388
|
|
|
389
|
-
| Parameter
|
|
390
|
-
|
|
391
|
-
| `task`
|
|
392
|
-
| `projectDir`
|
|
393
|
-
| `agents`
|
|
394
|
-
| `maxRounds`
|
|
395
|
-
| `agentTimeoutMs`
|
|
396
|
-
| `maxTurnsPerAgent`
|
|
397
|
-
| `maxBudgetUsd`
|
|
398
|
-
| `defaultPermissionMode` | string
|
|
389
|
+
| Parameter | Type | Required | Description |
|
|
390
|
+
| ----------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
391
|
+
| `task` | string | yes | Task description |
|
|
392
|
+
| `projectDir` | string | yes | Working directory |
|
|
393
|
+
| `agents` | AgentPersona[] | | Agent list (defaults to 3-agent team) |
|
|
394
|
+
| `maxRounds` | number | | Max rounds (default 15) |
|
|
395
|
+
| `agentTimeoutMs` | number | | Per-agent timeout (default 1800000) |
|
|
396
|
+
| `maxTurnsPerAgent` | number | | Max tool turns per agent (default 30) |
|
|
397
|
+
| `maxBudgetUsd` | number | | Max API spend per agent |
|
|
398
|
+
| `defaultPermissionMode` | string | | Default permission mode for agents (`acceptEdits`, `bypassPermissions`, etc.). Overridden by agent-level `permissionMode`. Default: `bypassPermissions` |
|
|
399
399
|
|
|
400
400
|
### `council_status`
|
|
401
401
|
|
|
402
402
|
Get status of a running or recently completed council.
|
|
403
403
|
|
|
404
|
-
| Parameter | Type
|
|
405
|
-
|
|
406
|
-
| `id`
|
|
404
|
+
| Parameter | Type | Required |
|
|
405
|
+
| --------- | ------ | -------- |
|
|
406
|
+
| `id` | string | yes |
|
|
407
407
|
|
|
408
408
|
### `council_abort`
|
|
409
409
|
|
|
410
410
|
Abort a running council, stopping all agent sessions.
|
|
411
411
|
|
|
412
|
-
| Parameter | Type
|
|
413
|
-
|
|
414
|
-
| `id`
|
|
412
|
+
| Parameter | Type | Required |
|
|
413
|
+
| --------- | ------ | -------- |
|
|
414
|
+
| `id` | string | yes |
|
|
415
415
|
|
|
416
416
|
### `council_inject`
|
|
417
417
|
|
|
418
418
|
Inject a user message into the next round of a running council.
|
|
419
419
|
|
|
420
|
-
| Parameter | Type
|
|
421
|
-
|
|
422
|
-
| `id`
|
|
423
|
-
| `message` | string | yes
|
|
420
|
+
| Parameter | Type | Required |
|
|
421
|
+
| --------- | ------ | -------- |
|
|
422
|
+
| `id` | string | yes |
|
|
423
|
+
| `message` | string | yes |
|
|
424
424
|
|
|
425
425
|
### `council_review`
|
|
426
426
|
|
|
427
427
|
Review a completed council session. Returns a structured report of all changed files, branches, worktrees, plan.md status, review files, and agent summaries. Does not modify any state.
|
|
428
428
|
|
|
429
|
-
| Parameter | Type
|
|
430
|
-
|
|
431
|
-
| `id`
|
|
429
|
+
| Parameter | Type | Required |
|
|
430
|
+
| --------- | ------ | -------- |
|
|
431
|
+
| `id` | string | yes |
|
|
432
432
|
|
|
433
433
|
**Returns**: `CouncilReviewResult` with `changedFiles`, `branches`, `worktrees`, `reviews`, `planContent`, and `agentSummaries`.
|
|
434
434
|
|
|
@@ -436,9 +436,9 @@ Review a completed council session. Returns a structured report of all changed f
|
|
|
436
436
|
|
|
437
437
|
Accept and finalize council work. Cleans up all council scaffolding: removes worktrees, deletes `council/*` branches, removes `plan.md` and `reviews/` directory.
|
|
438
438
|
|
|
439
|
-
| Parameter | Type
|
|
440
|
-
|
|
441
|
-
| `id`
|
|
439
|
+
| Parameter | Type | Required |
|
|
440
|
+
| --------- | ------ | -------- |
|
|
441
|
+
| `id` | string | yes |
|
|
442
442
|
|
|
443
443
|
**Returns**: `CouncilAcceptResult` with `branchesDeleted`, `worktreesRemoved`, `planDeleted`, `reviewsDeleted`.
|
|
444
444
|
|
|
@@ -446,10 +446,10 @@ Accept and finalize council work. Cleans up all council scaffolding: removes wor
|
|
|
446
446
|
|
|
447
447
|
Reject council work and provide feedback. Rewrites `plan.md` with rejection feedback and commits it. Does NOT delete any worktrees or branches — the council can be restarted to retry.
|
|
448
448
|
|
|
449
|
-
| Parameter
|
|
450
|
-
|
|
451
|
-
| `id`
|
|
452
|
-
| `feedback` | string | yes
|
|
449
|
+
| Parameter | Type | Required | Description |
|
|
450
|
+
| ---------- | ------ | -------- | ------------------------------------------- |
|
|
451
|
+
| `id` | string | yes | Council session ID |
|
|
452
|
+
| `feedback` | string | yes | Detailed feedback on what needs to be fixed |
|
|
453
453
|
|
|
454
454
|
**Returns**: `CouncilRejectResult` with `planRewritten` and `feedback`.
|
|
455
455
|
|
|
@@ -461,29 +461,29 @@ Reject council work and provide feedback. Rewrites `plan.md` with rejection feed
|
|
|
461
461
|
|
|
462
462
|
Send a cross-session message. Delivered immediately if target is idle, queued if busy.
|
|
463
463
|
|
|
464
|
-
| Parameter | Type
|
|
465
|
-
|
|
466
|
-
| `from`
|
|
467
|
-
| `to`
|
|
468
|
-
| `message` | string | yes
|
|
469
|
-
| `summary` | string |
|
|
464
|
+
| Parameter | Type | Required | Description |
|
|
465
|
+
| --------- | ------ | -------- | ------------------------------------------- |
|
|
466
|
+
| `from` | string | yes | Sender session name |
|
|
467
|
+
| `to` | string | yes | Target session name, or `"*"` for broadcast |
|
|
468
|
+
| `message` | string | yes | Message text |
|
|
469
|
+
| `summary` | string | | Short preview (5-10 words) |
|
|
470
470
|
|
|
471
471
|
### `session_inbox`
|
|
472
472
|
|
|
473
473
|
Read inbox messages for a session.
|
|
474
474
|
|
|
475
|
-
| Parameter
|
|
476
|
-
|
|
477
|
-
| `name`
|
|
478
|
-
| `unreadOnly` | boolean |
|
|
475
|
+
| Parameter | Type | Required | Description |
|
|
476
|
+
| ------------ | ------- | -------- | -------------------------- |
|
|
477
|
+
| `name` | string | yes | Session name |
|
|
478
|
+
| `unreadOnly` | boolean | | Only unread (default true) |
|
|
479
479
|
|
|
480
480
|
### `session_deliver_inbox`
|
|
481
481
|
|
|
482
482
|
Deliver all queued inbox messages to an idle session.
|
|
483
483
|
|
|
484
|
-
| Parameter | Type
|
|
485
|
-
|
|
486
|
-
| `name`
|
|
484
|
+
| Parameter | Type | Required |
|
|
485
|
+
| --------- | ------ | -------- |
|
|
486
|
+
| `name` | string | yes |
|
|
487
487
|
|
|
488
488
|
---
|
|
489
489
|
|
|
@@ -493,20 +493,20 @@ Deliver all queued inbox messages to an idle session.
|
|
|
493
493
|
|
|
494
494
|
Start a dedicated Opus planning session (up to 30 min). Runs in background.
|
|
495
495
|
|
|
496
|
-
| Parameter | Type
|
|
497
|
-
|
|
498
|
-
| `task`
|
|
499
|
-
| `cwd`
|
|
500
|
-
| `model`
|
|
501
|
-
| `timeout` | number |
|
|
496
|
+
| Parameter | Type | Required | Description |
|
|
497
|
+
| --------- | ------ | -------- | ---------------------------- |
|
|
498
|
+
| `task` | string | yes | What to plan |
|
|
499
|
+
| `cwd` | string | | Project directory |
|
|
500
|
+
| `model` | string | | Model (default: opus) |
|
|
501
|
+
| `timeout` | number | | Timeout ms (default 1800000) |
|
|
502
502
|
|
|
503
503
|
### `ultraplan_status`
|
|
504
504
|
|
|
505
505
|
Get status and plan text when completed.
|
|
506
506
|
|
|
507
|
-
| Parameter | Type
|
|
508
|
-
|
|
509
|
-
| `id`
|
|
507
|
+
| Parameter | Type | Required |
|
|
508
|
+
| --------- | ------ | -------- |
|
|
509
|
+
| `id` | string | yes |
|
|
510
510
|
|
|
511
511
|
---
|
|
512
512
|
|
|
@@ -516,21 +516,21 @@ Get status and plan text when completed.
|
|
|
516
516
|
|
|
517
517
|
Launch a fleet of bug-hunting agents (1-20) reviewing code from different angles.
|
|
518
518
|
|
|
519
|
-
| Parameter
|
|
520
|
-
|
|
521
|
-
| `cwd`
|
|
522
|
-
| `agentCount`
|
|
523
|
-
| `maxDurationMinutes` | number |
|
|
524
|
-
| `model`
|
|
525
|
-
| `focus`
|
|
519
|
+
| Parameter | Type | Required | Description |
|
|
520
|
+
| -------------------- | ------ | -------- | ------------------------------- |
|
|
521
|
+
| `cwd` | string | yes | Project directory |
|
|
522
|
+
| `agentCount` | number | | Agents (1-20, default 5) |
|
|
523
|
+
| `maxDurationMinutes` | number | | Duration (5-25 min, default 10) |
|
|
524
|
+
| `model` | string | | Model for reviewers |
|
|
525
|
+
| `focus` | string | | Review focus area |
|
|
526
526
|
|
|
527
527
|
### `ultrareview_status`
|
|
528
528
|
|
|
529
529
|
Get status and findings when completed.
|
|
530
530
|
|
|
531
|
-
| Parameter | Type
|
|
532
|
-
|
|
533
|
-
| `id`
|
|
531
|
+
| Parameter | Type | Required |
|
|
532
|
+
| --------- | ------ | -------- |
|
|
533
|
+
| `id` | string | yes |
|
|
534
534
|
|
|
535
535
|
---
|
|
536
536
|
|
|
@@ -542,20 +542,20 @@ Three-agent autonomous iteration loop (Planner / Coder / Reviewer) over a git wo
|
|
|
542
542
|
|
|
543
543
|
Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start only after the Planner receives plan approval and emits `spawn_subagents`.
|
|
544
544
|
|
|
545
|
-
| Parameter
|
|
546
|
-
|
|
547
|
-
| `run_id`
|
|
548
|
-
| `workspace`
|
|
549
|
-
| `planner_engine`
|
|
550
|
-
| `planner_model`
|
|
551
|
-
| `planner_custom_engine`
|
|
552
|
-
| `coder_engine`
|
|
553
|
-
| `coder_model`
|
|
554
|
-
| `coder_custom_engine`
|
|
555
|
-
| `reviewer_engine`
|
|
556
|
-
| `reviewer_model`
|
|
557
|
-
| `reviewer_custom_engine` | object
|
|
558
|
-
| `send_timeout_ms`
|
|
545
|
+
| Parameter | Type | Required | Description |
|
|
546
|
+
| ------------------------ | ---------- | -------- | ------------------------------------------------------------------------------------------------ |
|
|
547
|
+
| `run_id` | string | yes | Stable run identifier |
|
|
548
|
+
| `workspace` | string | yes | Git workspace path |
|
|
549
|
+
| `planner_engine` | EngineType | | Planner engine (default `claude`) |
|
|
550
|
+
| `planner_model` | string | | Planner model (Claude default `opus`; other engines use their own default when omitted) |
|
|
551
|
+
| `planner_custom_engine` | object | | Trusted `CustomEngineConfig` when Planner engine is `custom`. **Local callers only** — see below |
|
|
552
|
+
| `coder_engine` | EngineType | | Default Coder engine (default `claude`) |
|
|
553
|
+
| `coder_model` | string | | Default Coder model (Claude default `sonnet`) |
|
|
554
|
+
| `coder_custom_engine` | object | | Trusted config when Coder may use `custom`. **Local callers only** |
|
|
555
|
+
| `reviewer_engine` | EngineType | | Default Reviewer engine (default `claude`) |
|
|
556
|
+
| `reviewer_model` | string | | Default Reviewer model (Claude default `sonnet`) |
|
|
557
|
+
| `reviewer_custom_engine` | object | | Trusted config when Reviewer may use `custom`. **Local callers only** |
|
|
558
|
+
| `send_timeout_ms` | number | | Per-message timeout (default 600000) |
|
|
559
559
|
|
|
560
560
|
> **Custom engines are local-only.** A `CustomEngineConfig` names an executable to
|
|
561
561
|
> spawn plus its argv and env, so it may only be supplied by a caller that already
|
|
@@ -564,6 +564,16 @@ Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start o
|
|
|
564
564
|
> body field with a 400 — the embedded server is often reverse-tunnelled and its
|
|
565
565
|
> token is a monitoring credential, not permission to choose what binary runs.
|
|
566
566
|
> Built-in engines are fully selectable over HTTP.
|
|
567
|
+
>
|
|
568
|
+
> **Resuming one is done by reference.** Refusing the config over HTTP left a real
|
|
569
|
+
> gap: a custom-engine run that crashed could not be brought back by any remote
|
|
570
|
+
> caller, because the material it needed had nowhere to come from. So a remote
|
|
571
|
+
> resume names the secret instead of carrying it — `plannerCustomEngineRef` and
|
|
572
|
+
> friends on `POST /autoloop/<id>/resume`, `agentCustomEngineRefs` on
|
|
573
|
+
> `workflow_resume` — and the orchestrator resolves the name against its own
|
|
574
|
+
> `CLAWO_CUSTOM_ENGINE_<NAME>` environment. `GET /autoloop/<id>/resume-requirements`
|
|
575
|
+
> says which roles need one. The name is not sensitive, the value never leaves the
|
|
576
|
+
> host, and an unknown name fails loudly rather than starting without credentials.
|
|
567
577
|
|
|
568
578
|
Custom configs are not persisted or accepted from Planner output. See [`multi-engine.md`](./multi-engine.md) for their shape.
|
|
569
579
|
|
|
@@ -571,18 +581,18 @@ Custom configs are not persisted or accepted from Planner output. See [`multi-en
|
|
|
571
581
|
|
|
572
582
|
Send a message into the Planner conversation.
|
|
573
583
|
|
|
574
|
-
| Parameter | Type
|
|
575
|
-
|
|
576
|
-
| `run_id`
|
|
577
|
-
| `text`
|
|
584
|
+
| Parameter | Type | Required |
|
|
585
|
+
| --------- | ------ | -------- |
|
|
586
|
+
| `run_id` | string | yes |
|
|
587
|
+
| `text` | string | yes |
|
|
578
588
|
|
|
579
589
|
### `autoloop_status`
|
|
580
590
|
|
|
581
591
|
Get the current state and push log.
|
|
582
592
|
|
|
583
|
-
| Parameter | Type
|
|
584
|
-
|
|
585
|
-
| `run_id`
|
|
593
|
+
| Parameter | Type | Required |
|
|
594
|
+
| --------- | ------ | -------- |
|
|
595
|
+
| `run_id` | string | yes |
|
|
586
596
|
|
|
587
597
|
### `autoloop_list`
|
|
588
598
|
|
|
@@ -594,21 +604,21 @@ List active Autoloop runs in this manager process.
|
|
|
594
604
|
|
|
595
605
|
Reset one role session while retaining the role's current engine/model selection.
|
|
596
606
|
|
|
597
|
-
| Parameter
|
|
598
|
-
|
|
599
|
-
| `run_id`
|
|
600
|
-
| `agent`
|
|
601
|
-
| `force`
|
|
602
|
-
| `eager_restart` | boolean
|
|
607
|
+
| Parameter | Type | Required | Description |
|
|
608
|
+
| --------------- | ---------------------------------------- | -------- | --------------------------------------------- |
|
|
609
|
+
| `run_id` | string | yes | Run id |
|
|
610
|
+
| `agent` | `'planner'` \| `'coder'` \| `'reviewer'` | yes | Role to reset; Planner requires `force: true` |
|
|
611
|
+
| `force` | boolean | | Allow Planner reset |
|
|
612
|
+
| `eager_restart` | boolean | | Start the replacement session immediately |
|
|
603
613
|
|
|
604
614
|
### `autoloop_stop`
|
|
605
615
|
|
|
606
616
|
Terminate the run and stop all role sessions.
|
|
607
617
|
|
|
608
|
-
| Parameter | Type
|
|
609
|
-
|
|
610
|
-
| `run_id`
|
|
611
|
-
| `reason`
|
|
618
|
+
| Parameter | Type | Required |
|
|
619
|
+
| --------- | ------ | -------- |
|
|
620
|
+
| `run_id` | string | yes |
|
|
621
|
+
| `reason` | string | |
|
|
612
622
|
|
|
613
623
|
---
|
|
614
624
|
|
|
@@ -626,109 +636,192 @@ List all ultraapp runs.
|
|
|
626
636
|
|
|
627
637
|
Full snapshot of a run: spec + chat + state.
|
|
628
638
|
|
|
629
|
-
| Parameter | Type
|
|
630
|
-
|
|
631
|
-
| `id`
|
|
639
|
+
| Parameter | Type | Required |
|
|
640
|
+
| --------- | ------ | -------- |
|
|
641
|
+
| `id` | string | yes |
|
|
632
642
|
|
|
633
643
|
### `ultraapp_status`
|
|
634
644
|
|
|
635
645
|
Lightweight status (mode + timestamps).
|
|
636
646
|
|
|
637
|
-
| Parameter | Type
|
|
638
|
-
|
|
639
|
-
| `id`
|
|
647
|
+
| Parameter | Type | Required |
|
|
648
|
+
| --------- | ------ | -------- |
|
|
649
|
+
| `id` | string | yes |
|
|
640
650
|
|
|
641
651
|
### `ultraapp_new`
|
|
642
652
|
|
|
643
653
|
Create a fresh run. Optionally seeds the interview with the user's first message.
|
|
644
654
|
|
|
645
|
-
| Parameter
|
|
646
|
-
|
|
647
|
-
| `firstMessage` | string |
|
|
655
|
+
| Parameter | Type | Required | Description |
|
|
656
|
+
| -------------- | ------ | -------- | ----------------------------------------------------------------------------- |
|
|
657
|
+
| `firstMessage` | string | | Free-form opening line; the interview Opus reads it before its first question |
|
|
648
658
|
|
|
649
659
|
### `ultraapp_answer`
|
|
650
660
|
|
|
651
661
|
Submit an answer to the current interview question.
|
|
652
662
|
|
|
653
|
-
| Parameter
|
|
654
|
-
|
|
655
|
-
| `id`
|
|
656
|
-
| `value`
|
|
657
|
-
| `freeform` | string |
|
|
663
|
+
| Parameter | Type | Required | Description |
|
|
664
|
+
| ---------- | ------ | -------- | -------------------------------------------------------------------- |
|
|
665
|
+
| `id` | string | yes | Run id |
|
|
666
|
+
| `value` | string | yes | One of the question's `options[].value`, or `''` when using freeform |
|
|
667
|
+
| `freeform` | string | | Free-form text when none of the options fit |
|
|
658
668
|
|
|
659
669
|
### `ultraapp_add_file`
|
|
660
670
|
|
|
661
671
|
Upload a sample file to `examples/` (the interview engine will `extract_metadata` it).
|
|
662
672
|
|
|
663
|
-
| Parameter | Type
|
|
664
|
-
|
|
665
|
-
| `id`
|
|
666
|
-
| `path`
|
|
667
|
-
| `content` | string \| Buffer | yes
|
|
673
|
+
| Parameter | Type | Required |
|
|
674
|
+
| --------- | ---------------- | -------- |
|
|
675
|
+
| `id` | string | yes |
|
|
676
|
+
| `path` | string | yes |
|
|
677
|
+
| `content` | string \| Buffer | yes |
|
|
668
678
|
|
|
669
679
|
### `ultraapp_spec_edit`
|
|
670
680
|
|
|
671
681
|
Apply RFC 6902 JSON Patch ops to the AppSpec mid-interview.
|
|
672
682
|
|
|
673
|
-
| Parameter | Type
|
|
674
|
-
|
|
675
|
-
| `id`
|
|
676
|
-
| `patch`
|
|
683
|
+
| Parameter | Type | Required |
|
|
684
|
+
| --------- | -------- | -------- |
|
|
685
|
+
| `id` | string | yes |
|
|
686
|
+
| `patch` | object[] | yes |
|
|
677
687
|
|
|
678
688
|
### `ultraapp_build_start`
|
|
679
689
|
|
|
680
690
|
Validate the spec strictly (shape + cross-refs + DAG) and enqueue the build. Council picks it up FIFO.
|
|
681
691
|
|
|
682
|
-
| Parameter | Type
|
|
683
|
-
|
|
684
|
-
| `id`
|
|
692
|
+
| Parameter | Type | Required |
|
|
693
|
+
| --------- | ------ | -------- |
|
|
694
|
+
| `id` | string | yes |
|
|
685
695
|
|
|
686
696
|
### `ultraapp_build_cancel`
|
|
687
697
|
|
|
688
698
|
Abort an active build. Council sessions are stopped and the worktrees are left as-is for inspection.
|
|
689
699
|
|
|
690
|
-
| Parameter | Type
|
|
691
|
-
|
|
692
|
-
| `id`
|
|
700
|
+
| Parameter | Type | Required |
|
|
701
|
+
| --------- | ------ | -------- |
|
|
702
|
+
| `id` | string | yes |
|
|
693
703
|
|
|
694
704
|
### `ultraapp_feedback`
|
|
695
705
|
|
|
696
706
|
Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spec-delta` (focused interview + auto-rerun), or `structural` (suggest fresh run).
|
|
697
707
|
|
|
698
|
-
| Parameter | Type
|
|
699
|
-
|
|
700
|
-
| `id`
|
|
701
|
-
| `text`
|
|
708
|
+
| Parameter | Type | Required | Description |
|
|
709
|
+
| --------- | ------ | -------- | ----------------------- |
|
|
710
|
+
| `id` | string | yes | Run id |
|
|
711
|
+
| `text` | string | yes | The feedback (1+ chars) |
|
|
702
712
|
|
|
703
713
|
### `ultraapp_promote_version`
|
|
704
714
|
|
|
705
715
|
Atomically swap the deployed version. Stops the current container/process, starts the target's, updates the router map.
|
|
706
716
|
|
|
707
|
-
| Parameter | Type
|
|
708
|
-
|
|
709
|
-
| `id`
|
|
710
|
-
| `version` | string | yes
|
|
717
|
+
| Parameter | Type | Required | Description |
|
|
718
|
+
| --------- | ------ | -------- | ------------------------------------ |
|
|
719
|
+
| `id` | string | yes | Run id |
|
|
720
|
+
| `version` | string | yes | Target version label (`v1`, `v2`, …) |
|
|
711
721
|
|
|
712
722
|
### `ultraapp_start_container`
|
|
713
723
|
|
|
714
724
|
Start the container/process for the active version (no-op if already running).
|
|
715
725
|
|
|
716
|
-
| Parameter | Type
|
|
717
|
-
|
|
718
|
-
| `id`
|
|
726
|
+
| Parameter | Type | Required |
|
|
727
|
+
| --------- | ------ | -------- |
|
|
728
|
+
| `id` | string | yes |
|
|
719
729
|
|
|
720
730
|
### `ultraapp_stop_container`
|
|
721
731
|
|
|
722
732
|
Stop the container/process without deleting any state.
|
|
723
733
|
|
|
724
|
-
| Parameter | Type
|
|
725
|
-
|
|
726
|
-
| `id`
|
|
734
|
+
| Parameter | Type | Required |
|
|
735
|
+
| --------- | ------ | -------- |
|
|
736
|
+
| `id` | string | yes |
|
|
727
737
|
|
|
728
738
|
### `ultraapp_delete`
|
|
729
739
|
|
|
730
740
|
Stop + remove the run completely (sessions, container, on-disk state, router entry).
|
|
731
741
|
|
|
732
|
-
| Parameter | Type
|
|
733
|
-
|
|
734
|
-
| `id`
|
|
742
|
+
| Parameter | Type | Required |
|
|
743
|
+
| --------- | ------ | -------- |
|
|
744
|
+
| `id` | string | yes |
|
|
745
|
+
|
|
746
|
+
---
|
|
747
|
+
|
|
748
|
+
## Workflow kernel & verification (6.0.0)
|
|
749
|
+
|
|
750
|
+
Full semantics in [`workflow.md`](./workflow.md) and
|
|
751
|
+
[`verification.md`](./verification.md).
|
|
752
|
+
|
|
753
|
+
### `workflow_start`
|
|
754
|
+
|
|
755
|
+
Start a durable run. Every state transition is checkpointed to disk, so a run
|
|
756
|
+
survives a process restart and can be resumed.
|
|
757
|
+
|
|
758
|
+
| Param | Type | Notes |
|
|
759
|
+
| ------------ | -------------------------------- | -------------------------------------------------------------------- |
|
|
760
|
+
| `spec` | object | `WorkflowSpec`: `{ name, nodes[], cwd?, contract?, maxNodeVisits? }` |
|
|
761
|
+
| `template` | `solve` \| `council` \| `fanout` | Build a built-in instead of supplying `spec` |
|
|
762
|
+
| `task` | string | Required with `template` |
|
|
763
|
+
| `agents` | array | `{ name, engine?, model?, persona? }` |
|
|
764
|
+
| `reviewers` | array | `solve` only — agents that review the finished change |
|
|
765
|
+
| `humanGate` | boolean | `solve` only — park for approval before anything is written |
|
|
766
|
+
| `maxRepairs` | number | `solve` only, default 3 |
|
|
767
|
+
| `cwd` | string | Working directory |
|
|
768
|
+
| `runId` | string | Explicit id |
|
|
769
|
+
| `contract` | object | Acceptance contract — see below |
|
|
770
|
+
|
|
771
|
+
Returns `{ runId, workflow, state, nodes }` and runs in the background.
|
|
772
|
+
|
|
773
|
+
### `workflow_status`
|
|
774
|
+
|
|
775
|
+
`{ runId, events? }` → run state, per-node status, `outcome`, `evidenceId`,
|
|
776
|
+
`costUsd`, `consensusVotes`, and the last N events when `events` is given.
|
|
777
|
+
|
|
778
|
+
`outcome` is `verified` (a contract passed), `refuted` (it failed), or
|
|
779
|
+
`unverified` (**none was declared — nothing checked the work**, which is not the
|
|
780
|
+
same as a failure).
|
|
781
|
+
|
|
782
|
+
### `workflow_list` / `workflow_resume` / `workflow_cancel` / `workflow_steer` / `workflow_approve`
|
|
783
|
+
|
|
784
|
+
- `workflow_list({ workflow?, state?, limit? })` — newest first, survives restarts.
|
|
785
|
+
- `workflow_resume({ runId })` — nodes already succeeded are not re-run; the node
|
|
786
|
+
that was in flight is retried, because a half-finished node left no result to
|
|
787
|
+
trust.
|
|
788
|
+
- `workflow_cancel({ runId })`.
|
|
789
|
+
- `workflow_steer({ runId, text })` — the text is **prepended** to the next agent
|
|
790
|
+
node's prompt.
|
|
791
|
+
- `workflow_approve({ runId, approved })` — answers a `human_gate` node.
|
|
792
|
+
|
|
793
|
+
### `verify_run`
|
|
794
|
+
|
|
795
|
+
Run an acceptance contract against a directory outside any workflow — for a plain
|
|
796
|
+
`session_send` that edited a repo, say. `{ cwd, contract, baseSha?, label? }` →
|
|
797
|
+
the evidence bundle.
|
|
798
|
+
|
|
799
|
+
Without `baseSha`, `diff_policy` sees untracked files only.
|
|
800
|
+
|
|
801
|
+
### The `contract` parameter
|
|
802
|
+
|
|
803
|
+
```jsonc
|
|
804
|
+
{
|
|
805
|
+
"id": "ship-it",
|
|
806
|
+
"fixOnFailureRounds": 2,
|
|
807
|
+
"checks": [
|
|
808
|
+
{ "type": "command", "cmd": "npm", "args": ["test"], "timeoutMs": 600000 },
|
|
809
|
+
{ "type": "command", "cmd": "npm", "args": ["run", "lint"], "required": false },
|
|
810
|
+
{ "type": "http", "url": "http://localhost:3000/health" },
|
|
811
|
+
{ "type": "screenshot", "url": "http://localhost:3000/", "viewports": [{ "width": 1440, "height": 900 }] },
|
|
812
|
+
{ "type": "diff_policy", "forbidPaths": ["configs"], "maxFiles": 40 },
|
|
813
|
+
{ "type": "file", "path": "dist/index.js" },
|
|
814
|
+
],
|
|
815
|
+
}
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
**Declare it yourself.** Never copy a contract out of an agent's output: an agent
|
|
819
|
+
that writes its own acceptance criteria is grading itself, which is the problem
|
|
820
|
+
contracts exist to solve. Unrecognised fields are dropped before anything runs,
|
|
821
|
+
and a `command` check is argv — there is no shell string to inject into.
|
|
822
|
+
|
|
823
|
+
`required` defaults to true; a failing non-required check is recorded in the
|
|
824
|
+
evidence bundle without refuting the run.
|
|
825
|
+
|
|
826
|
+
`screenshot` captures and stores images. It does not compare pixels and is not
|
|
827
|
+
visual regression testing.
|