fix(agent): load agents_md on the claude harness via CLAUDE.md

[mmabrouk]

The bug

A harness: claude agent ignored its own instructions.agents_md. Configure one with
"You are a text summarizer, summarize the text, no questions back", paste a bare paragraph,
and it replies like the Claude Code CLI ("Is there something I can help with, a coding
task?") instead of summarizing.

It is a filename mismatch, not a dropped field:

• The runner writes agents_md to a file named AGENTS.md in the run cwd, for every
  harness (services/agent/src/engines/sandbox_agent/workspace.ts).
• Claude runs through @anthropic-ai/claude-agent-sdk, whose memory loader auto-loads
  CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md only. It never reads AGENTS.md.
• The ACP adapter already sets settingSources: ["user","project","local"], so a root
  CLAUDE.md would load. But none was written.

Net effect: for claude the instructions were written to disk and never read, so the agent
fell through to Claude Code's default coding persona. Pi is unaffected — Pi reads AGENTS.md.

The fix

Choose the instructions filename by harness in the file-materialization step:

• claude harness -> CLAUDE.md (the name the loader reads)
• pi / everything else -> AGENTS.md (unchanged)

The filename is a materialization detail, not a wire detail — the wire already carries the
neutral agentsMd string and says nothing about a filename. So this lands in the runner
(the sidecar), the wire contract and golden fixtures are untouched, and the Python harness
mapper does not change. The SDK's own materialization mirror (Harness._provisioning) gets
the same one-line rule so both paths agree.

Before / after (claude harness)

	file written in cwd	loaded by claude-agent-sdk?
before	AGENTS.md	no — instructions ignored
after	CLAUDE.md	yes — loaded as project memory

Out of scope (deliberately)

Delivering agents_md as an appended system prompt so it overrides the coding persona for
verb-less input is a separate, larger fix: sandbox-agent 0.4.2 strips _meta from
sessionInit, so the runner can't reach the adapter's append hook today. This PR makes
agents_md "considered as project memory" (the "ignored" bug); the persona-strength lever is
tracked in the design doc.

Tests

• services/agent/tests/unit/sandbox-agent-workspace.test.ts — new claude cases assert
  CLAUDE.md (and no AGENTS.md) on local + Daytona; existing Pi cases still assert
  AGENTS.md. Full runner suite: 402 passing; tsc --noEmit clean.
• sdks/python/oss/tests/pytest/unit/agents/test_environment_lifecycle.py — new claude case
  asserts _provisioning returns {"CLAUDE.md": ...}. Full agents unit suite: 454 passing
  (wire golden unchanged).

Verifying live

The sidecar image bakes the runner, so this is only live after a sidecar rebuild/restart.
After redeploy: create a harness: claude agent whose instructions are a summarizer persona,
send a bare paragraph with no instruction verb, and confirm it summarizes instead of asking
"how can I help?".

Design doc: docs/design/agent-workflows/projects/builder-agent-reliability/agentsmd-claude-fix/README.md

https://claude.ai/code/session_01WSp2LqKrEtXnm2fsPWuQWa

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 1, 2026 8:57pm

[coderabbitai]

Important

Review skipped

Draft detected.

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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 84461fd2-b577-483c-8982-1c7bc6c3d86a

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/agent-claude-agentsmd

---

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.}

[mmabrouk]

Design-doc-only PR (the implementation code is being stripped; this is the claude-harness agents_md fix design for your review).

Feedback I need before implementing: OK with the approach? For the claude harness, materialize the agent's instructions as CLAUDE.md (the filename the bundled claude-agent-sdk actually auto-loads) instead of AGENTS.md, done in the sidecar adapter, keeping AGENTS.md for the pi harnesses. That is the one-file fix for the bug where a claude agent never reads its instructions.

Approve and I'll implement.

[mmabrouk]

I agree.

[mmabrouk]

lgtm

[mmabrouk]

The runner half of this fix is now open as #5007 (base fix/infinite-loop-in-big-agents, since big-agents does not carry the services/agent/ tree). That PR adds services/agent/src/engines/sandbox_agent/workspace.ts (the harness-aware CLAUDE.md vs AGENTS.md write) plus its test.

This PR (#5000) now carries the SDK half: the Harness._provisioning filename mirror (interfaces.py) + its test, alongside the 5 design docs. Label flipped to implementing.

[mmabrouk]

Rebased onto big-agents f8765a9b89 and folded in the runner half. This PR now carries BOTH halves of the agents_md/CLAUDE.md fix:

• SDK half: interfaces.py filename mirror + test_environment_lifecycle.py.
• Runner half: harness-aware instructionsFile in services/runner/src/engines/sandbox_agent/workspace.ts (claude -> CLAUDE.md, every other harness -> AGENTS.md) + its test, on the renamed services/runner path.

#5007 (which had the runner half on the stale services/agent path) is closed in favor of this. Please review: the harness-aware filename branch in workspace.ts (both the Daytona and local write paths) and the SDK filename mirror.