kandev/docs/plans/plugin-explicit-utility-invocation/task-01-host-contract.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
01-host-contract	Explicit host invocation contract	done	1		plan.md	REQ-PLUGINS-EXPLICIT-UTILITY-001	AC-PLUGINS-EXPLICIT-UTILITY-001.1 AC-PLUGINS-EXPLICIT-UTILITY-001.2 AC-PLUGINS-EXPLICIT-UTILITY-001.3 AC-PLUGINS-EXPLICIT-UTILITY-001.4 AC-PLUGINS-EXPLICIT-UTILITY-001.5 AC-PLUGINS-EXPLICIT-UTILITY-001.6 AC-PLUGINS-EXPLICIT-UTILITY-001.7 AC-PLUGINS-EXPLICIT-UTILITY-001.8 AC-PLUGINS-EXPLICIT-UTILITY-001.10 AC-PLUGINS-EXPLICIT-UTILITY-001.11 AC-PLUGINS-EXPLICIT-UTILITY-001.12	../../specs/plugins/system-design/plugin-explicit-utility-invocation.md

Task 01: Explicit host invocation contract

Summary

Implement the options API and safe wire method through the real SDK, host, and backend adapters. Remove implicit configuration routing and its obsolete transition machinery in the same compilable slice.

In scope

• Add UtilityAgentOptions, update Host implementations and test doubles, and regenerate proto stubs with make proto.
• Preserve old prompt-only wire calls as default requests. Never downgrade the revised SDK to the old RPC.
• Wire the existing default getter through a narrow interface; retain profile eligibility, late wiring, and final runner checks.
• Remove invocation-only utility lookup, legacy markers, install stamping, and hidden configuration preservation. Keep old files loadable.
• Add transport, selection, permissions, storage-error, cancellation, default-change, and reload regressions using TDD.

Out of scope

• General agent execution, cwd, session APIs, profile eligibility changes, and unrelated UI redesign.
• Work owned by other tasks. Do not revert their changes or the prior hydration and Windows CI fixes.

Acceptance

• Every default/override and legacy-wire branch selects the prescribed profile without reading plugin configuration.
• Unsupported hosts and invalid selections cannot execute a fallback profile.
• The backend compiles, targeted tests pass, and old serialized records load without retaining routing authority.

Verification

Use TDD for changed logic. Commands below run from the host repository root unless stated otherwise.

make -C apps/backend proto
(cd apps/backend && go test ./pkg/pluginsdk ./internal/plugins/... ./internal/backendapp ./internal/agent/hostutility ./internal/utility/profilebinding)
git diff --check

Files likely touched

• apps/backend/pkg/pluginsdk/host.go
• apps/backend/pkg/pluginsdk/host_data_test.go
• apps/backend/proto/kandev/plugin/v1/plugin.proto
• apps/backend/proto/kandev/plugin/v1/plugin.pb.go
• apps/backend/proto/kandev/plugin/v1/plugin_grpc.pb.go
• apps/backend/internal/plugins/host_utility.go
• apps/backend/internal/plugins/host_utility_test.go
• apps/backend/internal/plugins/host_data_wire_test.go
• apps/backend/internal/plugins/host.go
• apps/backend/internal/plugins/service.go
• apps/backend/internal/plugins/service_install.go
• apps/backend/internal/plugins/service_install_test.go
• apps/backend/internal/plugins/service_config.go
• apps/backend/internal/plugins/config_test.go
• apps/backend/internal/plugins/store/store.go
• apps/backend/internal/backendapp/main.go
• apps/backend/internal/backendapp/services.go
• apps/backend/internal/backendapp/services_plugin_utility_test.go

Dependencies

None.

Risks

• Changing SDK interfaces and wire semantics together requires all in-tree implementations to be migrated.

Parallelism

sequential

Inputs

• Requirement and design.
• Plan, including compatibility rules, evidence matrix, and delivery instructions.
• Existing SDK wire tests, host utility tests, and plugin-fixture patterns. Read changed source and local AGENTS.md before editing.

Results

Implemented. make -C apps/backend proto passed. The focused Go command passed for pkg/pluginsdk, internal/plugins/..., internal/backendapp, internal/agent/hostutility, and internal/utility/profilebinding. The cmd/mock-agent suite also passed, including TestPromptUsesCurrentSessionModel, which proves that ACP session model selection reaches prompt execution. git diff --check passed.

Host commit: eb9cfceda75cdc51c40efa289018e1a6f008d04a, pushed to PR #2870.