#22439: feat(workspace): add tiered bootstrap loading with configurable bootstrapTier
agents
size: S
Cluster:
Hooks Enhancements and Fixes
Closes #22438
## Motivation
Bootstrap files consume LLM tokens on every session. For users with large workspaces, loading all files into every session — including sub-agents and cron jobs — wastes context window budget on files the agent never references. This PR introduces tiered loading so users can control how much context each session type receives, **reducing unnecessary token usage** while preserving persona consistency where needed.
## What
Introduces a three-tier bootstrap file loading system (`minimal` | `standard` | `full`) with a new `agents.defaults.bootstrapTier` configuration option.
## Why
The current binary split (main=all, subagent/cron=minimal) doesn't support use cases where subagents need persona context or where main sessions should be lightweight. This adds a clean, backward-compatible middle ground that lets users optimize their token budget per session type.
## How
- **`resolveBootstrapTier(sessionKey, tierOverride)`** — Resolves effective tier from session type + optional config override
- **`filterBootstrapFilesForSession(files, sessionKey, tierOverride)`** — Extended with optional tier parameter (backward compatible — no tierOverride = existing behavior)
- **Config**: `agents.defaults.bootstrapTier` in zod schema, TypeScript types, labels, and help text
## Testing
11 unit tests covering:
- Default tier resolution for main/subagent/cron sessions
- Config override behavior
- File filtering per tier
- Backward compatibility (no tier = existing behavior)
- Full tier including extra bootstrap files
All tests pass.
## Changes
| File | Change |
|------|--------|
| `src/agents/workspace.ts` | `BootstrapTier` type, `resolveBootstrapTier()`, extended filter |
| `src/agents/bootstrap-files.ts` | Wire tier from config |
| `src/config/zod-schema.agent-defaults.ts` | Zod schema for bootstrapTier |
| `src/config/types.agent-defaults.ts` | TypeScript type |
| `src/config/schema.labels.ts` | UI label |
| `src/config/schema.help.ts` | Help text |
| `src/agents/workspace.tiered-bootstrap.test.ts` | 11 tests |
7 files changed, 145 insertions(+), 3 deletions(-)
Most Similar PRs
#19879: Feat/foropenclaw bootstrapfiles clean
by akyourowngames · 2026-02-18
69.5%
#9521: fix: restrict bootstrap files for cron agentTurn sessions
by ComputClaw · 2026-02-05
68.4%
#15568: feat: configurable workspace context files (agents.defaults.context...
by koatora20 · 2026-02-13
68.3%
#21542: feat(config): add injectMode for workspace bootstrap files
by anonymusk7 · 2026-02-20
68.2%
#13524: feat: conditional bootstrap file loading for heartbeat vs DM sessions
by tarun131313 · 2026-02-10
66.9%
#19621: feat: shared-bootstrap hook for cross-agent bootstrap files
by Diaspar4u · 2026-02-18
65.5%
#8258: feat: Add smart model tiering for cost optimization
by revenuestack · 2026-02-03
64.9%
#19826: fix: add in-prompt warnings and doctor check for bootstrap file tru...
by akramcodez · 2026-02-18
64.9%
#10567: feat(agents): add configurable startup session pruning
by abutlabs · 2026-02-06
63.1%
#20267: feat: workspace-aware post-compaction context
by nickjlamb · 2026-02-18
63.1%