kandev/docs/plans/plugin-agent-tools/task-04-runtime-propagation-backend-dispatch.md

id, title, status, wave, depends_on, plan, spec, adr

id	title	status	wave	depends_on	plan	spec	adr
04-runtime-propagation-backend-dispatch	Runtime propagation and backend dispatch	done	3	02-plugin-catalog-invocation 03-agentctl-dynamic-registry	plan.md	../../specs/plugins/requirements/agent-tools.md	../../decisions/2026-08-11-plugin-tools-through-kandev-mcp.md

Task 04: Runtime propagation and backend dispatch

Acceptance

• Launch and resume profiles include the current catalog, while Configuration and External surfaces expose no plugin tools.
• A scoped backend MCP action verifies the bound task/session pair and current plugin declaration before one plugin RPC, and maps valid text/structured/error results back to agentctl.
• A serialized backendapp refresher pushes each effective snapshot to every active execution, continues after individual failures, and leaves later launch/resume or refresh able to repair stale runtime state.

Verification

cd apps/backend && go test -race ./internal/mcp/handlers ./internal/mcp/scope ./internal/orchestrator/executor ./internal/agent/runtime/lifecycle ./internal/backendapp

Files likely touched

• apps/backend/pkg/websocket/actions.go
• apps/backend/internal/mcp/handlers/handlers.go
• apps/backend/internal/mcp/handlers/plugin_tools.go
• apps/backend/internal/mcp/handlers/plugin_tools_test.go
• apps/backend/internal/orchestrator/executor/executor.go
• apps/backend/internal/orchestrator/executor/executor_execute.go
• apps/backend/internal/orchestrator/executor/executor_mcp_mode_test.go
• apps/backend/internal/agent/runtime/lifecycle/manager_launch.go
• apps/backend/internal/agent/runtime/lifecycle/manager_mcp_plugin_tools_test.go
• apps/backend/internal/backendapp/plugin_tool_refresher.go
• apps/backend/internal/backendapp/plugin_tool_refresher_test.go
• apps/backend/internal/backendapp/main.go

Dependencies

Tasks 02 and 03.

Parallelism

Sequential. This task joins shared plugin, MCP, orchestrator, lifecycle, and backendapp contracts.

Inputs

• Spec Permissions, Failure Modes, and hot-refresh scenarios
• Root/backend auth scoping guidance for in-session MCP
• Existing provider live refresher, resolveTaskSessionMCPProfile, lifecycle SetMcpProvidersForSession, and MCP dispatcher patterns

Risks

• A handler that trusts agent-supplied task/session IDs creates a cross-user authorization defect. Use only server-bound identity and authorize first.
• Out-of-order or blocking catalog propagation can restore stale tools or stall plugin supervision.

Output contract

Report the exact identity/authorization chain, refresh serialization and failure behavior, launch/resume wiring, commands and results, and task/plan status updates.

Results

• Added mcp.list_plugin_tools and mcp.invoke_plugin_tool actions with task / session binding checks, surface filtering, and service dispatch.
• Wired the plugin service into backend MCP handler registration and preserved existing identity scoping.
• Added the agentctl plugin-tool control endpoint, lifecycle fan-out, and a coalescing backendapp refresher wired to plugin lifecycle notifications.
• Agentctl retains the complete revisioned catalog and applies surface filters while rebuilding the active MCP profile, so live surface changes do not lose declarations.
• Verification: go test -race ./internal/mcp/handlers ./internal/mcp/scope ./internal/orchestrator/executor ./internal/agent/runtime/lifecycle ./internal/backendapp passed.