[EPIC] MCP Execution Readiness and Bounded Context Grants

[Joncallim]

Issue Type

Epic.

Priority: P0 for execution reliability. This is the next architecture epic after the Executable Workforce Beta (#119, closed) because MCP ambiguity is now the main reason approved tasks can still stall at handoff.

Canonical architecture (handoff-ready, no reasoning required to implement): docs/adr/0009-mcp-admission-contract.md. Every child slice below references it.

Context

Forge distinguishes three kinds of MCP involvement, but the code does not distinguish them in one place:

1. Planning-only MCP context — the Architect says an MCP would help; Forge records it only as run-scoped prompt instructions. It grants nothing.
2. Bounded read-only context grants — Forge assembles a project-scoped, inspectable read-only context packet (file names, selected excerpts) after an explicit operator grant.
3. Live MCP tool handles — a worker calling an MCP at runtime. This is deferred; it is not implemented in this epic and must read as a product boundary, not a broken install.

Current failure mode (observed): the Architect produced a valid plan and work packages; MCP access was shown as planning-only; but package handoff still blocked on MCP grant semantics. filesystem.project.write commonly appears in plans even though Forge writes generated files through its sandbox execution JSON path, not live MCP tools. Required filesystem read/list/search requirements, prompt-only overlays, project-level filesystem approval, and no-capability MCP entries are handled by different code paths with subtly different rules.

Root cause: the same beta capability policy is re-derived by four overlapping code paths that do not agree (plus a fifth client-side copy). Full evidence with file:line anchors is in ADR 0009 §Context:

• validateMcpExecutionDesign — web/worker/mcp-execution-design.ts:326-454 (approval validation)
• deriveMcpGrantDecisions / decisionStatus — web/worker/mcp-execution-design.ts:753-867 (preview)
• evaluateWorkPackageMcpBroker — web/worker/mcp-execution-design.ts:599-739 (handoff)
• requiresFilesystemGrantApproval / summarizeFilesystemCapabilities — web/lib/mcps/filesystem-grants.ts:90-339
• client re-implementation — web/app/dashboard/tasks/[id]/page.tsx:348-444

The most important consequence: web/app/api/tasks/[id]/approve/route.ts never runs the handoff broker — it gates only on the filesystem path — so a package the broker will block at handoff for a non-filesystem reason passes approval and stalls later. This epic makes planning, approval, UI state, filesystem grants, and handoff follow one admission contract so this cannot recur with the next workforce slice.

Desired Outcome

Forge should let normal approved work packages advance without confusing MCP blockers, while keeping live MCP tool access out of scope until a deliberate later security-reviewed slice.

Architecture principles

1. One contract, many surfaces. The same MCP admission decision drives preview badges, approval blocking, handoff blocking, and recovery messaging.
2. Planning is not permission. Architect proposals and prompt overlays are context, not tool grants.
3. Bounded context is explicit. File/repository context is packaged, visible, and attached to run evidence.
4. Writes stay on the Forge execution path. Generated files are written through sandbox output and Forge-applied host-repository writes, not live MCP filesystem write tools.
5. Blocks must be actionable. Every blocked MCP state names the exact missing grant, unhealthy MCP, unsupported capability, or deferred feature.
6. No silent privilege widening. Broad aliases cover project read/list/search only. Write, destructive, admin, secrets, and merge operations remain blocked.

The admission model — every surface consumes one package-level evaluation (admitWorkPackageMcp → McpWorkPackageAdmission) built from one per-requirement producer (admitMcpRequirement → McpAdmissionDecision); validateMcpExecutionDesign, deriveMcpGrantDecisions, evaluateWorkPackageMcpBroker, and requiresFilesystemGrantApproval become shape-preserving adapters over it. Full types + producer + adapters + the total precedence-ordered decision table are in ADR 0009; the per-requirement decision is:

type McpAdmissionDecision = {
  schemaVersion: 1
  mcpId: 'filesystem' | 'github' | string
  agent: string
  requirement: 'required' | 'optional'
  requestedCapabilities: string[]
  normalizedCapabilities: string[]
  capabilityClasses: Array<{ capability: string; class: McpCapabilityClass; deliveryKind: McpDeliveryKind | null }>
  mode:
    | 'planning_only'
    | 'bounded_context_required'
    | 'bounded_context_approved'
    | 'blocked'
    | 'deferred_live_mcp'
    | 'unknown_legacy'          // pre-#172 artifact; never re-invented
  status: 'allowed' | 'warning' | 'blocked'
  reason: string
  recoveryAction?:
    | 'continue_as_prompt_context'
    | 'approve_project_filesystem_context'
    | 'install_or_fix_mcp'
    | 'revise_plan'
    | 'defer_live_mcp_feature'
  evidenceRefs: string[]          // PLANNED scope pre-run (root + capability set); run evidence added by S4
}

Cross-surface parity is asserted on the canonical (mode, admissionStatus) pair. The grant-preview adapter keeps its legacy status field (allowed → proposed) and adds a canonical admissionStatus: 'allowed' | 'warning' | 'blocked' so shape preservation and literal status parity both hold.

Capability classes (sourced from MCP_CATALOG.runtime.capabilities, one classifier):

• Planning-only — prompt overlays, MCP-aware subtasks, filesystem.project.write. Warn, do not block, when no live MCP handles are issued.
• Bounded read-only — filesystem.project.read|list|search. May require explicit project-level filesystem approval; produce visible effective grant metadata.
• Deferred live MCP — live tool handles; github write/branch/pr/merge/settings/secret; filesystem write/delete/admin (an enumerated set of recognized live-tool families). Blocked/deferred until a later security-reviewed runtime-grant epic. A first-class named mode, not a generic "beta scope" error. A required deferred capability blocks with revise_plan; an optional one warns with defer_live_mcp_feature.
• Unknown / typo — a capability naming no known MCP, or a known MCP with an unrecognized/typo capability, is unknown and blocks with revise_plan — never silently treated as safe or as deferred.

Operator UX contract — the task detail page answers four questions without logs: (1) is this just planning context? (2) does this package need bounded project filesystem context (show the exact grant)? (3) is an MCP unhealthy/missing (link setup/retry)? (4) is this a deferred-live-MCP feature (say deferred, not broken install)?

Scope boundary: live MCP tool handles remain unissued; filesystem.project.write is planning-only or normalized into the sandbox write path; required filesystem read/list/search stays explicit, recoverable, and auditable; approved tasks cannot enter a handoff block that was already visible at approval.

Tasks

The epic is delivered as six sweeping child slices plus the existing Architect-assignment slice. All are linked as sub-issues of this epic and detailed with file-level architecture in their own bodies and in ADR 0009.

Child slices (dependency-ordered):

• [FEATURE] S1 — Unified MCP admission contract and capability taxonomy #176 — S1: Unified MCP admission contract and capability taxonomy. New web/lib/mcps/admission.ts + capability-normalization.ts; catalog-driven classifyCapability; the McpAdmissionDecision contract, admitMcpRequirement, and shape-preserving adapters. Blocks all others. (This pass also authored ADR 0009.)
• [FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177 — S2: Consolidate admission onto the shared core and enforce it at approval. Make the four paths thin adapters; make approval run the same admission decision as handoff. Adds the preview==handoff invariant tests. Blocked by [FEATURE] S1 — Unified MCP admission contract and capability taxonomy #176.
• [FEATURE] S3 — Deterministic bounded filesystem context grant/denial recovery #178 — S3: Deterministic bounded filesystem context grant/denial recovery. Denied-required grant holds pre-claim (zero attempts); cross-endpoint recovery is deterministic; handoff consults project config in both branches. Blocked by [FEATURE] S1 — Unified MCP admission contract and capability taxonomy #176, [FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177.
• [FEATURE] S4 — Specialist prompt and bounded context packet assembly with run evidence #179 — S4: Specialist prompt and bounded context packet assembly with run evidence. Overlays/subtasks as instructions not grants; bounded context packet metadata attached as inspectable evidence (contents stay prompt-only); sandbox vs host writes separated. Blocked by [FEATURE] S1 — Unified MCP admission contract and capability taxonomy #176, [FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177 (consumes S2's canonical evaluation + persisted shape); builds on [FEATURE] Add Architect-driven MCP assignment and agent prompt overlays #43.
• [FEATURE] S5 — Unified operator UI copy and recovery-action contract for MCP admission #180 — S5: Unified operator UI copy and recovery-action contract. One admission-copy.ts mapping mode+recoveryAction+status to badges/CTAs across the task, projects, and MCPs pages. Blocked by [FEATURE] S1 — Unified MCP admission contract and capability taxonomy #176, [FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177, [FEATURE] S4 — Specialist prompt and bounded context packet assembly with run evidence #179 (renders S4's run-evidence schema).
• [FEATURE] S6 — End-to-end MCP admission regression (tiny task-tracker flow) and preview==handoff invariant #181 — S6: End-to-end MCP admission regression (tiny task-tracker flow) + preview==handoff invariant. Blocked by [FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177, [FEATURE] S3 — Deterministic bounded filesystem context grant/denial recovery #178, [FEATURE] S4 — Specialist prompt and bounded context packet assembly with run evidence #179, [FEATURE] S5 — Unified operator UI copy and recovery-action contract for MCP admission #180.
• [FEATURE] Add Architect-driven MCP assignment and agent prompt overlays #43 — Architect-driven MCP assignment and agent prompt overlays (existing). Now a child slice, re-scoped to planning/overlay output only (assignment, prompt overlays, MCP-aware subtasks that feed S4). Its runtime tool-issuance and tool-call-audit acceptance criteria are deferred to the later security-reviewed live-MCP epic (depends on [FEATURE] Add adversarial agent mode with default rules and project override editor #40, Add security review workforce architecture and subagent taxonomy #60); capability vocabulary standardized to github.* / filesystem.project.*.

Dependency graph

#176 (S1) ─► #177 (S2) ─┬─► #178 (S3) ───────────────► #181 (S6)
                        └─► #179 (S4) ─► #180 (S5) ──► #181 (S6)
#43 (planning) ───────────────────────► #179 (S4)

Related issues (stay independent; dependencies/dependents, not subsumed):

• [EPIC] Executable Workforce Beta: capability-brokered sequential specialist execution #119 — Executable Workforce Beta (closed). Predecessor; this epic hardens the MCP readiness gaps it left intentionally out.
• [FEATURE] Add project-level MCP installation and health panel #39 — Project MCP install/health panel (closed). Dependency satisfied; this epic depends on that setup/status surface for recovery links but does not reopen installer work.
• [FEATURE] Add adversarial agent mode with default rules and project override editor #40 — Adversarial agent mode. Future live MCP grants depend on adversarial/security review; this epic does not wait on it and does not issue live grants.
• Add security review workforce architecture and subagent taxonomy #60 — Security review workforce architecture. Relevant for deferred live MCP grants and high-risk capability policy.
• P1: Technical hardening for DB-backed configuration, coding standards, and modularity #121 — DB-backed configuration and modularity. The eventual DB-backed MCP capability catalogue belongs there; S1 keeps the allow-list catalog-sourced in code as the precursor.
• [P0] Unify Forge agent/workforce model for Claude, Codex, editable prompts, and Workspace roadmap #124 — Unify Forge agent/workforce model. The admission contract sits under that unified runtime-neutral model.
• [FEATURE] Create pull requests and merge/rework gates from approved workforce output #69 — PR creation and merge/rework gates. Downstream; deferred until execution is reliable. This epic keeps writes on the sandbox/host-apply path.
• Build an AI-native issue tracker with GitHub sync and automatic Epic/Milestone grouping #42 — AI-native issue tracker. Where MCP requirements/assignments/execution design are stored and displayed.

Acceptance Criteria

• Forge has one documented MCP admission contract (docs/adr/0009-mcp-admission-contract.md) used by preview, approval, UI, and handoff. ([FEATURE] S1 — Unified MCP admission contract and capability taxonomy #176)
• The four admission code paths are thin adapters over one shared core; duplicated helpers are removed. ([FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177)
• A single invariant test proves grant preview, approval, and handoff produce the same canonical (mode, admissionStatus) for a fixed package and fixed health snapshot across all capability classes, the deny-wins-beats-optional case, a known-MCP typo, a required github read without materialized prompt context, all four requirement fields, and all three fallback actions. ([FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177, [FEATURE] S6 — End-to-end MCP admission regression (tiny task-tracker flow) and preview==handoff invariant #181)
• Plan approval runs the same admission decision as handoff over a captured MCP health snapshot, so a block already visible in the approval-time snapshot is surfaced at approval rather than missed until handoff. (Health/config can still change between approval and handoff; the guarantee is "no missed approval-time block", not "never blocks later".) ([FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177)
• filesystem.project.write is treated as planning-only (warn) or normalized into the sandbox write path — never a live MCP grant — consistently across all paths. ([FEATURE] S1 — Unified MCP admission contract and capability taxonomy #176, [FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177)
• Required filesystem read/list/search access is explicit, understandable, recoverable, and auditable; denying a required grant holds the package without burning an execution attempt; recovery is deterministic across endpoints. ([FEATURE] S3 — Deterministic bounded filesystem context grant/denial recovery #178)
• Live MCP tool handles are never issued to package runs; the bounded read-only context packet metadata (file names/counts/redaction summary, per ADR 0008) is attached to the run as inspectable evidence, while raw file contents stay prompt-only and are not persisted. ([FEATURE] S4 — Specialist prompt and bounded context packet assembly with run evidence #179)
• Every blocked MCP state names the exact missing grant / unhealthy MCP / unsupported capability / deferred feature, with the correct recovery action; a required deferred capability still offers revise_plan (actionable) while an optional one is approvable; deferred-live reads as a product boundary, not a broken install; planning-only context is visually separate from hard blockers. ([FEATURE] S5 — Unified operator UI copy and recovery-action contract for MCP admission #180)
• A representative end-to-end regression covers the tiny-task-tracker flow (frontend/QA/docs/review, prompt-only context, required filesystem read/search still gated, deferred capability reported as deferred). ([FEATURE] S6 — End-to-end MCP admission regression (tiny task-tracker flow) and preview==handoff invariant #181)
• npm run lint, npx tsc --noEmit, npm test, and npm run build pass for each slice.

[github-actions]

FORGE issue validation

This Epic issue now matches the required FORGE template structure.
The validator applied ready-for-agent and removed needs-clarification if it was present.