Summary

Fixes openclaw#56029

Problem

When spawning subagents via sessions_spawn, each subagent automatically receives ALL workspace files (AGENTS.md, SOUL.md, USER.md, MEMORY.md, HEARTBEAT.md, TOOLS.md, IDENTITY.md, etc.) as context — even when the subagent is doing a narrow, stateless task like scanning database rows or running shell commands.

Impact:

• Each subagent loads ~5-10k tokens of workspace context it never uses
• A typical audit cycle spawns 4-5 workers → 25-50k wasted tokens per cycle
• Running 10+ cycles per day → 250-500k tokens/day burned on irrelevant context

Solution

Add configuration options to control workspace context injection for subagents:

{
  "agents": {
    "defaults": {
      "subagents": {
        "workspaceScope": "essential",
        "workspaceFiles": ["AGENTS.md", "TOOLS.md"]
      }
    }
  }
}

Scope Options

Custom Allowlist

For fine-grained control:

{
  "workspaceFiles": ["AGENTS.md", "MEMORY.md"]
}

Implementation (Phase 1)

This PR implements the foundation:

1. Type definitions (types.agent-defaults.ts)

   • Add workspaceScope and workspaceFiles to AgentDefaultsConfig.subagents

2. Filtering logic (bootstrap-files.ts)

   • Add SubagentWorkspaceScope type
   • Add applySubagentWorkspaceScopeFilter() function
   • Extend resolveBootstrapFilesForRun() to accept scope parameters

Remaining Work (Phase 2)

• Wire up config reading in subagent spawn flow
• Add unit tests for applySubagentWorkspaceScopeFilter()
• Add documentation for new config options
• Update CLI help text

Token Savings Estimate

For a workflow spawning 5 workers per cycle, 10 cycles/day:

• Before: 500k tokens/day on workspace context
• After (essential): ~100k tokens/day → 80% reduction

Checklist

• Code follows project style guidelines
• Comments added for new types and functions
• Tests added/updated (Phase 2)
• Documentation updated (Phase 2)