feat(acp): add resumeSessionId to sessions_spawn for ACP session resume

[pejmanjohn]

Summary

Add resumeSessionId parameter to sessions_spawn so agents can resume existing ACP sessions (e.g. a prior Codex conversation) instead of starting fresh. The agent replays conversation history via session/load.

Flow

sessions_spawn(resumeSessionId) → spawnAcpDirect → initializeSession →
ensureSession → acpx --resume-session → agent session/load

Changes

• sessions-spawn-tool.ts — Add resumeSessionId param with description so agents discover and use it
• acp-spawn.ts — Thread through SpawnAcpParams
• manager.types.ts / manager.core.ts — Thread through AcpInitializeSessionInput
• types.ts — Add to AcpRuntimeEnsureInput
• extensions/acpx/src/runtime.ts — Pass as --resume-session flag to acpx CLI

All new fields are optional (backward-compatible).

Dependency

Requires acpx >= next release (openclaw/acpx#85 merged, pending npm publish). The --resume-session CLI flag was added there. Version bump commit will follow once published.

Testing

• 26 unit tests pass (runtime + tool schema)
• Verified e2e: Discord → sessions_spawn(resumeSessionId="...") → Codex resumed session and recalled stored secret
• Tested locally with dev gateway
• Lightly tested (e2e with dev bot, unit tests for all code paths)
• I understand what the code does

🤖 AI-assisted (Codex for initial implementation, manually reviewed and refined)

Note: Happy to open a Discussion first if preferred for new ACP features — wanted to get the implementation up for visibility since the acpx side (PR #85) is already merged.

[aisle-research-bot]

🔒 Aisle Security Analysis

We found 2 potential security issue(s) in this PR:

#	Severity	Title
1	🟡 Medium	IDOR risk: sessions_spawn forwards user-controlled resumeSessionId to ACPX/Codex session resume without authorization/validation
2	🔵 Low	Sensitive resumeSessionId exposed via child process command-line arguments (--resume-session)

---

1. 🟡 IDOR risk: sessions_spawn forwards user-controlled resumeSessionId to ACPX/Codex session resume without authorization/validation

Property	Value
Severity	Medium
CWE	CWE-639
Location	src/agents/tools/sessions-spawn-tool.ts:152-163

Description

The sessions_spawn tool now accepts an optional resumeSessionId and forwards it into the ACP runtime initialization flow, which ultimately runs ACPX with sessions new --resume-session <resumeSessionId>.

If sessions_spawn is available to untrusted/remote callers (e.g., chat users, group tenants, or any non-owner sender allowed to use the tool), this creates a cross-session data access risk:

• resumeSessionId is taken directly from tool arguments and not validated (e.g., UUID-only) or scoped/authorized to the requesting user/session.
• Downstream, ACPX/Codex is instructed to resume an existing session ID (commonly stored under a shared host directory such as ~/.codex/sessions/).
• An attacker who can guess/obtain another session ID could resume it and cause its conversation history to be replayed into the spawned agent context, enabling data exfiltration (summaries, quotes, tool outputs, etc.).

Vulnerable flow (high-level):

• input: resumeSessionId from sessions_spawn tool args (src/agents/tools/sessions-spawn-tool.ts)
• propagation: spawnAcpDirect → AcpSessionManager.initializeSession → AcpRuntime.ensureSession
• sink: ACPX CLI invocation uses --resume-session with attacker-controlled value (extensions/acpx/src/runtime.ts builds ['sessions','new','--resume-session', resumeSessionId]).

Vulnerable code:

const result = await spawnAcpDirect(
  {
    task,
    label: label || undefined,
    agentId: requestedAgentId,
    resumeSessionId,
    cwd,
    mode: mode && ACP_SPAWN_MODES.includes(mode) ? mode : undefined,
    thread,
    sandbox,
    streamTo,
  },
  {
    agentSessionKey: opts?.agentSessionKey,
    ...
  },
);

Recommendation

Add authorization and validation before allowing resumeSessionId to be used.

At minimum:

1. Validate format to reduce path/payload abuse and accidental misuse (UUID v4/v1 style).
2. Restrict scope so callers can only resume sessions they own/created (or require explicit owner approval).
3. Consider disabling this feature by default behind a config flag (opt-in).

Example (format validation + owner-only gate):

import { looksLikeSessionId } from "../../sessions/session-id.js";
import { ToolAuthorizationError, ToolInputError } from "./common.js";

​// ... inside execute
const resumeSessionId = readStringParam(params, "resumeSessionId");
if (resumeSessionId) {
  if (!looksLikeSessionId(resumeSessionId)) {
    throw new ToolInputError("resumeSessionId must be a UUID");
  }
  ​// If this tool can be invoked by non-owner senders, require owner or a config allowlist.
  if (!opts?.senderIsOwner) {
    throw new ToolAuthorizationError("resumeSessionId is restricted to owner senders.");
  }
}

Stronger approach: maintain a mapping of allowed resumeSessionIds per requester (or per agentSessionKey/accountId) and verify membership before passing it downstream.

---

2. 🔵 Sensitive resumeSessionId exposed via child process command-line arguments (--resume-session)

Property	Value
Severity	Low
CWE	CWE-214
Location	extensions/acpx/src/runtime.ts:206-213

Description

The ACPX runtime passes resumeSessionId as a raw command-line argument when resuming a session:

• resumeSessionId is taken from AcpRuntimeEnsureInput and appended into the spawned acpx CLI argv (--resume-session <id>).
• OS-level process inspection (e.g., /proc/<pid>/cmdline, ps, crash dumps, some process supervisors) can expose argv to other local users/processes.
• This identifier is described as a Codex session UUID from ~/.codex/sessions/; leaking it may enable unintended correlation/access to prior conversation history in environments where session IDs are security-relevant.

Vulnerable code:

const resumeSessionId = asTrimmedString(input.resumeSessionId);
const ensureSubcommand = resumeSessionId
  ? ["sessions", "new", "--name", sessionName, "--resume-session", resumeSessionId]
  : ["sessions", "ensure", "--name", sessionName];

Recommendation

Avoid placing sensitive identifiers in process argv.

Options (best to worst):

1. Pass the resume session id via stdin or a temp file (so it doesn't appear in ps output).
2. Pass via environment variable (still sometimes exposed, but typically less visible than argv).
3. If the acpx CLI requires argv, add a redaction layer anywhere commands are logged/telemetry-captured (and document that resumeSessionId is sensitive).

Example approach using an env var (requires acpx support; otherwise add a new CLI option that reads from env/stdin):

​// Prefer: acpx reads resume id from env or stdin rather than argv
const env = { ...process.env, ACPX_RESUME_SESSION_ID: resumeSessionId };
spawn(resolved.command, resolved.args /* without resumeSessionId */, { cwd, env });

---

Analyzed PR: #41847 at commit d7950d9

_{Last updated on: 2026-03-10T09:56:22Z}

[greptile-apps]

Greptile Summary

This PR adds an optional resumeSessionId parameter to the sessions_spawn tool and threads it through the ACP stack (acp-spawn.ts → manager.core.ts → types.ts → runtime.ts) so that the acpx CLI receives a --resume-session flag and replays an existing Codex conversation instead of starting a fresh one. All additions are backward-compatible (optional fields). The runtime-level logic in extensions/acpx/src/runtime.ts is clean, and both the runtime test and tool-layer test cover the happy path well.

One logic gap to address:

• resumeSessionId silently ignored for the default subagent runtime — resumeSessionId is read in sessions-spawn-tool.ts but is never forwarded to spawnSubagentDirect. Because runtime defaults to "subagent" when not explicitly provided, an agent that passes resumeSessionId without also specifying runtime="acp" will silently receive a brand-new session rather than the resumed one. The codebase already has the right pattern for this: the streamTo parameter has an early-return guard. The same guard should be added for resumeSessionId, and the schema description should explicitly note the runtime=acp requirement.

Confidence Score: 2/5

• Unsafe to merge without fixing the runtime guard for resumeSessionId — agents may silently create fresh sessions instead of resuming intended ones.
• One verified logic bug in src/agents/tools/sessions-spawn-tool.ts: resumeSessionId parameter is silently dropped when runtime defaults to "subagent" (the default when not explicitly set). This mirrors a bug pattern that was already fixed for the streamTo parameter in the same function. The fix is straightforward (add an early-return guard and update the schema description), but without it, user input is silently ignored, leading to incorrect session behavior. All other type threads and ACP runtime logic are correct and well-tested.
• src/agents/tools/sessions-spawn-tool.ts — add runtime guard for resumeSessionId and update schema description to mention runtime=acp requirement.

Comments Outside Diff (1)

1. src/agents/tools/sessions-spawn-tool.ts, line 130-135 (link)

   resumeSessionId is read at line 100 but is never forwarded to spawnSubagentDirect. Because runtime defaults to "subagent" when not explicitly set, an agent that calls sessions_spawn({ task: "...", resumeSessionId: "..." }) without specifying runtime: "acp" will silently start a fresh session instead of resuming the intended one — with no error or warning.

   This is the same problem that was already solved for streamTo, which has an explicit runtime guard right above this block. The same pattern should be applied to resumeSessionId:

   Additionally, the resumeSessionId schema description (lines 28-33) should mention the runtime=acp requirement so agents discover this constraint before calling the tool.

_{Last reviewed commit: 1821ef4}

[pejmanjohn]

Addressed @greptile-apps feedback in 886a3d3:

• Added early-return guard that errors when resumeSessionId is passed without runtime="acp" (mirrors the existing streamTo guard pattern)
• Updated schema description to note the runtime=acp requirement
• Added test for the guard (27/27 tests pass)

Good catch — without this, agents that omit runtime would silently get a fresh session instead of resuming.

[greptile-apps]

Perfect! The guard implementation looks clean:

1. Early-return pattern matches the existing streamTo guard perfectly
2. Clear error message tells users exactly what's wrong: resumeSessionId is only supported for runtime=acp; got runtime=${runtime}
3. Schema updated to document the requirement upfront
4. Test coverage verifies both the error path and that no spawn functions are called

This prevents the silent failure where agents would get a fresh session instead of resuming. Good catch and solid fix! ✅

[onutc]

Landed after rebasing onto current main.

• Gate: pnpm lint, pnpm build, pnpm test
• Source branch commit: pejmanjohn@d7950d9
• Landed commit: aca216b

Thanks @pejmanjohn!