Deepen prompt execution behind a Prompt Session

[derek-palmer]

Problem Statement

Prompt execution policy leaks across CLI and MCP adapters. The CLI validates task existence and emits scan-first warnings with FORERUNNER_SCAN_DONE; the MCP server validates tool names, checks task existence, tracks scan state, and blocks non-exempt tasks until scan is called. The bundle module is pure, but task ordering and session policy are duplicated at adapter edges.

Solution

Add a Prompt Session module that owns task lookup, scan-first enforcement, scan state, and bundle resolution. CLI and MCP should act as adapters to the Prompt Session rather than each reimplementing task ordering rules.

Implementation Decisions

• Build on the Task Registry from issue Deepen task metadata behind a Task Registry #45 if that lands first.
• Prompt Session owns scan-exempt policy and scan state.
• Prompt Session returns structured success/error results rather than printing directly.
• CLI adapter translates session results into stdout/stderr and exit codes.
• MCP adapter translates session results into JSON-RPC responses.
• bundle.py should remain focused on prompt text resolution.
• Keep CLI env-var compatibility for FORERUNNER_SCAN_DONE unless there is a deliberate migration plan.

Testing Decisions

• Unit test Prompt Session scan-first behavior directly.
• Unit test scan task marks the session as scan-complete.
• Unit test exempt tasks: scan and init-agent-onboarding.
• Keep adapter tests for CLI warnings/exit codes and MCP JSON-RPC errors.
• Verify CLI and MCP use the same task policy.

Out of Scope

• Changing prompt task content.
• Changing the scan-first invariant.
• Adding persistent cross-process session state.
• Replacing the MCP stdio transport.

Origin

This Deepening Opportunity came from /improve-codebase-architecture. It is the second candidate after Task Registry (#45).