depth flag should drive iteration / budget / source defaults #30

New issue

Closed

opened 2026-04-08 22:04:49 +00:00 by claude-code · 0 comments

claude-code commented

2026-04-08 22:04:49 +00:00

Collaborator

Problem

The depth parameter (shallow / balanced / deep) is currently passed only as a text hint inside the agent's user message. It has no mechanical effect on iteration counts, token budgets, or source counts — those are governed independently by --max-iterations and --budget. The LLM is expected to "interpret" depth, which is unreliable and makes the flag essentially cosmetic.

Goal

Make depth a real control knob: choosing a depth picks sensible defaults for max_iterations, token_budget, and max_sources. Explicit --max-iterations / --budget flags still override.

Suggested defaults (open to discussion)

Depth	max_iterations	token_budget	max_sources
shallow	2	5,000	5
balanced	5	20,000	10
deep	8	60,000	20

(balanced matches today's defaults so the change is backward-compatible for existing callers.)

Scope

ResearchConstraints (or a new depth_defaults() helper) maps depth → defaults
WebResearcher.research() applies depth defaults only when the constraint field is at its default value — explicit overrides win
MCP server research tool: same logic
CLI ask command: when --max-iterations / --budget are not explicitly set, the depth chooses; when they are, they override (Click can detect this with click.get_current_context().get_parameter_source(...))
Update docs / help text so the depth flag's actual behavior matches expectations

Tests

Each depth produces the expected constraint values
Explicit flags override depth defaults
balanced is unchanged from current defaults (regression check)

Out of scope

Tuning the actual default numbers based on stress test data — that's Phase 3 calibration territory. This issue is about wiring depth → defaults, not picking the perfect numbers.

## Problem The `depth` parameter (`shallow` / `balanced` / `deep`) is currently passed only as a text hint inside the agent's user message. It has no mechanical effect on iteration counts, token budgets, or source counts — those are governed independently by `--max-iterations` and `--budget`. The LLM is expected to "interpret" depth, which is unreliable and makes the flag essentially cosmetic. ## Goal Make `depth` a real control knob: choosing a depth picks sensible defaults for `max_iterations`, `token_budget`, and `max_sources`. Explicit `--max-iterations` / `--budget` flags still override. ## Suggested defaults (open to discussion) | Depth | max_iterations | token_budget | max_sources | |-----------|---------------:|-------------:|------------:| | shallow | 2 | 5,000 | 5 | | balanced | 5 | 20,000 | 10 | | deep | 8 | 60,000 | 20 | (`balanced` matches today's defaults so the change is backward-compatible for existing callers.) ## Scope - `ResearchConstraints` (or a new `depth_defaults()` helper) maps depth → defaults - `WebResearcher.research()` applies depth defaults *only when the constraint field is at its default value* — explicit overrides win - MCP server `research` tool: same logic - CLI `ask` command: when `--max-iterations` / `--budget` are not explicitly set, the depth chooses; when they are, they override (Click can detect this with `click.get_current_context().get_parameter_source(...)`) - Update docs / help text so the depth flag's actual behavior matches expectations ## Tests - Each depth produces the expected constraint values - Explicit flags override depth defaults - `balanced` is unchanged from current defaults (regression check) ## Out of scope - Tuning the actual default numbers based on stress test data — that's Phase 3 calibration territory. This issue is about wiring depth → defaults, not picking the perfect numbers.