Subagents sometimes read node_modules instead of source files

Description

When spawning subagents (via the Agent tool) to perform bulk file edits across a codebase, subagents sometimes start reading files in node_modules/ instead of the source files they were instructed to modify. This appears to happen when the agent is looking up component APIs or type definitions — it resolves the import path into node_modules and starts reading package internals rather than staying within the src/ directory it was scoped to.

Context

I was using Claude Code (Opus) to migrate an admin app from raw Chakra UI imports to a custom component library (@televet/kibble-ui). I spawned two parallel subagents with detailed instructions listing specific source files to modify under apps/admin/src/. Both agents began reading files in node_modules/@televet/kibble-ui/ and node_modules/@chakra-ui/ to understand component APIs — even though the prompt already contained the full API documentation they needed and explicitly listed only src/ files to modify.

Visibility concern

The parent agent has no real-time visibility into what a background subagent is doing. I only noticed because I was watching the terminal output and saw node_modules paths scrolling by. The parent agent had no way to detect or prevent this until I flagged it manually, at which point I sent a SendMessage to redirect them. By that time they had already burned significant context and token budget reading package internals.

Expected behavior

Subagents should stay within the file scope described in their prompt. When a prompt says "modify ONLY these files under src/", the agent should not autonomously decide to explore node_modules/ for supplementary information — especially when that information was already provided in the prompt.

Suggested improvements

• A way to scope subagent file access (e.g. allowedPaths parameter on the Agent tool)
• Or at minimum, a heuristic that discourages reading node_modules/ unless explicitly asked
• Better parent visibility into subagent activity (e.g. a way to see what tools a background agent is calling)

Environment

• Claude Code CLI
• Model: Opus 4.6 (1M context)
• Platform: macOS