From 466cc816a828b684d43dbd4f9a11f6f12560e4fb Mon Sep 17 00:00:00 2001 From: Pejman Pour-Moezzi Date: Tue, 10 Mar 2026 10:06:09 -0700 Subject: [PATCH] docs(acp): document resumeSessionId for session resume (#42280) * docs(acp): document resumeSessionId for session resume * docs: clarify ACP resumeSessionId thread/mode behavior (#42280) (thanks @pejmanjohn) --------- Co-authored-by: Onur --- docs/tools/acp-agents.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index e41a96248ae..65a320f1c52 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -243,9 +243,36 @@ Interface details: - `mode: "session"` requires `thread: true` - `cwd` (optional): requested runtime working directory (validated by backend/runtime policy). - `label` (optional): operator-facing label used in session/banner text. +- `resumeSessionId` (optional): resume an existing ACP session instead of creating a new one. The agent replays its conversation history via `session/load`. Requires `runtime: "acp"`. - `streamTo` (optional): `"parent"` streams initial ACP run progress summaries back to the requester session as system events. - When available, accepted responses include `streamLogPath` pointing to a session-scoped JSONL log (`.acp-stream.jsonl`) you can tail for full relay history. +### Resume an existing session + +Use `resumeSessionId` to continue a previous ACP session instead of starting fresh. The agent replays its conversation history via `session/load`, so it picks up with full context of what came before. + +```json +{ + "task": "Continue where we left off — fix the remaining test failures", + "runtime": "acp", + "agentId": "codex", + "resumeSessionId": "" +} +``` + +Common use cases: + +- Hand off a Codex session from your laptop to your phone — tell your agent to pick up where you left off +- Continue a coding session you started interactively in the CLI, now headlessly through your agent +- Pick up work that was interrupted by a gateway restart or idle timeout + +Notes: + +- `resumeSessionId` requires `runtime: "acp"` — returns an error if used with the sub-agent runtime. +- `resumeSessionId` restores the upstream ACP conversation history; `thread` and `mode` still apply normally to the new OpenClaw session you are creating, so `mode: "session"` still requires `thread: true`. +- The target agent must support `session/load` (Codex and Claude Code do). +- If the session ID isn't found, the spawn fails with a clear error — no silent fallback to a new session. + ### Operator smoke test Use this after a gateway deploy when you want a quick live check that ACP spawn