acpx-session

name: acpx-session description: Manage ACPX sessions for delegating tasks from an orchestrator agent to coding agents. Use for agent-to-coding-agent work delegation with named sessions, parallel workstreams, and status tracking. version: "1.0.0"

Install

Copy to agents/<coder>/skills/acpx-session/SKILL.md. Requires ACPX CLI installed and at least one coding agent configured.

ACPX Session Skill

Session Creation

Create a new session for a coding agent:

acpx <agent> sessions new

Named sessions for tracking:

acpx <agent> sessions new --name <name>

Prompt Submission

Send a task to the agent:

acpx <agent> "task description"

Submit from a file:

acpx <agent> --file <path>

Pipe via stdin:

echo "task" | acpx <agent>

Parallel Workstreams

Use named sessions to run concurrent work without collisions:

acpx <agent> -s frontend "implement login page"
acpx <agent> -s backend "add auth endpoint"

Each named session maintains independent context and state.

Exec Mode

For one-shot, stateless tasks that don't need session persistence:

acpx <agent> exec "one-shot task"

No session is created or retained after completion.

Status and Cancel

Check active sessions:

acpx <agent> status

Cancel a running session:

acpx <agent> cancel

Cancel a named session:

acpx <agent> cancel -s <name>

Integration with sessions_send

Combine ACPX with the handoff protocol:

1. Receive a HANDOFF message via sessions_send
2. Spawn an ACPX session for the target coding agent
3. Post ACK with the session name and ETA
4. On completion, post DONE with evidence back via sessions_send
5. If blocked, post BLOCKED with explicit unblock requirements

This bridges the inter-agent handoff protocol with ACPX session management.

Operating Rules

When to use which mode:

• mode: persistent for any task that spans more than one prompt or needs the coding agent to remember context (refactors, multi-file changes, anything with iteration). Cost: a live session per topic.
• exec for stateless, one-shot work (a single read, a one-prompt summary, a quick syntax fix). No session is retained. Always prefer exec when the task fits in one prompt and doesn't need memory of prior turns.

Session naming convention:

• Persistent sessions get a name tied to the task: <task_id> or <scope>-<task_id> (e.g. auth-build-142). This makes ACK/DONE handoffs traceable and lets parallel work coexist without collisions.
• Never reuse a session name across unrelated tasks.

Parallel sessions:

• Use named sessions to keep concurrent workstreams isolated (acpx codex -s frontend ... and acpx codex -s backend ... run in parallel).
• One named session = one workstream. Don't multiplex unrelated prompts through the same session — the coding agent's context will fragment.

Cancel vs. let it run:

• Cancel cooperatively (acpx <agent> cancel -s <name>) when scope changed and the in-flight work is now wrong. Don't kill blindly — cooperative cancel lets the agent flush partial state cleanly.
• Let it run if the work is still relevant but slow. The session lifecycle uses queued/running states; new prompts queue rather than interrupt.

Failure budget:

• After 3 failed retries on the same prompt, stop. Post BLOCKED with what was tried, not another retry. ACPX is not magic — three identical failures usually mean the prompt or the environment is wrong, not the model.

Telegram-specific note:

• For Telegram topics, /acp spawn <agent> --thread here is the in-chat way to start a persistent session bound to the current topic. /acp spawn --bind here does not work on Telegram (it works on Discord/BlueBubbles/iMessage).
• sessions_spawn(runtime="acp", thread:true) from a Telegram subagent currently fails (openclaw/openclaw#41004). Use the slash command or a persistent ACP binding in openclaw.json instead.

Supported Agents