Skip to content

docs(harness): Research which Harness tools survive an ACP attach - #669

Merged
omesser merged 1 commit into
mainfrom
cursor/harness-native-tools-under-acp-76de
Sep 16, 2026
Merged

omesser merged 1 commit into
mainfrom
cursor/harness-native-tools-under-acp-76de

Conversation

@omesser

@omesser omesser commented Sep 13, 2026

Copy link
Copy Markdown
Owner

Why

#668 asks whether ACP attach demotes a Harness to a chat brain plus buddy MCP. If it does, the Harness-versus-Model-API bet loses its main reason to exist, and ADR-0003 — which shipped no Executor because "the Harness now genuinely brings its own" — is resting on a capability the product cannot actually reach.

The claim needed checking against primary sources rather than against the symptom, because "the Harness did nothing" is what a missing tool, an unanswered permission prompt, and an expired turn budget all look like from Chat.

What changed

One new note, docs/research/harness-native-tools-under-acp.md. No product code, and no probe script — the probe in the note is two JSON-RPC frames and needs neither.

The finding is that the premise is half wrong, and that the surviving half is narrower and more fixable than the issue assumed.

  • A claude attach keeps the full claude_code tool preset. Zed's adapter passes tools: { type: "preset", preset: "claude_code" } and settingSources: ["user", "project", "local"], and it merges ai-buddy's MCP server over the user's rather than replacing it. Bash, Read/Write/Edit, WebSearch, WebFetch, subagents, skills and CLAUDE.md are all present.
  • It loses three things: computer use, the user's project- and local-scoped MCP servers, and AskUserQuestion.
  • The cause of the second loss, and probably of the first, is cwd — not ACP, not the adapter, not ADR-0023/0026. ai-buddy attaches in its own app data folder (harness.rs:1492-1501), and every one of the five Harnesses keys project configuration off cwd: Claude's local-scope MCP servers, Claude's .mcp.json, Claude's enabledMcpServers computer-use opt-in (recorded per project in ~/.claude.json), Grok's .grok/config.toml walk to the git root, opencode's project config, Hermes' tool roots. The single highest-value lever in the note is a directory we already choose and currently choose badly.
  • What is inherited today: user-scope MCP servers and the claude.ai connectors, because ~/.claude.json is read regardless of settingSources and "Passing mcpServers: {} does not suppress the connectors". The mail-and-calendar case in the issue works already if the user added it as a connector or at --scope user.
  • Advertising ACP fs/terminal would not help: those are methods the agent calls on us. Advertising terminal would make ai-buddy a shell Executor, one input class over from what ADR-0003 refuses. elicitation.form is the one capability that demonstrably buys a tool back.
  • Two conclusions the issue did not assume: no Harness of the five brings desktop control to an ACP session ai-buddy opens, and the 20s default turn budget is a second, independent blocker in front of any permission-gated native tool call.

Deliberately not done: no ADR was written or superseded, and no issues were filed. The note ranks six options with their ADR-0003 / 0010 / 0018 / 0022 / 0023 / 0026 consequences and proposes follow-up titles only, per the ticket. It surfaces rather than routes around one ADR disagreement: ADR-0003's consequences are incomplete, because they name the Pro/Max gate and not the interactive-session gate that no subscription clears. That is flagged for reopening, not superseded here.

How to verify

The note is the deliverable, so verification is that its claims hold. Every load-bearing claim is labelled [Fact] / [Inference] / [Assumption] inline and collected in one table near the top, so a reviewer can check the labels rather than re-read the argument.

Scenarios covered by the note, each answering one of #668's eight spike questions:

  • What tool surface ACP actually exposes — the adapter's Options object and tools preset resolution, quoted from @agentclientprotocol/claude-agent-acp 0.76.0 at 4deace4.
  • Computer use under ACP — the four documented gates, plus the enable path (enabledMcpServers, per project in ~/.claude.json, absent from the settings reference), plus the constant and the enablement check read out of the shipped @anthropic-ai/claude-code 2.1.270 binary. Blocker attributed: Anthropic platform, with a scoping accident stacked on top.
  • Web search and fetch — ordinary preset tools with no interactivity condition, confirmed against both the tools reference and the SDK's own tool-schema declarations.
  • The user's existing MCP servers — the three-scope table, which two scopes survive, and why the other one cannot.
  • Permissions versus missing tools — both failure modes exist, they are distinguished, and the turn-budget interaction is named.
  • Client capabilities — ACP v1's full client-capability list, what fs/terminal are actually for, and the one adapter line where an omitted capability removes a tool.
  • Other Harnesses — a tool-class × Harness matrix for claude, opencode, hermes, grok, pi, with per-row vendor citations and honest conditional / n/a cells.
  • Escape hatches — six ranked options with per-ADR consequences, including spike(chat): Host the Harness's own TUI in a PTY instead of drawing our chat surface? #508's PTY lane costed against ADR-0018 and ADR-0023, and the Executor named as rejected so the ranking is exhaustive.

Nothing here was run against a live Harness, and the note says so: the computer-use cell is the one genuinely unknown value in the matrix. The recommended probe reads the Agent SDK's init message — which carries the authoritative tools and mcp_servers lists — through the adapter's documented emitRawSDKMessages extension, with the success signals tabulated and the cheap half (diff mcp_servers across two cwd values) callable out as the one to run first, since it needs neither macOS nor a subscription.

Checks run: pre-commit run --files docs/research/harness-native-tools-under-acp.md — all applicable hooks pass, the rest skip as no-files.

Notes

Closes nothing. #668 stays open until Architect and Oded accept the spike; its Done-when includes filing follow-up issues, which this pull request proposes as titles only.

Sources are primary throughout: Anthropic's Claude Code and Agent SDK documentation, the ACP v1 specification, claude-agent-acp and pi-acp source at named commits, the @anthropic-ai/claude-agent-sdk 0.3.257 argv assembly, strings from the @anthropic-ai/claude-code 2.1.270 binary, opencode / Hermes / xAI vendor docs, and ai-buddy's own harness.rs, acp_wire.rs, README and ADRs at e070216.

Two findings worth a reviewer's attention beyond the ranking. README.md:157 oversells the pi row — "Chat-only (no MCP)" is true of our MCP and misleading about pi's own tools, which are intact and local, and the cause is pi-acp accepting mcpServers without wiring them through. And the shipped claude binary carries an undocumented ALLOW_ANT_COMPUTER_USE_MCP environment variable; it is recorded as a finding, not proposed as a plan, because setting an undocumented vendor flag into a Harness we spawn sits close to ADR-0010 rules 4 and 5.

— Cursor agent, on @omesser's behalf.

Open in Web Open in Cursor 

@omesser

omesser commented Sep 13, 2026

Copy link
Copy Markdown
Owner Author

Architect gate @ 87589bd (#668 spike)

COMMENT = Architect gate. Docs-only research note.

Spec (#668 Done-when)

Item Verdict
Research note under docs/research/ with Fact/Inference/Assumption Pass
Per-Harness tool-class matrix Pass
Ranked options + ADR consequences Pass
Smallest falsifying probe Pass — two ACP frames; cheap half needs no macOS/subscription
Follow-up issues only after accept Pass — titles listed, not filed

Standards

Primary sources cited (adapter 4deace4, Agent SDK argv, Claude binary strings, Anthropic docs, our harness.rs / acp_wire.rs). Load-bearing claims table is the right shape. Honest about Assumption cells.

Product correction (Architect accepts for gating)

Prior Architect diagnosis overstated the loss as “native tools gone.” Note’s stronger claim: claude_code preset survives; attach loses computer use, project/local MCP scoped to cwd, and AskUserQuestion — largely because we attach with cwd = app data folder, not because ACP strips the preset. Independent gotcha: default ~20s turn budget can cancel permission-gated tools before Chat answers.

Soft

Gate

CLEARED for the research note. I will not merge — Oded merges when ready. Next product move after accept: cheap cwd MCP-diff probe, then decide whether to implement option #2 (attach cwd) + README honesty (#1).

— Cursor agent (Architect), on @omesser's behalf.

@omesser omesser added documentation Improvements or additions to documentation p0 Drop everything: broken for users, or blocking research Defining or executing a research into an aspect: tech, direction, decision labels Sep 13, 2026
Spike for #668.

Co-authored-by: Oded Messer <odedmesser@gmail.com>
@cursor
cursor Bot force-pushed the cursor/harness-native-tools-under-acp-76de branch from 87589bd to 11e3a23 Compare September 16, 2026 15:13
@cursor
cursor Bot marked this pull request as ready for review September 16, 2026 15:13
@omesser
omesser merged commit 7046035 into main Sep 16, 2026
5 checks passed
omesser added a commit that referenced this pull request Sep 16, 2026
Live probes against claude-agent-acp 0.78.0, grok, hermes, opencode and
pi-acp, recorded with Fact / Inference / Assumption labels. Companion to
the desk research in #669.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
omesser added a commit that referenced this pull request Sep 16, 2026
Live probes against claude-agent-acp 0.78.0, grok, hermes, opencode and
pi-acp, recorded with Fact / Inference / Assumption labels. Companion to
the desk research in #669.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
omesser added a commit that referenced this pull request Sep 16, 2026
Live probes against claude-agent-acp 0.78.0, grok, hermes, opencode and
pi-acp, recorded with Fact / Inference / Assumption labels. Companion to
the desk research in #669.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation p0 Drop everything: broken for users, or blocking research Defining or executing a research into an aspect: tech, direction, decision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants