[BUG] Agent file relative paths resolved from project root instead of agent file location

Preflight Checklist

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

What's Wrong?

When an agent file located at .claude/agents/my-agent.md references a resource using a relative path, Claude Code resolves that path from the project root instead of from the agent file's own location. This causes agents to search outside the project directory and breaks portability.

Additionally, when a relative path appears as both inline code and a Markdown hyperlink, Claude ignores the hyperlink href entirely and only reads the inline code text — making the href useless as a canonical path reference.

What Should Happen?

Agent files are designed to be portable, installable entities — distributable via scripts and reusable across projects. If paths must be written relative to the project root (e.g. .claude/resources/my-resource.md), the agent file becomes:

1. Tied to a specific installation directory — breaking portability
2. Broken as documentation — links in the file no longer work when browsing the file outside its installed location (e.g. on GitHub, in an editor, or in another project)

The current behavior forces a choice between working links for humans and working paths for the agent — there should be no such conflict.

Environment

• Claude Code version: latest (npm install)
• OS: macOS (Apple Silicon M2)
• Shell: zsh

Suggested Fix

Resolve relative paths in agent files relative to the agent file's own location, not the project root. This is standard behavior in every module and document system (Node.js require, Python imports, HTML hrefs, CSS url()).

Alternatively, expose a variable such as __agent_dir__ that agents can use to construct absolute paths explicitly.

Error Messages/Logs

Steps to Reproduce

1. Create an agent file at .claude/agents/my-agent.md
2. Create a resource at .claude/resources/my-resource.md
3. In the agent file, reference the resource with a relative path:

Copy [`../resources/my-resource.md`](../resources/my-resource.md) to `process/output.md`

1. Invoke the agent
2. Claude resolves ../resources/ relative to the project root, escaping the project directory, instead of resolving it relative to .claude/agents/ where the agent file lives

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.83 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

iTerm2

Additional Information

_No response_