What

First slice of the #6295 workspace code-intelligence layer: a code_search agent tool that regex-searches the workspace in one call.

Coding agents currently locate code by looping file_list + file_read — there is no grep-equivalent built-in. code_search closes that gap: one call returns relpath:line: content rows for every match under a workspace-relative path.

Scope (deliberately minimal)

Lexical / regex search only. Structural symbol indexing, repo maps, reference graphs, and LSP / vector backends from @pavver's proposal are out of scope for this slice and tracked as later stages of #6295. Starting with lexical search follows the discussion's "FTS / repo maps before LSP and vectors" ordering and keeps the first slice small and reviewable.

Behaviour

• Input: query (regex, required), path (workspace-relative, default root), case_sensitive (default false), max_results (default 100, hard cap 1000).
• Skips .git / .hg / .svn / target / node_modules, hidden dirs, symlinks (not followed), binary files (NUL-byte sniff), and files larger than 2 MB. Caps total files scanned at 20k.
• Output sorted by path then line (deterministic, Enforce deterministic ordering for LLM-bound registries to stabilize prompt cache #3298); per-line output clipped to 400 chars on a char boundary; truncation is flagged in the output.

Design decisions

• No new dependency: hand-rolled iterative tokio::fs::read_dir DFS + the already-vendored regex crate. No walkdir, no tree-sitter.
• Lives in librefang-runtime/src/tool_runner/search.rs, wired like any other built-in tool — no new crate (the crate-boundary question from Workspace Code Intelligence Layer for Coding Agents #6295 is left for the structural-index stage).
• Read-only, always-native: added to ALWAYS_NATIVE_TOOLS (eager, no lazy-load round-trip) and to the guest read-only allowlist in kernel/auth.rs, so it needs no approval gate — same treatment as file_list. Path access goes through the existing resolve_file_path_ext sandbox.

Wiring

• tool_runner/search.rs — handler tool_code_search + 5 unit tests.
• tool_runner/definitions.rs — tool_name::CODE_SEARCH, ToolDefinition (JSON schema), ALWAYS_NATIVE_TOOLS.
• tool_runner/dispatch.rs — "code_search" match arm (named-workspace + download-dir read allowlist, like file_list).
• tool_runner/mod.rs — mod search; + handler import.
• kernel/auth.rs — guest READ_ONLY_TOOLS allowlist.
• prompt_builder.rs — tool_category (Files) + tool_hint.

Tests (in search.rs)

• missing_query_is_missing_parameter
• invalid_regex_is_invalid_parameter
• finds_matches_with_line_numbers
• is_case_insensitive_by_default_and_respects_flag
• skips_git_dir_and_binary_files
• no_matches_returns_friendly_message

Verification

This box has no native Rust toolchain and Docker was unavailable in this session, so cargo check / cargo fmt could not be run locally (the pre-commit fmt hook took its documented no-rustfmt soft-skip). CI is the authoritative check — the runtime unit lane compiles + runs the new tests, and the fmt lane validates formatting. Types were cross-checked against the file_list handler template (ToolError / ToolResult / resolve_file_path_ext signatures) and the existing drift tests (no_duplicate_tool_names, tools.len() at least 40) cover the new registration.

refs #6295