feat: add optional working_dir to MCP and LSP toolset configs

[simonferquel-clanker]

Summary

Adds an optional working_dir field to MCP and LSP toolset configurations, allowing these processes to be launched from a directory other than the agent's working directory.

Closes #2459

Changes

• pkg/config/latest/types.go — New WorkingDir field on Toolset struct
• pkg/config/latest/validate.go — Validation: working_dir only valid for types mcp and lsp
• pkg/config/mcps.go — Propagate working_dir from top-level mcps: definitions to referencing agent toolsets (existing toolset value takes precedence)
• pkg/teamloader/registry.go — resolveToolsetWorkingDir helper; createMCPTool and createLSPTool resolve and pass the working directory to the process
• agent-schema.json — working_dir added to Toolset and MCPToolset schema definitions
• Tests — validate_test.go, mcps_test.go, registry_test.go coverage for the new field
• examples/toolset-working-dir.yaml — New example demonstrating the feature

Behaviour

• working_dir is optional; omitting it keeps existing behaviour (process starts from agent's working directory)
• Relative paths are resolved relative to the agent's working directory
• Absolute paths are used as-is
• When using the top-level mcps: section, working_dir is inherited by referencing toolsets; a toolset-level value overrides the definition

[krissetto]

/review

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

Note: Automated verification returned inconclusive results. Findings are source-confirmed by manual code inspection.

[docker-agent]

MEDIUM: working_dir silently ignored when a ref: MCP catalog entry resolves to a remote server

The comment on this line is incorrect: the "remote branch" can be reached for ref:-based MCPs whose catalog entry resolves to serverSpec.Type == "remote" at runtime. In that case, createMCPTool returns early via mcp.NewRemoteToolset(...) (see line 323) without passing cwd:

if serverSpec.Type == "remote" {
    return mcp.NewRemoteToolset(toolset.Name, serverSpec.Remote.URL, ..., nil, nil), nil
    // ^ cwd is never passed — working_dir is silently discarded
}

The validation in validate.go only blocks working_dir when Remote.URL is set directly in the config; it does not block ref:-based toolsets. A user who writes:

toolsets:
  - type: mcp
    ref: docker:some-remote-server
    working_dir: ./workspace

will:

1. Pass config validation ✓
2. Have their directory existence-checked at startup (unnecessary work)
3. Have working_dir silently discarded at runtime

Fix options:

• Update the comment to accurately state the invariant (the remote Ref path is NOT blocked by validation)
• Optionally add a warning or error when working_dir is set but the resolved gateway spec is remote

[simonferquel-clanker]

Fixed in commit af057f34.

The misleading comment ("The remote branch never reaches here because working_dir is rejected by validation for toolsets with a remote.url") has been removed and replaced with an accurate one explaining the limitation: validation only blocks explicit remote.url toolsets; ref-based MCPs are not covered at parse time.

The runtime fix is in the serverSpec.Type == "remote" early-return inside the Ref branch:

if serverSpec.Type == "remote" {
    if toolset.WorkingDir != "" {
        return nil, fmt.Errorf("working_dir is not supported for MCP toolset %q: ref %q resolves to a remote server (no local subprocess)",
            toolset.Name, toolset.Ref)
    }
    return mcp.NewRemoteToolset(...), nil
}

The unnecessary checkDirExists call for ref-based toolsets is also deferred to after the server spec is resolved, so it only runs for subprocess-based refs.

[docker-agent]

MEDIUM: Validation gap — working_dir not rejected for ref:-based MCPs that may resolve to remote at runtime

This check only blocks working_dir when Remote.URL is set explicitly:

if t.WorkingDir != "" && t.Type == "mcp" && t.Remote.URL != "" {
    return errors.New("working_dir is not valid for remote MCP toolsets (no local subprocess)")
}

ref:-based MCPs (e.g. ref: docker:context7) are not covered. Their serverSpec.Type is only known at runtime (via the MCP Catalog API), so if the catalog entry resolves to a remote server, working_dir is silently dropped with no user-visible error.

The companion misleading comment in registry.go ("The remote branch never reaches here because working_dir is rejected by validation for toolsets with a remote.url") reinforces this false assumption.

Suggested fix: At minimum, update the comment in registry.go to accurately describe that only explicit-remote.url toolsets are guarded at validation time, not Ref-based ones. Optionally emit a warning when a Ref-based MCP with working_dir resolves to remote at runtime.

[simonferquel-clanker]

Fixed in commit af057f34.

• Updated the comment on this validation rule to clarify it only blocks explicit remote.url toolsets; ref-based MCPs are not covered at parse time because their transport type is only known at runtime.
• Added a runtime check in the serverSpec.Type == "remote" branch inside createMCPTool: if toolset.WorkingDir != "", an explicit error is returned ("working_dir is not supported for MCP toolset ... ref ... resolves to a remote server") instead of silently discarding the field.
• Also deferred the checkDirExists call for ref-based toolsets so it only runs after the server spec is resolved (avoids unnecessary work when the ref turns out to be remote).
• Added gateway.OverrideCatalogForTesting helper + TestMain in pkg/teamloader to enable unit tests without network, plus TestCreateMCPTool_RefRemote_WorkingDir_ReturnsError and TestCreateMCPTool_RefRemote_NoWorkingDir_Succeeds.

[krissetto]

overall lgtm, we should also updated the docs around this though

[simonferquel]

doc updated

[simonferquel]

Re-approving: force pushed was only a doc updated after a rebase