Project-scope agent in .claude/agents/ intermittently fails to register at session start (same file, same version — nondeterministic)

Update (2026-07-18): the intermittent non-registration has now persisted across 7 consecutive fresh sessions — one more than the 6 noted in the original report. Same conditions each time: car-cold is absent from the session's available-agents list at start, the def on disk is byte-identical (same git blob), Claude Code 2.1.196 is unchanged, and the sibling .claude/agents/ defs register normally in the very same sessions. No manual change on our side between sessions.

Three new findings since the original report

We've kept observing this across additional fresh sessions and instrumented it with control agents. Three findings that should materially narrow the search:

(1). Both of our empty-allowlist agents drop together (lockstep) at cold start

We added a trivial diagnostic twin, probe-empty, with the same empty allowlist as the failing agent:

---
name: probe-empty
description: diagnostic registration-control twin (referenced by nothing, spawned by nothing)
tools: []
model: sonnet
---

It is referenced by no workflow and spawned by nothing — it exists only to be read from the session's available-agents list. In every non-registering session since, both car-cold and probe-empty are absent together — they flicker in lockstep. Meanwhile sibling defs in the same directory with non-empty allowlists (playwright-test-planner/generator/healer) register in those same sessions. This points at the empty tools: [] allowlist as the shared trigger, independent of the rest of the car-cold def's content.

We've now added a third control, probe-anchor, identical in shape to probe-empty but with a minimal non-empty repo-inert allowlist (tools: [WebSearch]) — differing in exactly one variable. If it registers reliably in the sessions where both tools: [] agents are absent, that both confirms the empty-allowlist trigger and validates a non-empty allowlist as the workaround. (Data forthcoming.)

(2). A byte-identical delete + recreate does NOT re-register an already-known path (only restart works)

Within a failing session we deleted .claude/agents/car-cold.md and recreated it byte-for-byte (verified: git hash-object before == after == 1130aac5, working tree clean). Across three subsequent turn boundaries, car-cold never registered. So the "touch/recreate the file" workaround does not clear an already-failed registration for a given path — a full Claude Code restart is the only thing that clears it. This suggests the registration decision for a known path is made once at session load and is not revisited on later filesystem changes to that same path.

(3). Dynamic filesystem pickup is real but transient/unstable in both directions

The registry-update channel is demonstrably live during these sessions: creating a brand-new agent path (probe-empty) pushed an "agent added" notification mid-session, and deleting it pushed an "agent removed" notification. But that same live channel never emitted a "car-cold now available" notification for the already-known path in finding #2. And probe-empty's own dynamic registration was transient — it registered on creation, then dropped again later in the same session with no file change. So dynamic pickup fires for new paths but is unstable, and does not rescue an already-known path that failed to register at load.

Net

• The def is byte-constant across working and failing sessions (git-proven, from the original report), so this is not a frontmatter-content problem.
• The one structural variable that co-varies with the failure is the empty tools: [] allowlist (finding 1).
• Registration for a known path appears decided at first load and not re-evaluated on later same-path filesystem changes (finding 2), while new paths are picked up dynamically but unstably (finding 3).

Question

Does the loader treat an empty tools: [] array differently from a populated one (e.g. empty-array-as-missing/invalid, dropped on some load orderings), and is registration for a given agent path memorized at session start such that a later byte-identical rewrite of that path won't re-trigger it?

Root cause found: CRLF line endings in an agent-definition file silently break its registration.

Summary: on Windows with core.autocrlf=true, an agent definition under .claude/agents/*.md that lands in the working tree with CRLF line endings is silently skipped at agent-type registration — the type never appears in the session's available-agent list, and there is no warning or error. The identical file with LF endings registers normally. This fully explains the non-deterministic registration we reported earlier in this issue: it was never non-deterministic per session — it tracked the on-disk line endings of each def, which drifted to CRLF via autocrlf on some checkouts.

Evidence — a 4-arm controlled experiment

All four are trivial agent defs in the same .claude/agents/ directory, in the same session:

| Arm | Line endings | tools: format | Registered? |
|-----|--------------|-----------------|-------------|
| car-cold (the real one) | CRLF | flow-array [] | ❌ absent |
| probe-empty (control) | CRLF | flow-array [] | ❌ absent |
| probe-anchor (control) | CRLF | flow-array [WebSearch] | ❌ absent |
| probe-clone (control) | LF | bare comma-list | ✅ present |

• probe-clone is a byte-for-byte copy of a known-registering def (playwright-test-planner.md) with only name: changed — created LF-preserving. It registers.
• The three CRLF arms register together in lockstep across many fresh sessions and never register at cold start.
• Ruled out as the discriminator (both groups share these, or they don't split cleanly): BOM (none present), model:/color: fields, description length, file size, and load/sort order.
• Ground-truth byte check (git ls-files --eol + raw 0x0D count): the three absent arms are pure-CRLF (19 / 12 / 13 CR bytes); every registered def is pure-LF (0 CR bytes). A perfect CRLF-absent / LF-present split.

The common trigger on Windows: a repo with core.autocrlf=true and no .gitattributes rule pinning *.md to eol=lf. Files authored or checked out as CRLF in the working tree then fail to register, while older LF files in the same directory keep working — which reads exactly like non-determinism.

Our fix (workaround)

Add a .gitattributes rule forcing LF for agent defs, and renormalize the working tree:

.claude/agents/*.md text eol=lf

After that, the previously-CRLF defs register at cold start.

Request

The workaround shouldn't be necessary, and the silent-skip is the real hazard. Please either:

1. Make the agent-def frontmatter loader tolerant of CRLF (normalize line endings before parsing), or
2. At minimum, emit a LOUD warning when a def in .claude/agents/ is found but skipped (parse failure, CRLF, malformed frontmatter, etc.) — anything but a silent omission from the available-agent list.

A silent skip means a gate/agent that a workflow depends on can be un-runnable in a session with no indication why. A one-line "skipped .claude/agents/car-cold.md: <reason>" at startup would have turned a multi-session investigation into a 10-second diagnosis.

---

DRAFT — closing comment for anthropics/claude-code#78917

DRAFT ONLY. Steve posts this himself. CC does not submit to GitHub without explicit per-action authorization ([[feedback_no_boundary_crossing_without_authorization]]). Paste the body below (between the rules) as a new comment on #78917.

---

Root cause found: CRLF line endings in an agent-definition file silently break its registration.

Summary: on Windows with core.autocrlf=true, an agent definition under .claude/agents/*.md that lands in the working tree with CRLF line endings is silently skipped at agent-type registration — the type never appears in the session's available-agent list, and there is no warning or error. The identical file with LF endings registers normally. This fully explains the non-deterministic registration we reported earlier in this issue: it was never non-deterministic per session — it tracked the on-disk line endings of each def, which drifted to CRLF via autocrlf on some checkouts.

Evidence — a 4-arm controlled experiment

All four are trivial agent defs in the same .claude/agents/ directory, in the same session:

| Arm | Line endings | tools: format | Registered? |
|-----|--------------|-----------------|-------------|
| car-cold (the real one) | CRLF | flow-array [] | ❌ absent |
| probe-empty (control) | CRLF | flow-array [] | ❌ absent |
| probe-anchor (control) | CRLF | flow-array [WebSearch] | ❌ absent |
| probe-clone (control) | LF | bare comma-list | ✅ present |

• probe-clone is a byte-for-byte copy of a known-registering def (playwright-test-planner.md) with only name: changed — created LF-preserving. It registers.
• The three CRLF arms register together in lockstep across many fresh sessions and never register at cold start.
• Ruled out as the discriminator (both groups share these, or they don't split cleanly): BOM (none present), model:/color: fields, description length, file size, and load/sort order.
• Ground-truth byte check (git ls-files --eol + raw 0x0D count): the three absent arms are pure-CRLF (19 / 12 / 13 CR bytes); every registered def is pure-LF (0 CR bytes). A perfect CRLF-absent / LF-present split.

The common trigger on Windows: a repo with core.autocrlf=true and no .gitattributes rule pinning *.md to eol=lf. Files authored or checked out as CRLF in the working tree then fail to register, while older LF files in the same directory keep working — which reads exactly like non-determinism.

Our fix (workaround)

Add a .gitattributes rule forcing LF for agent defs, and renormalize the working tree:

.claude/agents/*.md text eol=lf

After that, the previously-CRLF defs register at cold start.

Request

The workaround shouldn't be necessary, and the silent-skip is the real hazard. Please either:

1. Make the agent-def frontmatter loader tolerant of CRLF (normalize line endings before parsing), or
2. At minimum, emit a LOUD warning when a def in .claude/agents/ is found but skipped (parse failure, CRLF, malformed frontmatter, etc.) — anything but a silent omission from the available-agent list.

A silent skip means a gate/agent that a workflow depends on can be un-runnable in a session with no indication why. A one-line "skipped .claude/agents/car-cold.md: <reason>" at startup would have turned a multi-session investigation into a 10-second diagnosis.

---

Root cause found: CRLF line endings in an agent-definition file silently break its registration.

Summary: on Windows with core.autocrlf=true, an agent definition under .claude/agents/*.md that lands in the working tree with CRLF line endings is silently skipped at agent-type registration — the type never appears in the session's available-agent list, and there is no warning or error. The identical file with LF endings registers normally. This fully explains the non-deterministic registration we reported earlier in this issue: it was never non-deterministic per session — it tracked the on-disk line endings of each def, which drifted to CRLF via autocrlf on some checkouts.

Evidence — a 4-arm controlled experiment

All four are trivial agent defs in the same .claude/agents/ directory, in the same session:

| Arm | Line endings | tools: format | Registered? |
|-----|--------------|-----------------|-------------|
| car-cold (the real one) | CRLF | flow-array [] | ❌ absent |
| probe-empty (control) | CRLF | flow-array [] | ❌ absent |
| probe-anchor (control) | CRLF | flow-array [WebSearch] | ❌ absent |
| probe-clone (control) | LF | bare comma-list | ✅ present |

• probe-clone is a byte-for-byte copy of a known-registering def (playwright-test-planner.md) with only name: changed — created LF-preserving. It registers.
• The three CRLF arms register together in lockstep across many fresh sessions and never register at cold start.
• Ruled out as the discriminator (both groups share these, or they don't split cleanly): BOM (none present), model:/color: fields, description length, file size, and load/sort order.
• Ground-truth byte check (git ls-files --eol + raw 0x0D count): the three absent arms are pure-CRLF (19 / 12 / 13 CR bytes); every registered def is pure-LF (0 CR bytes). A perfect CRLF-absent / LF-present split.

The common trigger on Windows: a repo with core.autocrlf=true and no .gitattributes rule pinning *.md to eol=lf. Files authored or checked out as CRLF in the working tree then fail to register, while older LF files in the same directory keep working — which reads exactly like non-determinism.

Our fix (workaround)

Add a .gitattributes rule forcing LF for agent defs, and renormalize the working tree:

.claude/agents/*.md text eol=lf

After that, the previously-CRLF defs register at cold start.

Request

The workaround shouldn't be necessary, and the silent-skip is the real hazard. Please either:

1. Make the agent-def frontmatter loader tolerant of CRLF (normalize line endings before parsing), or
2. At minimum, emit a LOUD warning when a def in .claude/agents/ is found but skipped (parse failure, CRLF, malformed frontmatter, etc.) — anything but a silent omission from the available-agent list.

A silent skip means a gate/agent that a workflow depends on can be un-runnable in a session with no indication why. A one-line "skipped .claude/agents/car-cold.md: <reason>" at startup would have turned a multi-session investigation into a 10-second diagnosis.

---