Files
kandev/docs/specs/tasks/mcp-task-agent-profile-default/spec.md
T
2026-07-19 23:18:06 +01:00

98 lines
9.5 KiB
Markdown

---
status: shipped
created: 2026-07-19
owner: kandev
---
# MCP-Created Task Agent Profile Default
## Why
Agents can create tasks and subtasks through `create_task_kandev`. When the tool call omits `agent_profile_id`, inheriting the calling task's profile can unintentionally select an expensive model instead of the workspace's configured default. Users need a durable choice between preserving that inheritance behavior and using the target workspace's default profile.
## What
- Task Actions settings exposes a per-user **MCP-created task agent profile** choice with two values:
- **Current task profile** (`current_task`): preserve the existing profile-resolution behavior.
- **Workspace default profile** (`workspace_default`): skip the current task profile, honor any workflow profile, then use the default agent profile of the workspace that owns the new task.
- `current_task` is the default for new users and for existing settings that do not contain the preference. Selecting `workspace_default` is opt-in.
- The preference applies only to tasks and subtasks created by `create_task_kandev` when `agent_profile_id` is omitted.
- An explicit `agent_profile_id` always wins and does not require the preference to be read.
- The setting explains in visible, plain language that Kandev makes this decision when an agent calls a task-creating Kandev MCP tool without `agent_profile_id`. It identifies `create_task_kandev` as the only affected tool, covers both new tasks and subtasks, names `spawn_session_kandev` as unaffected, and states that an explicitly chosen profile wins. A secondary help tooltip explains why adding a session does not create a new profile-resolution decision. Each option describes both its resolution behavior and when to choose it, including the risk that current-task inheritance can reuse a more expensive profile.
- In `current_task` mode, the existing fallback order remains unchanged: parent task or calling source task, workflow step or workflow default, then target workspace default.
- In `workspace_default` mode, parent/source task inheritance is skipped. The profile resolves from the workflow step or workflow default first, then from the target workspace default. This preserves workflow policy while avoiding inheritance from the calling task.
- Executor and executor-profile inheritance are unchanged in both modes.
- The selected profile is persisted in the created task's launch metadata even when `start_agent=false`, matching the existing deferred-start contract.
- The setting is portable per-user state. It applies across workspaces, while `workspace_default` dynamically resolves against each new task's target workspace.
- The setting is usable at narrow mobile widths without horizontal page scrolling, clipped labels, or hover-only interaction.
## Data model
The existing JSON settings object in `users.settings` gains:
```text
mcp_task_agent_profile_default string enum: current_task | workspace_default
```
The value is non-null in the normalized user-settings model. Missing or unrecognized stored values normalize to `current_task` for backward and forward compatibility. PATCH requests accept only the two documented values.
No relational schema migration is required because user settings are stored as JSON.
## API surface
The existing user-settings contracts gain `mcp_task_agent_profile_default`:
- `GET /api/v1/user/settings` returns `settings.mcp_task_agent_profile_default` as `current_task` or `workspace_default`.
- `PATCH /api/v1/user/settings` accepts an optional `mcp_task_agent_profile_default`. Omission leaves the value unchanged; an unsupported value returns the existing validation response and does not update settings.
- `user.settings.updated` includes `mcp_task_agent_profile_default` so open clients converge on the saved value.
- The Go-served SPA boot settings include `userSettings.mcpTaskAgentProfileDefault` with the same normalized enum value.
The `create_task_kandev` input and response schemas do not change. The preference changes server-side resolution only when its existing optional `agent_profile_id` input is empty. Its MCP tool description explains the two server-side default modes and states that workflow step/default profiles retain precedence over the workspace default.
## Permissions
- A user who can read or update their existing user settings can read or update this preference.
- The preference does not grant task-creation or agent-profile permissions. Existing `create_task_kandev`, workspace, workflow, and profile authorization rules remain in force.
## Failure modes
- If `workspace_default` is selected and neither the task's workflow nor the target workspace supplies an agent profile, `create_task_kandev` returns a validation error and creates no task, regardless of `start_agent`.
- If a workspace lookup required by the selected resolution chain fails, task creation fails and creates no partial task.
- If user settings cannot be read for an omitted-profile request, task creation fails and creates no partial task; the server does not silently choose another policy.
- An explicit `agent_profile_id` continues through existing validation and resolution even if reading the preference would fail.
- Changing the choice creates a local settings draft. The preference is persisted only when the user chooses **Save changes**; a failed save keeps the draft selected and leaves the stored preference unchanged.
## Persistence guarantees
- The preference survives backend restarts and frontend reloads as part of backend-owned portable user settings.
- Existing installations with no stored field behave exactly as `current_task`.
- Saving the preference publishes the existing user-settings update event; no browser storage is a durable fallback.
- Created tasks retain the resolved agent profile in task metadata, so later session creation does not re-evaluate a changed preference.
## Scenarios
- **GIVEN** an existing user with no stored preference, **WHEN** Task Actions settings loads, **THEN** **Current task profile** is selected.
- **GIVEN** a user opens the setting without knowing MCP terminology, **WHEN** they read the control, **THEN** they can tell when it applies, what each option does, which option controls accidental model cost, and that an explicit profile selection overrides it.
- **GIVEN** a user needs to know which Kandev MCP calls use the setting, **WHEN** they read the control, **THEN** they can see that `create_task_kandev` is affected for new tasks and subtasks while `spawn_session_kandev` and UI-created tasks are not, without relying on the help tooltip.
- **GIVEN** `current_task` is selected and the calling task uses profile A while its workspace default is profile B, **WHEN** the agent creates a task without `agent_profile_id`, **THEN** the created task records profile A under the existing resolution rules.
- **GIVEN** `workspace_default` is selected, the calling task uses profile A, no workflow profile applies, and the target workspace default is profile B, **WHEN** the agent creates a top-level task without `agent_profile_id`, **THEN** the created task records profile B.
- **GIVEN** `workspace_default` is selected, a parent task uses profile A, no workflow profile applies, and its workspace default is profile B, **WHEN** the agent creates a subtask without `agent_profile_id`, **THEN** the subtask records profile B and retains the existing executor inheritance.
- **GIVEN** `workspace_default` is selected and the target workflow step or workflow default supplies profile W, **WHEN** the agent creates a task without `agent_profile_id`, **THEN** the created task records profile W instead of the caller or workspace-default profile.
- **GIVEN** `workspace_default` is selected and no workflow profile applies, **WHEN** the agent creates a task in a different workspace without `agent_profile_id`, **THEN** the new task uses that target workspace's default rather than the caller's workspace default.
- **GIVEN** either preference is selected, **WHEN** `create_task_kandev` includes profile C explicitly, **THEN** the created task records profile C.
- **GIVEN** `workspace_default` is selected and neither the workflow nor the target workspace has a default agent profile, **WHEN** an agent creates a task without `agent_profile_id`, **THEN** the tool returns a validation error and no task exists.
- **GIVEN** `workspace_default` is selected, no workflow profile applies, and a workspace default exists, **WHEN** an agent creates a task with `start_agent=false` and no `agent_profile_id`, **THEN** the task is created without a session and records the target workspace default for later launch.
- **GIVEN** the setting is open on a mobile viewport, **WHEN** the user selects **Workspace default profile** and chooses **Save changes**, **THEN** the choice saves and remains selected after reload without horizontal overflow.
- **GIVEN** a settings update fails, **WHEN** the user chooses **Save changes**, **THEN** the draft remains selected, the page shows the save failure, and the stored preference is unchanged.
## Out of scope
- Changing profile resolution for UI-created tasks, API-created tasks, automations, Office routing, or `spawn_session_kandev`.
- Changing workspace default profile configuration or agent-profile lifecycle rules.
- Changing executor or executor-profile inheritance.
- Selecting a specific profile directly from Task Actions settings; the tool's explicit `agent_profile_id` remains the per-call override.
## Implementation plan
See [`../../../plans/mcp-task-agent-profile-default/plan.md`](../../../plans/mcp-task-agent-profile-default/plan.md).