Feature Request: Option to disable parent directory traversal for CLAUDE.md discovery

Problem Statement

When using the Claude Agent SDK with settingSources: ['project'] in a subrepo within a monorepo structure, the SDK picks up CLAUDE.md files from parent directories that are not relevant to the current project.

My Setup

/monorepo                    # Parent repo

├── CLAUDE.md                # ❌ Gets loaded (unwanted)

├── /another-project

│   └── CLAUDE.md            # (sibling, not loaded)

└── /my-subrepo              # ← I run SDK here with cwd set to this path

    ├── CLAUDE.md            # ✅ Should be loaded (wanted)

    ├── .claude/

    │   ├── settings.json    # ✅ Should be loaded (wanted)

    │   ├── skills/          # ✅ Should be loaded (wanted)

    │   └── agents/          # ✅ Should be loaded (wanted)

    └── src/

Current Behavior

When I configure the SDK like this:

const result = query({

  prompt: "...",

  options: {

    cwd: "/monorepo/my-subrepo",

    settingSources: ['project'],  // or ['local']

    // ...

  }

});

The SDK loads:

• ✅ /monorepo/my-subrepo/CLAUDE.md


• ✅ /monorepo/my-subrepo/.claude/settings.json


• ✅ /monorepo/my-subrepo/.claude/skills/*


• ❌ /monorepo/CLAUDE.md (parent - unwanted)


• ❌ Could even traverse further up to grandparent directories

According to the documentation:

"Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory / and reads any CLAUDE.md or CLAUDE.local.md files it finds."

This parent traversal behavior is useful for the CLI in monorepo workflows, but problematic for SDK usage where I want isolated, predictable behavior for a specific subrepo.

Why This Is a Problem

1. Context pollution: Parent CLAUDE.md may contain instructions that conflict with or are irrelevant to the subrepo


2. Unpredictable behavior: Moving the subrepo or running from different directory structures changes what gets loaded


3. No workaround: I cannot use settingSources: ['project'] to load skills/settings without also triggering parent CLAUDE.md traversal


4. SDK isolation principle violated: The SDK migration guide states that v0.1.0 was designed for "predictable behavior independent of local filesystem configurations" - but parent traversal breaks this

Current Workarounds (All Unsatisfactory)

Workaround | Problem
-- | --
settingSources: [] + programmatic definitions | Loses skill auto-discovery, must manually define everything
settingSources: [] + plugins | Complex setup, skills still need specific paths
Symlinks | Fragile, doesn't work in all environments (CI, containers)
Remove parent CLAUDE.md | Not possible - other projects/teams use it

Proposed Solution

Add an option to control memory discovery scope when settingSources includes 'project' or 'local'.

Option A: New memoryScope option

const result = query({

  prompt: "...",

  options: {

    cwd: "/monorepo/my-subrepo",

    settingSources: ['project'],

    memoryScope: 'cwd-only',  // NEW: 'cwd-only' | 'traverse-parents' (default)

  }

});

Option B: Boolean flag

const result = query({

  prompt: "...",

  options: {

    cwd: "/monorepo/my-subrepo",

    settingSources: ['project'],

    disableParentMemoryTraversal: true,  // NEW

  }

});

Option C: Granular control

const result = query({

  prompt: "...",

  options: {

    cwd: "/monorepo/my-subrepo",

    settingSources: ['project'],

    memoryDiscovery: {

      traverseParents: false,      // Don't go up

      discoverSubdirectories: true // Still discover child CLAUDE.md on file access

    }

  }

});

Expected Behavior with Fix

With memoryScope: 'cwd-only' (or equivalent):

• ✅ Load {cwd}/CLAUDE.md


• ✅ Load {cwd}/.claude/CLAUDE.md


• ✅ Load {cwd}/.claude/settings.json


• ✅ Discover skills in {cwd}/.claude/skills/


• ✅ Discover agents in {cwd}/.claude/agents/


• ✅ Load subdirectory CLAUDE.md files on demand (existing behavior)


• ❌ Do NOT traverse to parent directories for CLAUDE.md

Use Cases

1. Monorepo with multiple independent projects - Each subrepo has its own CLAUDE.md with specific instructions


2. SDK-based automation in CI/CD - Need predictable, isolated behavior regardless of where repo is checked out


3. Multi-tenant agent hosting - Running agents for different projects from a shared parent directory


4. Testing/development - Want to test subrepo behavior without parent context interference

Environment

• SDK: @anthropic-ai/claude-agent-sdk (TypeScript)


• Use case: Running agent in subrepo with cwd option

Related Issues

• Issue #456 (claude-agent-sdk-python): Requests explicit skill/command path configuration separate from CLI settings


• Issue #722 (claude-code): Documentation inconsistency about CLAUDE.md discovery


• Issue #12962 (claude-code): Settings.json parent directory traversal for monorepos (inverse request - wanting MORE traversal for settings)

---

Thank you for considering this feature. The SDK's isolation model is great, but the inherited parent traversal behavior from Claude Code CLI breaks isolation for subrepo use cases.