context_for_task

Ask it before starting work your agent can’t scope: it returns the bounded slice of the codebase that matters for a natural-language task description, ranked and capped so you read a handful of files instead of the whole repo.

When to call

Before a refactor or feature touching code the agent hasn’t read.
When the repo is too large to explore file-by-file within the context window.
To decide which files to open, instead of opening files to decide.

Parameters

Name	Type	Default	Description
`dep_graph`	`DependencyGraph`	required	Dependency graph to search — a `parse` session ID.
`task`	`str`	required	Natural-language task description, e.g. `"add rate limiting to login"`.
`architecture`	`Architecture \| None`	`None`	Optional recovered-architecture session ID. When passed, components whose name or responsibility text matches a task keyword contribute their member entities as `component sibling` candidates too.
`max_files`	`int`	`15`	Maximum number of ranked files to return.

Returns

Field	Type	Meaning
`task`	`str`	Echoes the input task string.
`keywords`	`list[str]`	Tokenized keywords extracted from `task` (empty if none survived tokenization).
`num_files`	`int`	Number of entries in `files` — `0` on the no-keywords branch.
`files`	`list[dict]`	Ranked files: `{file_path, score, primary_role, entities, reason}`. `entities` is `{fqn, role}` for every matched entity in that file; `role` is one of `direct match`, `dependent of match`, `dependency of match`, `component sibling`. `reason` is a short human-readable string built from matched keywords and relationship notes.
`error`	`str` (only on the empty-keywords branch)	`"No searchable keywords found"` — set instead of raising when `task` tokenizes to nothing.

Examples

Both calls below run against a parse session (dep_graph="fe538dededcc", 572 entities / 29 edges) and a recover session (architecture="7abc279063c7", algorithm="pkg", pkg_depth=1) over a shallow clone of pallets/click.

→ context_for_task(dep_graph="fe538dededcc", task="add shell completion support for a new shell", architecture="7abc279063c7", max_files=5)
{
  "task": "add shell completion support for a new shell",
  "keywords": ["add", "shell", "completion", "support", "for", "new", "shell"],
  "num_files": 5,
  "files": [
    {
      "file_path": "click/shell_completion.py",
      "score": 1191.8,
      "primary_role": "direct match",
      "entities": [
        { "fqn": "click.shell_completion.BashComplete", "role": "direct match" },
        { "fqn": "click.shell_completion.BashComplete._check_version", "role": "direct match" }
        // … 34 more entities, all "direct match"
      ],
      "reason": "matches 'add', 'completion', 'for', 'shell'; depended on by BashComplete; depended on by ZshComplete"
    },
    { "file_path": "click/core.py", "score": 116.0, "primary_role": "direct match", "entities": [ /* … 23 entities … */ ], "reason": "matches 'add', 'completion', 'for', 'shell'" }
    // … 3 more files: click/types.py, click/exceptions.py, click/formatting.py
  ]
}

The second call uses a task with no dictionary-recognizable keywords to show the no-match branch — no exception, an error note instead:

→ context_for_task(dep_graph="fe538dededcc", task="???")
{
  "task": "???",
  "keywords": [],
  "num_files": 0,
  "files": [],
  "error": "No searchable keywords found"
}

Things worth knowing

A miss is a normal dict, not an exception. An untokenizable task returns {"keywords": [], "files": [], "error": "No searchable keywords found"} rather than raising — check for the error key, don’t rely on try/except.
architecture only ever adds candidates, never narrows. Passing a recovered architecture can pull in extra component sibling files whose parent component’s name/responsibility matches a keyword; omitting it just means fewer, purely keyword/graph-derived results — it never causes a call to fail.
Ranking is a heuristic, not a search index. Direct keyword hits seed relevance; only the top 10 seeds (_EXPAND_SEED_LIMIT) get their one-hop dependencies/dependents pulled in at half relevance (_NEIGHBOUR_DECAY = 0.5) — a real but low-scoring match can still miss the max_files cutoff if 15+ stronger files exist.
Token-budget truncation applies like any other tool. This response has no top-level graph/architecture key, so a tight max_tokens at the MCP layer runs it through the generic enforce_budget path (drops whole top-level keys, largest first, flags _budget_truncated: true) rather than the graph-aware progressive reduction used by ingest/parse/recover-shaped responses.
Results don’t persist a new session — this is a terminal, read-only view over the dep_graph/architecture sessions you already hold.