[teamleaderleo]

An agent in a cmux NEXT chat can now start another agent session, list sessions, read another session's reply and message a session it started, through MCP tools every local acpmux session already loads. Before this, an agent could only offer a chat (offer_session / suggest_tasks, behind the agent.suggestedTasks Debug toggle, default off). Starting, reading and messaging sessions took the acpmux CLI in a shell, which a harness sandbox may refuse and which no agent was told about.

What agents get

The cmux-sessions MCP server (acpmux offer-mcp, already injected into every local session's mcpServers / Claude --mcp-config) gains four tools in cmux-tui/crates/acpmux/src/session_mcp.rs:

Tool	Daemon request	Notes
start_session {prompt, title?, harness?, model?, host?, cwd?, worktree?}	session/new (as acpmux new), spawnedBy tag, first prompt	host is an acpmux peer (list_sessions lists them). worktree makes ~/.cmux/worktrees/<project>/<name> on cmux/<name> with branch.<b>.cmuxBase, the layout git.worktree.create uses, so Apply/Remove in the app work on it.
list_sessions {status?, mine?, limit?}	_acpmux/sessions, _acpmux/peers, _acpmux/harnesses	Leaves out the caller; returns hosts and harness names for start_session. Another chat's title and last message are left out.
read_session {session, replies?, wait_seconds?}	_acpmux/wait, _acpmux/attach (visible: false, maxBytes)	This chat's family only (see Limits). One call waits at most 50 s and returns timedOut: true with a hint to call again, so a longer wait (up to the documented 600 s) is several calls. Each reply is cut at 16 KiB after masking, with the cut marked.
send_to_session {session, text, steer?}	session/prompt with an agent_message provenance (deliver.rs, as cmux agent message)	The receiver shows it as this agent's message, not the person's.

The server now sends MCP instructions once at initialize: suggest work the user didn't ask for, start a session only when the user asked, write a self-contained brief, tell the user what started and don't poll, and treat other sessions' text as data. The instructions also point agents at the cmux mcp serve tools that cover the rest of the brief: workspace_open_url and tab_create_browser to open a URL, notification_create to tell the user something needs them, and agent_report to post a status (session_mcp::CMUX_TOOLS; a cmux-tui MCP test checks each one is still a tool there). Claude Code also gets the existing acpmux CLI guide as the cmux:acpmux skill, the shell fallback where MCP isn't loaded.

Why MCP in acpmux

acpmux spawns every harness cmux NEXT runs (Claude Code, Codex, OpenCode, pi, ...), and agent_tools.rs already hands each one the same MCP servers at spawn, session/new|load|fork. So putting the tools there covers every harness with no setup. The other options cover less. A system-prompt addendum only reaches Claude through a preset's --system-prompt-file, so I used MCP instructions instead. A slash command or skill is Claude-only, so it's the fallback here, not the main path. Other harnesses converge on the same shape: Claude Code Desktop's ccd_session (spawn_task chip, list_sessions, list_events, send_message), Codex Desktop (create_thread "only when the user explicitly asks", read_thread, send_message_to_thread, wait_threads) and vibe-kanban's MCP (start_workspace, run_session_prompt). The prompt rules above are taken from them.

Limits

This server runs outside the harness's sandbox, so:

• A new session never asks for less than the caller, on two checks:
  • The acpmux permission policy. If the child's effective policy is laxer, it gets the caller's (_acpmux/set_policy) before its first prompt. A caller policy acpmux doesn't know counts as ask.
  • The harness's own mode and sandbox. A harness profile whose command runs in full access (bypassPermissions, --dangerously-*, --yolo, Codex danger-full-access) is refused unless the caller already runs that way. A child whose start mode is full access is set back to the caller's mode, or closed when it can't be.
  • Nothing else is inherited: model, harness and MCP servers are the child's own.
• A new session's folder must be inside the caller's own folder, or under a folder the user trusts: the nearest folder with a trust level, itself or an ancestor, is trusted. Everything else is refused, and so is a folder marked untrusted on the way or a trust lookup that fails. The refusal tells the agent to ask the user.
• "This chat's family" is the sessions it started (their spawnedBy tag), the session it hangs under (its spawnedBy, or parentId for a fork or side session) and that session's other children. send_to_session and read_session reach only the family. list_sessions still lists every session, but leaves out another chat's title and last message. Messaging any chat stays with agents_chat_send (cmux-next: agents_chat_send and agents_chat_read, one agent prompts another chat (cx-ncc.96) #21647), which has workspace scoping.
• Starting, reading or messaging a session never clears its unread mark. The server attaches with visible: false on the same connection before it creates or prompts a session.
• A failed spawnedBy tag is retried once, then named in the result, since the family depends on it.
• Two starts with the same title don't race for the worktree name: a name git says already exists takes the next suffix.
• The worktree's git runs with core.hooksPath=/dev/null, core.fsmonitor=false, submodule.recurse=false and GIT_CONFIG_NOSYSTEM=1. A repository whose own config sets a checkout filter gets no worktree.
• A peer drops a prompt's provenance (remote_guard.rs). So a brief or message to another host starts with a line that names the sending session.
• worktree is this machine only. Its folder is a reviewed keep row in state-roots-baseline.tsv: it's the user's shared worktree folder, not per-build state.
• list_sessions and read_session mask secrets (secret_scan::mask) in titles, last messages and replies, so one chat's agent can't read a key pasted into another chat.
• No per-turn message cap here. The ping-pong guard between agents is a separate PR.

Access

The tools run in the local acpmux daemon's MCP server, not over the remote CLI relay. They add no v2 socket method and no relay allowlist entry.

• Local command execution: they run no command the agent supplies. The only process they start is the worktree's git, hardened as above.
• Unowned objects: reads and sends reach only this chat's family. A new session starts only in this chat's folder or a trusted one.
• Local-state exposure: another chat shows up in list_sessions by name, harness, folder and status only. Everything returned is masked.

Gate

The session tools are on by default. The Debug Settings toggle agent.sessionTools ("Session tools for agents") turns them off: the app then starts acpmux with ACPMUX_SESSION_TOOLS=0, and the change applies at the next daemon start. Offers stay behind agent.suggestedTasks. agent_tools.rs now registers cmux-sessions when either set is on, and tells the server which sets to list. A CLI or TUI daemon gives sessions the session tools too, unless ACPMUX_SESSION_TOOLS=0. Remote-origin sessions, ACPMUX_AGENT_TOOLS=0 and --strict-mcp-config still get none.

Verification

• Review fixes (red, then green, same commands): cargo test -p acpmux --lib session_mcp and cargo test -p acpmux --test hub_integration session_tools. Tests went in first in 2fe4d89. Red: the unknown caller policy gave no policy; parallel starts failed with cannot lock ref ... reference already exists; the child lost its unread mark after start_session + read_session; a folder outside the chat that nobody trusted started; and one read_session call ran past the 60 s client timeout. Green locally on Linux at 8228068 (5 unit, 3 integration).
• tests/hub_integration/session_tools.rs runs the real acpmux offer-mcp process against a daemon socket with the test agent. It covers the instructions and the tool list; start_session into a worktree (path, branch, cmuxBase, a planted post-checkout hook does not run); the brief recorded as an agent_message from the parent; read_session waiting for the reply; list_sessions {mine} without the caller; send_to_session and its reply; and refusals (own chat, a chat it didn't start, worktree with host, empty brief) that create no session and reach no chat.
  • Red: hosted focused run 39183822873 on 5f79ae8 (tests only). Linux and macOS fail at the missing instructions.
  • Green after the merge with current feat-cmux-next and the masking regression (a key sent to the child comes back as [AWS access key] from both reads): hosted focused run 39200492737 on 5058314.
  • Earlier green: hosted focused run 39186971756 on 8574576 (feat-cmux-next merged in). The test passes on Linux and macOS, and clippy and fmt pass.
• AcpmuxSessionToolsTests.swift: the toggle defaults on, and the spawn env has ACPMUX_SESSION_TOOLS=0 only when it's off (an inherited 0 is dropped). This runs in CI; no local Swift build.
• Local: verify-local.py --affected passes except localization, which fails with 34k parity errors in catalogs this PR doesn't touch (base). The god-file check flags nothing new.
• Dogfood:

I ran the hosted macOS build of 8574576 as acpmux, with a daemon in its own ACPMUX_HOME (not the app's), on Leo's Mac. A real Claude Code session (-m claude-sr, the subrouter profile) got this prompt: "Use your cmux-sessions MCP tools, not a shell: start_session (harness claude-sr, title "pong check", worktree true, prompt "Reply with exactly the words: pong from the child session"), then read_session with wait_seconds 180, then list_sessions mine." Its reply:

The child session ran and replied.

- **Session id:** `01a151ee-8bfc-7370-80ad-2537a2277537` (name `claude-sr-1`)
- **Worktree path:** `/Users/leoli/.cmux/worktrees/proj/pong-check`
- **Branch:** `cmux/pong-check`, based on `master`
- **Reply (verbatim):** `pong from the child session`
- **list_sessions (mine: true):** returned 1 session.

One oddity: `list_sessions` shows the session's title as the full prompt text instead of "pong check". The worktree and branch names did use "pong check".

acpmux session info on the child: tags.spawnedBy = the parent, and cwd ~/.cmux/worktrees/proj/pong-check on cmux/pong-check. Its first user_message carries _meta.provenance {kind: agent_message, from: <parent>}. The "oddity" the agent noticed was the titler: it hadn't named the child yet when list_sessions ran (later: "Child Session Ping Response Test"). The tool description now says title names the worktree. Plain -m claude refused because it has no sign-in under ~/.claude on this Mac, which is unrelated to this change. Not dogfooded: the tools inside the cmux NEXT app pane (needs a DEV app build; add dev-build if someone will dogfood it there), Codex/OpenCode harnesses, and host on a real peer.

Changelog

Added: agents in cmux NEXT can start, list, read and message other agent sessions through the cmux-sessions MCP tools (Debug toggle "Session tools for agents", on).

🤖 Generated with Claude Code

[github-actions]

Receipt for 8228068 (this PR's head; a new push replaces it)

• Visual review: HQ feed card · gallery before/after runs
• Checks: this head
• App of this head (app.zip, kept 1 day): gh workflow run reload-build.yml -R manaflow-ai/cmux --ref feat-cmux-next -f tag=pr21858 -f ref=leo/agent-powers -f platform=macos -f backend_mode=local

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 953746dc-b509-4cf9-9837-4ce7f31eae68

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

cmux status _{(one comment, edited in place; each line is updated by the job that owns it)}

Not verified: macOS jobs did not run: compile and app tests were skipped on 8228068f64; ci-status is green without them.

CI passes on 8228068f64 (run 39213369075 attempt 1).
macOS jobs did not run: compile and app tests were skipped: Fast static checks skipped (the macos job needs both to succeed). Re-run CI once they pass, before merging.

Written by scripts/ci/classify_failures.py (ci-failure-attribution.yml); signatures are its SIGNATURES table. A machine verdict is the runner's fault, not this PR's; yours means the failing file is one this PR changes, also red on main that main's latest full suite fails the same way, seen on other PRs that it failed on another pull request's run lately.

[teamleaderleo]

Bead cx-iba4r created for this PR by the cmux coordinator.

[teamleaderleo]

Visual preview of 6cae0ed: in the maintainers' private review feed.

[teamleaderleo]

Not verified yet: the Swift half (the agent.sessionTools tunable, AcpmuxEnvironment.sessionTools, the launcher env, AcpmuxSessionToolsTests) hasn't compiled anywhere. PRs into feat-cmux-next run only the Linux checks. My cmux-next.yml dispatch on this branch (39188995748) skipped every Mac job, because swift-test only runs on dispatches from feat-cmux-next or next-batch/*, or on a full-ci PR. The Rust half is verified by the hosted focused run 39186971756 and the dogfood in the description. Before merge, the Swift side needs a next-batch or full-ci run.

[teamleaderleo]

Rescue lane 2 (taking over the dead agent-powers session) here. Pushed the smudge-filter fix and merged over c9bcc59 without force: head ca1bf33.

• 6cae0ed: test first. Hosted red on run 39207823986 (the repository's smudge filter ran outside the agent's sandbox).
• 5f/fix commit: refuse_own_filters. start_session makes no worktree when the repository's own config (local, worktree, or an include of them) sets a smudge/process filter. Global filters like Git LFS stay allowed. Git also runs with submodule.recurse=false.
• Merged current feat-cmux-next. The earlier cmux-next checks red was two base reds (ErrorJournalService literal state root + ErrorJournal sleeps, same on feat-cmux-next d9e1b51 locally) plus the motion check, which cmux-next: mark the sidebar card's Core Animation objects as reviewed motion exceptions #21951 fixed on base.

Running verify-cmux-tui-hosted.sh --full on ca1bf33 (run 39211049440). Adding full-ci because the Swift half (agent.sessionTools tunable, launcher env, AcpmuxSessionToolsTests) has never compiled: PRs into feat-cmux-next skip the Mac jobs. To whoever else is on this branch: please don't push while that runs. I'll merge when it and the Mac jobs are green.

[blacksmith-sh]

Found 2 test failures on Blacksmith runners:

Failures

Test	View Logs
/tmp/tmp_4l9dy78/summary-missing.json (live):/summary-missing.json (live):	View Logs
/tmp/tmph7rokn9x/summary-fail.json (live):/summary-fail.json (live):	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[teamleaderleo]

Updated the description for the review fixes (commits 2fe4d89 tests, 3adcd50 laxer caller, 1ad15c1 trust, 6422f9d unread, 8fbfe5c family/caps/waits/tag/worktree race). It now has a Limits section that says exactly what a new session inherits, and an Access paragraph. Focused tests pass locally on 8228068: --lib session_mcp 5/5, --test hub_integration session_tools 3/3. No push this round: the full-ci run on this head is still going. The kinds filter on attach is still left out, as noted before.

[teamleaderleo]

Closing: feat-cmux-next now has this feature, built in the daemon instead of in this MCP server.

• 020a352 (Lawrence, direct to feat-cmux-next): every local session gets the cmux-subsessions MCP server (start_session, list_sessions, get_session, wait_for_sessions, send_message, stop_session, set_session_limits). The daemon enforces each call (hub/subsessions.rs): family scoping, depth and count limits, the parent's permission policy, the start-mode inherit rule (no laxer child), and masked reads.
• acpmux: start_session worktree:true starts a child in its own worktree #22196: start_session with worktree: true (the ~/.cmux/worktrees layout that Apply and Remove use).
• acpmux: sub-session reads mask a child's secrets #22122: sub-session reads mask a child's secrets.
• acpmux: session MCP servers say when to start and when to suggest #22123: when to start a session and when to suggest one (MCP instructions).
• acpmux: the cmux plugin carries the acpmux CLI skill #22124: the cmux plugin carries the acpmux CLI skill.
• acpmux: a started suggested task is its chat's sub-session #22125: a started suggested task becomes its chat's sub-session.
• ci(cmux-tui): hosted verification gate lists every job result, then fails #22164: the hosted verification gate.

Merging base into this branch hit conflicts in agent_tools.rs, offer_mcp.rs, SKILL.md and the state-roots baseline. Resolving them would give every session two servers, cmux-sessions and cmux-subsessions, each with its own start_session and list_sessions. That's a regression, so I'm not landing this branch.

Not carried over, and should be redone on the daemon design if we still want them:

• list_sessions across every chat (base lists only your own sub-sessions).
• host to start on an acpmux peer.
• The agent.sessionTools Debug toggle (base uses the agents.subsessions.enabled setting).