SFF-060: Governed execution tool catalog and policy

[jmrpineda]

Reported by: Codex
Requested by: jmr.pineda
Priority: P1
Affected surfaces: Execution harness, phase execution policies, agent profiles, model configuration, MCP/runtime contracts, product packaging boundary
Constraints: Preserve the MCP workflow boundary; do not expose arbitrary provider passthrough tools; policy decisions must remain inspectable and auditable; keep SpecForge OSS useful without requiring Central for basic local tool use.

Summary

SpecForge should define a governed execution-tool model that separates workflow tools from model-facing execution tools, makes tool access an explicit part of the phase execution envelope, and encodes which capabilities belong to OSS-local runtime versus gateway-routed organization-grade infrastructure.

Problem / opportunity

The product already models repository access and phase routing, but that is not enough to safely support access to private repositories, RAG, CAG, and related external context sources. If tool access is added as a generic provider capability, the harness loses clarity about what the model is allowed to call, under which phase constraints, and how those calls are audited. At the same time, SpecForge is public open source while SpecForge Central is intended to be commercial. The tool model therefore needs a defensible packaging boundary so Central monetizes governed shared capabilities rather than basic local tool use.

Requested behavior

Define a first-class execution-tool catalog and policy contract for SpecForge. The runtime should distinguish between workflow mutation tools and model-facing execution tools, and each phase or assigned agent should declare which execution tools are allowed, which scopes they can reach, and which routing class applies: local-only, local-preferred, central-preferred, or central-required.

Scope

• In scope: Execution-tool domain model; separation between workflow tools and execution tools; phase-level and agent-level allowed-tool policy; repository and domain scope rules; routing-class model; packaging-aware policy defaults; basic per-execution budget semantics; blocking reasons when a requested tool is not allowed or not locally routable.
• Out of scope: Implementing every possible connector; full sandboxing across all providers in the first cut; arbitrary shell access disguised as a tool; using Central as a mandatory path for trivial current-repo reads.

Acceptance criteria

1. SpecForge defines a first-class execution-tool contract that is distinct from workflow tools and usable across providers.
2. The effective phase execution envelope can declare allowed execution tools, repository or domain reach, routing class, and minimum budget restrictions.
3. The runtime can reject or downgrade a tool request with an explicit policy reason when the phase envelope does not allow it or requires Central routing.
4. The policy model preserves OSS-local value for current-repository intelligence while reserving shared, governed, or secrets-backed capabilities for gateway-routed use.

Notes

• This feature should build on the existing execution-envelope work rather than redefine it.
• The implementation should keep provider transport details behind the harness so provider-native tool APIs do not become the source of truth.
• A useful first taxonomy is:
  • workflow tools: mutate or inspect .specs/** through MCP contracts
  • execution tools: provide governed context or external actions to phase execution
• Candidate policy fields include allowed tool IDs, allowed repositories, allowed domains, routing class, writable paths, redaction rules, and request or token budgets.
• Product packaging guidance is captured in doc/execution-tool-packaging.md.