[FEATURE] IsReadInSession(path) query tool / --check-read-state flag

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code's Write and Edit tools require a prior Read invocation on the same file in the same session. This is a safety check — the agent should see what it's modifying before modifying it. The mechanism works, but it has two downstream issues that affect framework authors:

1. Read-state is opaque to the agent. There is no way to query "have I already Read this file in this session?" The agent must either remember (fragile across long sessions, especially after compaction), do a defensive Read (wasteful on large files), or hit the tool error and recover (most expensive — recovery typically loses 5–20k tokens to a redundant full Read).
2. The undocumented Read(limit:1) shortcut is load-bearing but invisible. State-tracking is per-file, not per-byte: Read(limit:1) registers the file at ~50 tokens and unblocks Edit calls anywhere in it. This is correct, valuable behavior — but it's nowhere in the docs. Framework authors who discover it ship discipline around it; those who don't, full-Read everything. The framework population stratifies by who happened to figure out an undocumented optimization.

The combined cost across the install base is non-trivial. Mycelium (an agent framework on Claude Code) estimates 10–50k tokens/session saved by enforcing Read(limit:1) for Edit-only paths. That's only the discipline-aware case; agents in the wild over-Read by significantly more.

Proposed Solution

A read-only query tool: IsReadInSession(path) -> bool

A cheap (single int response) tool that lets the agent query the harness's read-state directly. Eliminates defensive Reads, eliminates recovery loops, eliminates the need for framework-prose enforcement of the discipline.

Example agent flow:

if not IsReadInSession(".claude/canvas/purpose.yml"):
    Read(file_path=".claude/canvas/purpose.yml", limit=1)
Edit(file_path=".claude/canvas/purpose.yml", ...)

Token cost per check: ~10 tokens (call + bool response).
Token cost avoided: 50–20,000 tokens per unnecessary defensive Read.

Alternative Solutions

1. Surface read-state in existing tool response metadata. When an Edit or Read succeeds, include files_read_in_session: ["path1", "path2"] in the response so agents can build their own session memory cheaply.
2. Document the Read(limit:1) behavior officially. Lowest-cost change. Doesn't eliminate the cognitive load on the agent (still has to remember which files it has Read), but at least levels the playing field between discipline-aware and discipline-naive frameworks.
3. A --check-read-state-only parameter on Edit/Write that returns the read-state check result without attempting the modification. Same benefit as option 1, scoped to existing tools.
4. No change. Frameworks continue to enforce via prose. Acceptable cost, but compounds across the install base.

Of these, alternative 2 (documentation) should ship regardless of which path the team chooses — the current state is undocumented load-bearing behavior, which is a fragility risk independent of this request.

Priority

Medium - Would be very helpful

Feature Category

File operations

Use Case Example

Mycelium framework, canvas-write workflow. Mycelium is a theory-grounded agent harness for product development. Product knowledge lives in .claude/canvas/*.yml files (typically 25 files, ranging from 100 to 1000+ lines each). A typical workflow:

User: /mycelium:ice-score for solution opp-001-sol-A

Agent needs to:

1. Read .claude/canvas/opportunities.yml (locate the solution)
2. Read .claude/canvas/gist.yml (check existing ICE entries)
3. Edit .claude/canvas/gist.yml (append ICE score)
4. Edit .claude/canvas/opportunities.yml (update solution's confidence)

Steps 1 and 2 are necessary — the agent needs the content. Steps 3 and 4 are the actual work. Today, even with the Read(limit:1) discipline shipped, the agent has to remember it Read both files in steps 1–2 in order to skip a defensive Read(limit:1) before steps 3–4. After context compaction or in long sessions, that memory degrades.

With IsReadInSession(path):

• Step 3 prelude: IsReadInSession(gist.yml) → true → skip Read, go straight to Edit (~10 tokens overhead)
• Step 4 prelude: IsReadInSession(opportunities.yml) → true → same (~10 tokens overhead)
• Net cost: 20 tokens to confirm state vs 100 tokens for two defensive Read(limit:1) calls vs 30,000+ tokens for two full defensive Reads.

Multiply across a 30-turn Mycelium session touching 10–15 canvas files: 300+ tokens of state checks replace 50,000+ tokens of defensive Reads on the conservative discipline path, or 200,000+ tokens on the naive path.

Why it generalizes: any agent framework that builds discipline on top of Claude Code's file tools will hit this. Mycelium is one instance; the request scales with the harness-engineering paradigm.

References

• Verified behavior (2026-05-14): Read(limit:1) on a 5-line file followed by Edit targeting line 3 succeeded — state-tracking confirmed per-file, not per-byte.
• Mycelium v0.23.18 changelog entry documenting the discipline this request would simplify.
• Mycelium Check 31 (validator): mechanical enforcement of canvas-write Preflight presence across 22 skills.

Additional Context

_No response_