kandev/docs/specs/plugins/requirements/plugin-explicit-utility-invocation.md

status, system, created, owners

status	system	created	owners
active	plugins	2026-09-14	kandev

Explicit Plugin Utility Invocation Requirements

Overview

The plugin system owns the public Host invocation contract. Agent settings own profiles and the platform default utility profile. A plugin can save a preferred profile in its configuration. It must pass that preference explicitly when it requests a completion. These requirements replace REQ-PLUGINS-DIRECT-PROFILE-INVOCATION-001. The user accepted this direction after review of PR #2870. The implementation and verification are recorded in the implementation plan.

Terminology

• Default profile: the profile selected in Settings > Utility Agents under Default utility agent model.
• Override: an agent-profile ID supplied in a single invocation. It is not a utility-agent record ID.
• Plugin preference: a profile ID saved by the plugin through the existing configuration service.
• Utility completion: one prompt and one text response, without a task session or caller-selected working directory.

Requirements

REQ-PLUGINS-EXPLICIT-UTILITY-001: Explicit utility execution selection

Intent: Make execution selection visible in the invocation contract and keep plugin configuration ownership with the caller.

Acceptance criteria

• AC-PLUGINS-EXPLICIT-UTILITY-001.1: When the caller omits an override or supplies an empty profile ID, the host shall use the current default profile.
• AC-PLUGINS-EXPLICIT-UTILITY-001.2: When the caller supplies an eligible profile ID, the host shall use that exact profile, independent of the default.
• AC-PLUGINS-EXPLICIT-UTILITY-001.3: Plugin configuration, field names, manifest selectors, and legacy transition metadata shall not determine invocation selection.
• AC-PLUGINS-EXPLICIT-UTILITY-001.4: A missing or ineligible explicit override shall return FailedPrecondition without executing a different profile.
• AC-PLUGINS-EXPLICIT-UTILITY-001.5: An unset, missing, or ineligible default shall return FailedPrecondition when the caller omits an override.
• AC-PLUGINS-EXPLICIT-UTILITY-001.6: Without agent_invoke permission, the call shall fail before settings access, profile lookup, or execution.
• AC-PLUGINS-EXPLICIT-UTILITY-001.7: Cancellation and operational failures shall remain distinct from configuration failures. No failure shall trigger implicit profile fallback.
• AC-PLUGINS-EXPLICIT-UTILITY-001.8: Changes to the default shall affect subsequent default invocations. A default change shall not redirect an explicit override or an invocation already dispatched.
• AC-PLUGINS-EXPLICIT-UTILITY-001.9: The plugin shall read its saved preference and pass it explicitly. Saving, clearing, and reloading a preference shall preserve that behavior.
• AC-PLUGINS-EXPLICIT-UTILITY-001.10: A host that cannot honor the explicit selection contract shall reject the new client call before execution. It shall not silently ignore an override.
• AC-PLUGINS-EXPLICIT-UTILITY-001.11: Existing prompt-only clients on the revised host shall use the platform default. Migration documentation shall state this behavior change.
• AC-PLUGINS-EXPLICIT-UTILITY-001.12: Invocation shall remain a single text completion. It shall not create a task, session, or worktree, or accept a caller-selected working directory.

Out of scope

• General agent execution, cwd, streaming, tools, session lifecycle, and arbitrary execution options.
• Changes to eligibility: profiles remain enabled, global, non-CLI-passthrough, and explicitly inference-capable.
• UI redesign, new configuration storage, automatic conversion of utility-agent record IDs into profile IDs, or new capability grants.