Summary

codedb_query today is a composable pipeline tool. The agent supplies an array of explicit steps (find, search, filter, deps, outline, read, sort, limit, word, symbol) and each step operates on the file set produced by the previous step. The composition is powerful, but a few rough edges hurt agent-driven exploration in practice:

1. A single failing step kills the whole pipeline. If step 3 errors out, steps 1-2 of useful work are thrown away.
2. codedb_outline errors are bare strings. A bad path returns error: file not indexed: <path> with no fallback hint, so the agent has to guess the right path on the next call.
3. Pipeline error messages don't say which input shape they got. When an op fails for missing args, callers can't tell whether codedb dropped the field or the client sent it under the wrong name. (Note: codedb_bundle already gained a received keys: [...] diagnostic in MCP bundle should preserve nested tool arguments for codedb_outline #357 — codedb_query should do the same.)

Non-goals (explicit)

• codedb is a tool, not an agent. This issue does not propose any natural-language intent classification, automatic pipeline composition, or response-ranking heuristics. The agent stays in charge of what to ask for; codedb's job is to answer the asked question reliably and surface enough information that the agent can recover from mistakes.
• No new "task: ..." parameter that runs a default pipeline. That would be sneaking agentic behavior into the tool. Agents that want a multi-step query already have the pipeline interface.

Proposal

Three small, independently-shippable improvements to codedb_query and codedb_outline:

1. Partial results in codedb_query

When a pipeline step fails, return the work the prior steps produced, plus a structured tail naming the failing step and reason. Today's behavior is "first error aborts the pipeline and discards everything"; the new behavior should be "complete what we can, label what failed."

Example output today:

2 files matched:
  src/foo.zig
  src/bar.zig
error: deps needs prior step or 'path' param

Example output proposed:

2 files matched:
  src/foo.zig
  src/bar.zig
--- partial ---
stages_ok: 2
failed_at: 3 (deps)
reason: deps needs prior step or 'path' param

2. Fuzzy path fallback in codedb_outline

When codedb_outline is given a path that doesn't index, today it returns:

error: file not indexed: src/main.zig

Proposed: also append the top-3 closest indexed paths so the agent can correct the call without a separate codedb_find.

error: file not indexed: src/main.zig
did you mean:
  src/main_old.zig
  src/main2.zig
  src/main_test.zig

3. Per-stage diagnostics on missing-arg errors

Mirror the received keys: [...] diagnostic that codedb_bundle gained in #357 (PR #362). When a codedb_query pipeline step fails with error: missing ..., append the keys actually present on that step.

Acceptance criteria

• Pipeline step failure no longer discards prior-step output. New --- partial --- tail names the failing step and reason.
• codedb_outline returns up to 3 fuzzy-match suggestions for non-indexed paths.
• codedb_query step missing-arg errors include received keys: [...] like codedb_bundle does.
• Failing tests for each item land before the fix (per repo policy in CLAUDE.md).
• Telemetry remains aggregate-only and privacy-preserving.
• No new top-level tools and no automatic step composition based on a task parameter.

Out of scope

• Any heuristic that picks pipeline ops automatically.
• Cross-step result ranking (search hits vs. symbol matches vs. fuzzy paths).
• Embedding/vector search.
• Symbol references / impact analysis (separate, larger initiative).

Related

• MCP bundle should preserve nested tool arguments for codedb_outline #357 — bundle received keys diagnostic (closed in v0.2.5792). Shape (3) above mirrors that work.
• Improve literal search recall and exact filename ranking #363 — literal-phrase recall and fuzzy ranking. Adjacent reliability work but separate code paths; tracked independently.