Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

When .claude/agents/<name>.md exists at both an ancestor directory (e.g. repo root) and a closer directory in the cwd ancestor chain, the /agents UI displays the closer (deeper) agent's content (description and system prompt). However, when the agent is invoked at runtime — via claude --agent <name> or via the Task tool — Claude Code executes the ancestor (root) file's content.

The two sources of truth disagree. UI shows one file's content; runtime runs another file's content. There is no error, warning, or visible signal that the file shown to the user is not the file being invoked.

This contradicts the documented closest-wins-per-name behavior for agent discovery, and is opposite to how same-name resolution works for skills and CLAUDE.md.

What Should Happen?

Either:

1. Closest wins (preferred, matches docs and skills behavior): the closer (deeper) .claude/agents/<name>.md should be used at runtime, matching what /agents displays. Project-level files override ancestor-level files of the same name.
2. Or, if ancestor-wins is intentional: the /agents UI should reflect runtime behavior — display the file that will actually be invoked. Documentation should also state explicitly that ancestor-level same-named agents take precedence over closer ones.

Either way, the UI and runtime must agree. Today's silent disagreement makes any same-name override pattern unreliable.

Related issues for context:

• #26489 — [FEATURE] skills/, agents/, commands/ should traverse parent directories like CLAUDE.md does (broader traversal nconsistency)

• #58950 — [DOCS] Clarify recursive subdirectory discovery in ~/.claude/agents/ and .claude/agents/

Error Messages/Logs

Steps to Reproduce

 # 1. Create test repo with two .claude/agents/ levels containing same-named agents
  mkdir -p /tmp/agent-discovery-test/root-app/sub-project/.claude/agents
  cd /tmp/agent-discovery-test/root-app
  mkdir -p .claude/agents

  # Ancestor-level agent
  cat > .claude/agents/root-only.md <<'EOF'
  ---
  name: root-only
  description: test agent for discovery verification
  ---
  You are a test agent. Reply: "I am ROOT."
  EOF

  # Closer (project-level) agent — same name, different content
  cat > sub-project/.claude/agents/root-only.md <<'EOF'
  ---
  name: root-only
  description: test agent for discovery verification
  ---
  You are a test agent. Reply: "I am PROJECT."
  EOF

2. Launch Claude from sub-project/

  cd sub-project
  claude --agent root-only

3. In the session, prompt:

say your line

Expected output: I am PROJECT. (the closer agent's content)

Actual output: I am ROOT. (the ancestor agent's content)

Additional verification:

• Plain launch (claude without --agent) followed by Task tool invocation produces the same result — I am ROOT.
• Running /agents in the session and viewing root-only shows the project-level file's description ("project-level override" if you set it that way) and system prompt — content that does not match what runtime executes.
• When asked, Claude itself reports: "the system's available-agents list showed the root description; the project-level file appears not to have been picked up or was shadowed."

The bug is reproducible across both invocation paths (--agent flag and Task tool) and is independent of session caching — observed on fresh sessions after clearing ~/.claude/projects/<encoded-path>/ between runs.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.142

Platform

AWS Bedrock

Operating System

macOS

Terminal/Shell

iTerm2

Additional Information

No response