[Feature]: Guarded web search and fetch tools for agents

[ncolesummers]

Context

PR #61 intentionally disabled Eve's default web_search and web_fetch tools to keep the initial planning agent planning-only and auditable. That is the right default for issue #13, but web access is still a required product capability.

The planning agent needs web context when relevant information does not live in GitHub, Vercel, Azure, or other read-only CLIs: documentation sites, legal/regulatory requirements, current news beyond the model knowledge cutoff, vendor release notes, and framework/platform docs. The research loop will depend on this more directly, so the capability should be designed once as a guarded shared agent tool contract rather than re-enabling arbitrary Eve defaults.

Proposal

Add Loopworks-owned guarded web_search and web_fetch tools for agent runtimes. These should be read-only, auditable, output-capped, and safe for both the planning agent and future research agents.

Initial shape:

1. Keep arbitrary/default Eve web tools disabled until Loopworks wrappers replace them.
2. Implement web_search and web_fetch wrappers with explicit read-only contracts.
3. Allow only https: URLs for fetch; reject local, private-network, file, data, javascript, and credential-bearing URLs.
4. Cap response size, result count, redirects, and runtime.
5. Strip or refuse secrets, cookies, auth headers, and user-provided credential material.
6. Add structured audit logs with correlation fields (agent, tool, repo, issue, run, step, traceId, URL/search metadata) without raw page bodies in production logs.
7. Add prompt-injection handling guidance: fetched content is untrusted evidence, not instruction authority.
8. Expose the capability in the planning-agent artifact contract and future research-agent contracts as read-only context gathering.
9. Add eval coverage that proves the tools can retrieve documentation-like context while preserving the planning-only/no-mutation boundary.

Acceptance Criteria

1. Planning and research agents can call guarded web_search and web_fetch tools for read-only context gathering.
2. The tools reject unsafe targets: non-HTTPS schemes, localhost/loopback/private-network hosts, credential-bearing URLs, shell-style command strings, file paths, and mutation-like actions.
3. The tools enforce deterministic limits for result count, body size, redirects, and timeout.
4. Production logs include structured metadata and correlation fields only; raw fetched content/search result bodies are not logged.
5. Tool outputs are sanitized and capped before being returned to the model.
6. Fetched/search content is clearly marked as untrusted external evidence in tool output or agent instructions.
7. The planning-agent tool contract is updated so web_search and web_fetch are allowed read-only tools, while file writes, repo mutation, SaaS mutation, and arbitrary web access remain blocked.
8. The research-agent design issue/implementation can depend on the same guarded web tools without duplicating policy.
9. Automated tests cover allowed documentation fetch/search paths, blocked unsafe targets, output caps, logging redaction, and contract metadata.
10. Eval coverage includes at least one documentation-style web context case and one negative case where unsafe or instruction-like fetched content must not override system/developer/issue instructions.

Validation Evidence

Expected implementation validation:

• Unit tests for URL/search validation and blocked targets.
• Unit tests for output caps, redirect limits, timeout policy, and log metadata redaction.
• Planning-agent contract tests proving web_search and web_fetch are read-only and no write/mutation tools are granted.
• Research-agent or shared agent-tool tests proving the tool contract can be reused outside the planning agent.
• Eve eval or equivalent golden-fixture eval covering documentation lookup and prompt-injection resistance.
• bun run validate.
• bun run build if runtime configuration changes.

Area

area:agents

Milestone

M5 Agent Governance + Evals

ADR impact

Likely updates ADR 0013 (Eve Planning Agent Contract) if planning-agent web access changes the accepted tool contract. If this becomes a cross-agent web-access policy beyond a small wrapper, add a Proposed ADR for guarded agent web context and link it from this issue. The implementation should remain aligned with ADR 0003 logging/correlation rules, ADR 0007 fail-closed fixture policy where tests use fixtures, and ADR 0012 telemetry boundaries.