Sub-agent dispatch injects hardcoded instructions that conflict with custom agent prompts (.claude/agents/)

Summary

When Claude Code dispatches a sub-agent (via the Agent tool), it appends hardcoded "extra notes" to the launch prompt. These notes can directly contradict instructions in the user's custom agent definition (.claude/agents/*.md), with no mechanism to override or disable them.

Environment

• Claude Code version: latest
• Platform: macOS

The injected notes

Every sub-agent receives the following trailing notes appended to whatever prompt the orchestrator provides:

Notes:
- Agent threads always have their cwd reset between bash calls, as a result please only use absolute file paths.
- In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.
- For clear communication with the user the assistant MUST avoid using emojis.
- Do not use a colon before tool calls. Text like "Let me read the file:" followed by a read tool call should just be "Let me read the file." with a period.

These are also visible in Piebald-AI/claude-code-system-prompts as agent-prompt-task-tool-extra-notes.md.

The conflict

Custom agent prompts in .claude/agents/*.md can require output that directly contradicts these injected notes. For example:

• An agent prompt may specify output templates containing emoji characters (as markers, identifiers, or status indicators)
• The injected note says: "the assistant MUST avoid using emojis" — blanket prohibition
• The agent prompt says: use specific emoji in output — explicit requirement

The sub-agent sees both instructions and must choose. The injected note uses strong "MUST" language positioned at the end of the prompt (recency bias), so it often wins over the user-defined agent prompt.

Why this is a problem

1. No override mechanism: Users cannot disable or customize the injected notes. The sub-agents documentation says "Subagents receive only this system prompt (plus basic environment details like working directory), not the full Claude Code system prompt" — but these extra notes are injected silently and are not mentioned in the docs.

1. Semantic mismatch: The emoji note says "for clear communication with the user" but sub-agents don't communicate with users — they return output to the orchestrating agent. The instruction assumes a context (user-facing output) that doesn't apply to sub-agents being orchestrated programmatically.

1. Undermines custom agent definitions: The purpose of .claude/agents/ is to give users control over sub-agent behavior. Injecting hardcoded instructions that can override the user's agent prompt defeats this purpose.

1. Silent failure: When a sub-agent drops content required by the agent prompt (because it's following the injected note instead), there's no warning. The orchestrating agent receives output that doesn't match what the agent prompt specified, with no indication of why.

Reproduction steps

1. Create a custom agent in .claude/agents/ whose output template includes emoji:

---
name: status-reporter
description: Reports status of tasks
tools: Read, Glob, Grep
---
When reporting results, always prefix your output with:
- ✅ for success
- ❌ for failure  
- ⚠️ for warnings

1. Ask Claude to use this agent for a task
2. Observe that the sub-agent often omits the required emoji prefixes, because the injected note tells it to "MUST avoid using emojis"

Suggested approaches

Option A: Don't inject notes that conflict with user-defined agent prompts. If a custom agent definition exists in .claude/agents/, its instructions should take precedence over generic injected notes.

Option B: Make the extra notes configurable. Allow users to override or disable specific injected notes via a frontmatter field in the agent definition (e.g., disableExtraNotes: true or extraNotes: [absolute-paths]).

Option C: Scope the notes appropriately. The emoji note could be scoped to agents without custom prompts, or rephrased to "prefer avoiding emojis unless your agent prompt specifies otherwise."

Related issues

• #25327 — CLI wrapper/system-reminder injections waste tokens and break agent workflows
• #24415 — Allow overriding builtin tool description components
• #18560 — system-reminder instructing Claude Code not to follow CLAUDE.md instructions
• #30634 — System plan mode instructions override user CLAUDE.md workflow directives

These report the same class of problem (system-injected instructions conflicting with user configuration) in different contexts. This issue is specifically about the sub-agent dispatch extra notes conflicting with custom agent definitions.