[danshapiro]

What users see

Freshclaude and Kilroy panes now get the Freshell MCP tools, the same tools a Claude terminal pane already has. The agent in the pane can list tabs, split its own pane, send keys and so on. Calls that name no target act on the agent's own pane, not on the pane the user happens to be looking at.

The tools follow Settings → Advanced → "Agent MCP server". The setting is read each time an agent starts, so changing it applies to the next pane you open or resume, with no server restart. Terminal panes do not follow the switch yet (#446, out of scope here).

What changed

1. One launch builder carries the MCP recipe and the pane. ClaudeLaunchSpec (claude_launch.rs) gained two optional fields: freshellMcp (the command and arguments of the Freshell MCP server) and freshellContext (the tab and pane the session runs for). Every way an agent starts goes through it: create, attach-resume, handoff resume, undo/redo and fork. An undo replacement or a fork child keeps its parent's pane.
2. The setting is read live. main.rs installs a provider that reads settings.codingCli.mcpServer at each sidecar start (new module crates/freshell-server/src/claude_freshell_mcp.rs). When the setting is on but the server command cannot be found, the pane starts without the tools and a warning is logged.
3. The token never goes on a command line. The sidecar always gets FRESHELL=1, FRESHELL_URL and FRESHELL_TOKEN in its environment, built from the server's own port and token. The MCP recipe holds only a command and arguments, never an env key, so the token never reaches the CLI's argv. Pane ids inherited from elsewhere are removed; only the pane's own ids are set.
4. Hosted and ordinary recipes never mix. The new sidecar module mcp-servers.mjs (it replaces hosted-mcp.mjs) gives a hosted session the session host's fixed recipe and an ordinary session the recipe Rust resolved. A session never gets both. Hosted Kilroy now gets the hosted recipe too; before this, the sidecar refused it.
5. Create and attach name their pane. freshAgent.create and freshAgent.attach carry tabId/paneId (protocol and client).
6. A handoff resumes for the pane that adopts the session. Switching a Claude terminal pane to Freshclaude/Kilroy, or stop-and-reopen, passes the pane's ids through to the resumed CLI. Without this, an untargeted MCP call from such a pane would have acted on the user's active pane.
7. Logs. freshagent.claude.mcp_injection (info) is logged at each launch, and freshagent.claude.mcp_unavailable (warn) when the command cannot be resolved. In the sidecar, mcp.freshell_recipe_rejected (warn) is logged when a recipe arrives malformed and is left out.
8. Test tools. The CLI simulator now starts stdio MCP servers the way the pinned CLI does (conformance scenario mcp). It hands them only the SDK's environment, and a program's text step can repeat the last tool result. The Rust claude rig gained shared helpers for reading query() options, finishing turns on disk, and killing a sidecar.
9. README describes the tools and the switch.

Tests (all on the final commit)

• Vitest: pnpm run test:vitest run test/unit/claude-sidecar/ test/unit/shared/ws-protocol.fresh-agent-pane-context.test.ts test/unit/client/components/fresh-agent/FreshAgentView.test.tsx test/integration/providers/claude-cli-sim.test.ts test/integration/providers/claude-freshell-mcp.test.ts test/integration/providers/claude-cli-contract.test.ts test/unit/mcp/freshell-tool.test.ts --config config/vitest/vitest.config.ts: 26 files, 931 passed. This includes the pinned-CLI contract test, which reads /proc/<pid>/cmdline to confirm the token is not in the CLI's argv.
• Rust, every claude integration file in freshell-ws (15 files): 100 passed. This includes freshagent_claude_mcp_launch (8: create for both flavours, the setting changing between launches, the hosted lane, attach-resume, handoff resume for freshclaude and for kilroy, undo, fork). Each launch-test binary also ran 4 times in parallel: all green.
• cargo test -p freshell-freshagent --lib claude: 466 passed. --lib handoff: 103 passed. cargo test -p freshell-server --bin freshell-server claude_freshell_mcp: 2 passed.
• Cloud e2e (GCLOUD_ROBOT_REQUIRE=1 pnpm run test:e2e <specs> --project=chromium): 33 passed, 0 flaky, 0 failed, on the final commit ab3cd3ba4.
  • The new spec freshclaude-freshell-mcp-rust.spec.ts covers three cases. First, for freshclaude and for kilroy, the agent lists tabs through the real MCP server, and its own tab is in the list. Second, while the user is on another tab, an untargeted split-pane splits the agent's own pane and leaves the active tab alone. Third, with the setting turned off, the same call answers "No such tool available".
  • The four other specs that drive the simulator were rerun, because every freshclaude session in them now starts a real MCP child: fresh-agent-error-turn-attention, fresh-agent-rollback-rust, freshclaude-live-transcript-rust and freshclaude-fork-rust.
• cargo fmt --check, clippy on the touched crates, and pnpm run typecheck are clean.

Each fix was written test-first, and each test was seen failing before its fix. For the e2e default-target check, I also made the MCP tool ignore the pane context on purpose and confirmed the spec fails ("the agent's own tab gains the new pane": expected 2, received 1).

Follow-ups

1. Terminal panes do not follow the "Agent MCP server" switch yet (Agent MCP server toggle is saved but not honored by agent launches #446).
2. The browser sends its layout to the server after a debounce that restarts on every layout change. During the first second or so after the page loads, the agent API may therefore not list the browser's tabs yet. The e2e now waits for that sync. It only shows up when an agent calls the API within a second of page load.
3. test/unit/port/ws-contract-freeze.test.ts has 2 failures on main as well: the frozen server-message schema is missing modelEffortLevels. It is not touched here.
4. Three freshell-platform provider_environment tests count a node_modules directory found above the test's temp directory. A stray /tmp/node_modules/ws on the dev host made them fail in the pre-push gate. Not from this branch: the push ran with TMPDIR set to a clean directory, and they pass there. The tests should not depend on what sits above their temp directory.
5. managed_provider_sdk_tests.rs (feature managed-provider-qualification, needs an owned sandbox) was updated to import mcp-servers.mjs but was not run.

🤖 Generated with Claude Code