Epic: agent tool parity — close the general-capability gaps vs. a full coding assistant

[initializ-mk]

Why

An audit of Forge's builtin toolset against what a general coding/assistant agent needs surfaced a cluster of gaps. Individually they're small; together they're the difference between "runs pre-scripted skills" and "can take on an open-ended task." This epic tracks them as one line item and, crucially, pins the shared security model so each tool lands consistently rather than bolting on its own execution/approval path.

Tracked issues

#	Gap	Notes
#265	Sandboxed shell/command runner	Controlled general execution above cli_execute's allowlist; sandbox-only, gated off by default
#266	web_fetch builtin	Fetch a URL → cleaned, LLM-readable content (fills the gap between web_search results and http_request raw bytes)
#267	Subagent delegation tool	Let an agent spawn a capability-scoped sub-agent (child tools/egress ⊆ parent)
#268	Wire up dormant file_read / file_write / file_edit / file_patch	Fully-built, tested builtins the runtime never registers; general R/W/edit surface
#255	Multimodal (image/document) input	Already tracked separately — the tool-side of general "read this file"; listed here for completeness

Shared model (the reason this is an epic, not 5 unrelated issues)

These aren't independent — they must share Forge's governed-execution posture so the safe default stays safe:

• Path confinement — feat(tools): wire up dormant file_read / file_write / file_edit / file_patch builtins for general agents #268 (file tools) and feat(tools): sandboxed shell/command runner — controlled general execution beyond cli_execute's allowlist #265 (shell) must reuse the NewPathValidator confinement the search tools already use; must not regress [ASI02] cli_execute workDir path confinement — reads escape to /etc/passwd (GAP-PATH) #235 (cli_execute /etc/passwd escape).
• Approval / dry-run — mutating tools (feat(tools): sandboxed shell/command runner — controlled general execution beyond cli_execute's allowlist #265 shell, feat(tools): wire up dormant file_read / file_write / file_edit / file_patch builtins for general agents #268 write/edit) route through the [ASI02/ASI09] Action-level approval + dry-run diff for destructive tool calls — close ASI02 #2 / ASI09 #1,#7 #223 action-level approval + dry-run path, building on the merged R4c DEFER (R4c (governance): implement DEFER decision (resumable executor) #211) pause-and-resume gate rather than inventing per-tool confirmation. [ASI02/ASI09] Action-level approval + dry-run diff for destructive tool calls — close ASI02 #2 / ASI09 #1,#7 #223 is the keystone dependency.
• Denied-command patterns — feat(tools): sandboxed shell/command runner — controlled general execution beyond cli_execute's allowlist #265 honors platform-authored [ASI02] Platform-layer denied_command_patterns — operator-authored, org-wide command denial across all skills #238 deny patterns.
• Blast-radius limits — feat(tools): subagent delegation tool — let an agent spawn a scoped sub-agent for a subtask #267 (subagent fan-out) respects [ASI08] Blast-radius quotas + circuit breaker (planner/executor) — close ASI08 #7 #233 quotas / circuit breaker and audits under the parent task via [ASI08/ASI09/ASI10] Tamper-evident (hash-chained + signed) audit stream — close ASI10 #1 / ASI09 #2 / ASI08 #10 #224.
• Egress — feat(tools): web_fetch builtin — fetch a URL and return cleaned, LLM-readable content #266 reuses http_request's egress-controlled path; no new network bypass.
• Off by default — every new-capability tool (feat(tools): sandboxed shell/command runner — controlled general execution beyond cli_execute's allowlist #265, feat(tools): subagent delegation tool — let an agent spawn a scoped sub-agent for a subtask #267) is opt-in and gated, matching the trusted-platform (not trusted-dev-box) assumption.

Suggested sequencing

1. [ASI02/ASI09] Action-level approval + dry-run diff for destructive tool calls — close ASI02 #2 / ASI09 #1,#7 #223 (approval keystone) + feat(tools): wire up dormant file_read / file_write / file_edit / file_patch builtins for general agents #268 (file tools) — highest leverage; feat(tools): wire up dormant file_read / file_write / file_edit / file_patch builtins for general agents #268's write/edit is the first real consumer of [ASI02/ASI09] Action-level approval + dry-run diff for destructive tool calls — close ASI02 #2 / ASI09 #1,#7 #223's dry-run diff, and the builtins already exist.
2. feat(tools): web_fetch builtin — fetch a URL and return cleaned, LLM-readable content #266 (web_fetch) — low-risk, self-contained, no new trust tier.
3. feat(tools): sandboxed shell/command runner — controlled general execution beyond cli_execute's allowlist #265 (shell runner) — depends on [ASI02/ASI09] Action-level approval + dry-run diff for destructive tool calls — close ASI02 #2 / ASI09 #1,#7 #223 + [ASI02] cli_execute workDir path confinement — reads escape to /etc/passwd (GAP-PATH) #235 + [ASI02] Platform-layer denied_command_patterns — operator-authored, org-wide command denial across all skills #238 + the [Bug]: Phase 5 — Container Sandbox Supervisor: Kernel-Level Network Isolation, Seccomp, DNS Proxy, Policy Engine #35 sandbox supervisor.
4. feat(tools): subagent delegation tool — let an agent spawn a scoped sub-agent for a subtask #267 (subagent) — depends on [ASI08] Blast-radius quotas + circuit breaker (planner/executor) — close ASI08 #7 #233 + [ASI08/ASI09/ASI10] Tamper-evident (hash-chained + signed) audit stream — close ASI10 #1 / ASI09 #2 / ASI08 #10 #224.

Done when

• feat(tools): sandboxed shell/command runner — controlled general execution beyond cli_execute's allowlist #265, feat(tools): web_fetch builtin — fetch a URL and return cleaned, LLM-readable content #266, feat(tools): subagent delegation tool — let an agent spawn a scoped sub-agent for a subtask #267, feat(tools): wire up dormant file_read / file_write / file_edit / file_patch builtins for general agents #268 closed (or explicitly deferred with rationale)
• Each mutating tool demonstrably routes through the shared approval/confinement model — no bespoke execution or confirmation paths
• Docs describe the general tool surface vs. the code-agent skill's code_agent_* specialization

Related security work: #211, #223, #233, #235, #238, #224