Regression: MCP handoff no longer inherits supervisor working directory

[alexmercenary]

Symptom

Handoff workers start in the cao-server process working directory (typically the CAO repository root) instead of inheriting the supervisor's project directory. For example, launching with:

cao launch --working-directory /path/to/my-project --agents supervisor

...the supervisor correctly starts in /path/to/my-project, but any worker created via the handoff MCP tool starts in the CAO checkout directory.

Investigation

Traced the complete execution path:

MCP handoff
  → _handoff_impl()
  → POST /terminals/run-step
  → run_agent_step()
  → create_terminal()
  → TmuxClient.create_window()
  → _resolve_and_validate_working_directory()

working_directory is conditionally omitted from the run-step payload when it is None, so it propagates unchanged to TmuxClient, which correctly falls back to os.getcwd().

In _handoff_impl:

if working_directory:
    payload["working_directory"] = working_directory

Previous behaviour

_create_terminal() (still used by assign) automatically resolved the supervisor terminal's current working directory via GET /terminals/{id}/working-directory whenever working_directory was None. This inherited the supervisor's pane CWD so workers started in the same project directory.

Current behaviour

During the _handoff_impl() refactor in #320, the handoff flow was simplified to a single POST /terminals/run-step. The supervisor working-directory inheritance step was no longer performed. _resolve_handoff_provider() still resolves session_name, caller_id, and allowed_tools, but not working_directory.

Root cause

In _handoff_impl():

1. The supervisor working directory is no longer resolved when working_directory is None.
2. working_directory is only included in the payload when truthy, so the field is omitted entirely when unset.

Potential fix

I tested a local fix that:

1. Restores supervisor CWD auto-resolution in _handoff_impl() (mirroring _create_terminal()):

if working_directory is None:
    current_terminal_id = os.environ.get("CAO_TERMINAL_ID")
    if current_terminal_id:
        try:
            response = requests.get(
                f"{API_BASE_URL}/terminals/{current_terminal_id}/working-directory",
                timeout=_mcp_timeout(),
            )
            if response.status_code == 200:
                working_directory = response.json().get("working_directory")
        except Exception:
            pass

2. Always includes working_directory in the run-step payload:

payload["working_directory"] = working_directory

This is confined to server.py and preserves the existing fallback behaviour if CWD resolution fails. RunStepRequest.working_directory already defaults to Optional[str] = None, so the unconditional inclusion is safe.

I haven't opened a PR yet because I wanted to confirm this aligns with the intended architecture first, but I'm happy to submit one if this approach makes sense.

[haofeif]

@alexmercenary thanks for raising this looking into the issue.

[haofeif]

@alexmercenary Thanks for the thorough write-up. The diagnosis is correct, and I confirmed it against current main.

We already have this mechanism, just not on the handoff path

The assign path already inherits the supervisor's working directory. In _create_terminal, when working_directory is None:

# server.py, _create_terminal (assign)
if working_directory is None:
    response = requests.get(f"{API_BASE_URL}/terminals/{current_terminal_id}/working-directory", ...)
    if response.status_code == 200:
        working_directory = response.json().get("working_directory")
        logger.info(f"Inherited working directory from conductor: {working_directory}")

That endpoint resolves the supervisor's live pane CWD via tmux (get_pane_working_directory), so an assign worker starts wherever the supervisor currently is, even when that differs from the cao-server CWD. The same primitive backs the kiro/codex memory plugins. So the machinery to "not start in cao-server's directory" already exists and works.

The fix for handoff is therefore not new machinery. It is applying this existing, proven assign mechanism to the handoff path.

Confirming the regression

_handoff_impl never resolves the supervisor working directory, and only forwards working_directory when it is truthy:

# server.py, _handoff_impl
if working_directory:
    payload["working_directory"] = working_directory

_resolve_handoff_provider resolves the other supervisor-derived context (session_name, caller_id, allowed_tools) into HandoffContext, but working directory was left out. So for handoff, working_directory reaches run_agent_step as None and TmuxClient falls back to the server's os.getcwd(). This is why assign and handoff diverged after the #320 refactor: assign kept the inheritance, handoff dropped it. Looks like an oversight in that refactor, not an intentional change.

Architecture alignment: two valid options

There are two places this can be fixed, and both are consistent with the current design. Worth picking deliberately:

Option A: caller-side (your proposal). Resolve the supervisor CWD in the MCP process via GET /terminals/{CAO_TERMINAL_ID}/working-directory and pass it in the run-step payload. This mirrors _create_terminal exactly and restores parity between assign and handoff.

If you go this way, the cleaner home is _resolve_handoff_provider (or a new field on HandoffContext) rather than an inline block in _handoff_impl. That keeps all supervisor-derived context resolved in one place, which is what HandoffContext is documented to be ("supervisor-derived context resolved WITHOUT creating a terminal").

Option B: server-side. The run-step endpoint already receives caller_id (the supervisor terminal id). run_agent_step could resolve CWD from it when working_directory is None, calling terminal_service.get_working_directory(caller_id) directly (a local call, no extra HTTP hop). This keeps the MCP client thinner and removes one round-trip.

Both are correct. Option A is the smaller change and matches the assign precedent. Option B is arguably the cleaner long-term shape since the server already owns caller_id and the CWD lookup is local to it. Maintainers' call on which fits the intended direction.

Notes that apply to either option

• GET /terminals/{id}/working-directory / get_working_directory() reads the live pane CWD via tmux, so the worker inherits wherever the supervisor currently is, not just its create-time directory. That matches the pre-feat(workflow): spec grammar + run_agent_step substrate (#312 Bolt 1) #320 behavior.
• Keep the best-effort fallback you have: if resolution fails, degrade to the server default rather than erroring. That is what the assign path does today.
• RunStepRequest.working_directory already defaults to Optional[str] = None, so always including it in the payload is safe.

Happy to review the PR whichever option you pick.

[alexmercenary]

Apologies for the slow reply. I'll follow your guidance and submit a PR this week for your review.

Thank you for confirming.