Code-context search subagent and reusable repository evidence artifact

[ncolesummers]

Summary

Create a declared code-context/search subagent under the shared stage orchestrator. It performs multi-step agentic repository research for stage specialists and returns a bounded, typed, commit-pinned context artifact instead of owning workflow state.

Context

Issue #47 gives planner and test-writer baseline repository-scoped discovery, grep, and line-range reads. Those primitives are intentionally local and bounded. More complex work may need query planning, reference following, parallel investigation, deduplication, and reusable context synthesis across planner, test-writer, implementation, and validation-review stages.

This is a first-party orchestration capability, not operator-supplied customization from #59 and not planner web access from #68.

Deliverables

• Declared sibling code-context/search subagent with independent model, instructions, tools, sandbox, and eval configuration.
• Typed code_context artifact with repository/commit identity, originating query, cited path/line ranges, relevance summaries, unresolved questions, search budgets, and truncation state.
• Bounded query planning and optional isolated child-session fan-out without nested durable ownership.
• Deterministic orchestration contract for requesting, validating, caching, and handing the artifact to planner, test-writer, implementation, and validation-review subagents.
• Sanitized OTel-aligned spans/logs containing correlation IDs, counts, duration, truncation, and outcome without queries, source text, or secrets.

Acceptance Criteria

• Every finding cites a repository-relative path, one-based line range, and exact commit SHA.
• Search excludes secret, generated, dependency, traversal, and symlink-escape surfaces and enforces query, match, file, byte, duration, and fan-out budgets.
• Repeated or overlapping findings are deduplicated while conflicting evidence and unresolved questions remain explicit.
• The subagent returns only a typed context recommendation/artifact; the root orchestrator validates it and owns durable persistence and transitions.
• Planner, test-writer, implementation, and validation-review can consume the same artifact without re-running equivalent searches.
• Prompt, model, tool, budget, provenance, negative-security, and no-mutation behavior have deterministic fixture and live Eve eval coverage under Agent evaluation framework #17 governance.

Dependencies and relationships

• Builds on baseline repository inspection from Test-writing subagent for the development loop #47.
• Planner web search/fetch remains [Feature]: Guarded web search and fetch tools for agents #68.
• Operator-defined tools, MCP, and skills remain Backlog gap: no operator-facing agent customization (custom tools, MCP, agent skills) #59.
• Implementation-stage consumption should align with Implementation subagent for the development loop #48.
• Eval governance aligns with Agent evaluation framework #17.

Architecture impact

Update ADR 0015 or supersede it if the shared orchestrator gains a reusable cross-stage context-artifact protocol. The search subagent remains a declared sibling and cannot mutate GitHub or durable workflow state.