ToolSearch injection does not load MCP tools inClaude Code custom agent sessions (--agent flag)

[Dany-86]

📋 Pre-flight Checks

• I have searched existing issues and this is not a duplicate
• I understand this issue needs status:approved before a PR can be opened

📝 Bug Description

The UserPromptSubmit hook fires correctly and injects the ToolSearch instruction (visible in system context). The agent acknowledges it. But calling any mcp__engram__* tool from within a Claude Code custom agent session (--agent flag) returns "No such tool available" — the tools never load via ToolSearch.

The same setup works correctly in the main Claude Code session (no --agent flag).

🔄 Steps to Reproduce

1. Install the engram plugin: claude plugin install engram
2. Create a custom agent at .claude/agents/my-agent.md (with or without a tools: frontmatter field)
3. Open a session with: claude --agent my-agent
4. Send any message — the ToolSearch injection appears in system context (hook is firing)
5. Agent attempts to call mcp__engram__mem_context or any other engram tool
6. Result: "No such tool available"

✅ Expected Behavior

MCP tools loaded via ToolSearch should be available in custom agent sessions (--agent), the same way they are in the main Claude Code session.

❌ Actual Behavior

The ToolSearch instruction is injected correctly but the MCP tools are never loaded. Any call to mcp__engram__* returns "No such tool available".

Running claude mcp list from within the agent session shows engram as Connected — the server is reachable, but the tools can't be invoked.

Operating System

Windows

Engram Version

1.15.7

Agent / Client

Claude Code

📋 Relevant Logs

💡 Additional Context

Tested and ruled out:

• Removing the tools: frontmatter field from the agent — no effect
• Adding mcpServers: [engram] to agent frontmatter — no effect
• Deleting duplicate MCP registrations (project .mcp.json, ~/.claude/mcp/engram.json) and clean reinstall — same result

The engram HTTP server is running and reachable. CLI commands (engram save, engram search, engram context) work correctly from Bash.

Workaround: calling the engram CLI directly via Bash inside custom agent instructions works as a fallback.

This may be a Claude Code platform limitation where ToolSearch doesn't propagate MCP tool loading into --agent sessions, but reporting here since it affects the plugin's core functionality for anyone using custom agents.

[Dany-86]

Update: after more investigation, found two related Claude Code bugs that together could explain the behavior.

Bug 1 — anthropics/claude-code#56551: plugin MCP servers ignore the alwaysLoad annotation — tools are always deferred behind ToolSearch regardless of configuration. We also tested the workaround mentioned in that issue (ENABLE_TOOL_SEARCH: auto in settings.json) — it had no effect, likely because engram's agent profile has 13 tools, above the threshold for eager loading.

Bug 2 — anthropics/claude-code#56398: named custom agents in .claude/agents/*.md don't get working tool access at runtime — the agent narrates tool interactions in text instead of actually invoking them. This affects both built-in tools and MCP tools, and applies regardless of how the MCP server is registered.

Tested registration methods that all produced the same result:

• Plugin marketplace (enabledPlugins)
• claude mcp add --scope user
• engram setup claude-code (~/.claude/mcp/engram.json)

In all cases the MCP server shows as Connected in /mcp but tools are not invocable from --agent sessions.

Leaving this open in case engram wants to track the upstream fixes or implement a mitigation.