Files
kandev/docs/specs/tasks/mcp-task-agent-profile-default/spec.md
T

182 lines
9.2 KiB
Markdown

---
status: shipped
created: 2026-07-19
owner: kandev
---
# MCP-Created Task Agent Profile Default
## Why
Agents create tasks and subtasks through `create_task_kandev`. Most coding
harnesses start delegated work with the configuration of the agent session that
created it. Kandev instead uses the profile that originally started the source
task, which is opaque when a task has multiple sessions or a session changes its
model.
Users need a predictable default that follows the creating session. They also
need an explicit workspace-default policy for cost control.
## What
- Task Actions settings exposes a per-user **MCP-created task agent profile**
choice with two stored values:
- **Creating session profile** (`current_task`) uses the verified session that
called `create_task_kandev`. It copies that session's agent profile and its
effective model, mode, and dynamic options.
- **Workspace default profile** (`workspace_default`) skips the creating
session and task profiles. It uses the workflow profile, then the target
workspace default.
- `current_task` remains the stored default for new users and existing settings.
The label changes because the creating session, not the task's original
profile, owns the default.
- The preference applies to top-level tasks and subtasks created by
`create_task_kandev` when `agent_profile_id` is omitted.
- The session-bound MCP server supplies `source_task_id` and `source_session_id`.
These fields are server-owned context and are not tool arguments.
- The backend uses `source_session_id` only when the session exists and belongs
to `source_task_id`. A live agent cannot select another session as the source.
- The creating session's effective configuration is its profile snapshot plus
the latest provider runtime state and explicit runtime overrides. Later values
override earlier values.
- Kandev stores the copied effective configuration as the initial session's
runtime overrides. The copied values therefore beat later edits to the shared
agent profile.
- The copied runtime configuration applies only when the creating session's
profile wins profile resolution. Kandev does not mix the values into an
explicit profile, a workflow-selected profile, or the workspace-default
profile.
- An explicit `agent_profile_id` wins when the task does not land on a workflow
step. It also prevents a user-settings read and prevents creator runtime
inheritance.
- A task that lands on a workflow step uses that step's launch profile. This is
the step's pinned profile, or the workflow default when the step has no pinned
profile. This workflow profile wins over an explicit or inherited profile.
- In `current_task` mode, a call without verified session context keeps the
compatibility fallback: parent or source task, workflow default, then target
workspace default. This supports external MCP calls and deferred tasks that
have no session.
- In `workspace_default` mode, parent and source task profiles remain skipped.
The workflow profile wins before the target workspace default.
- Executor and executor-profile inheritance do not change. Subtasks continue to
inherit executor configuration from the parent. Top-level tasks continue to
inherit it from the source task.
- The resolved profile and initial runtime configuration persist when
`start_agent=false`. The first session uses both values when a user starts the
task later.
- The setting explains that `create_task_kandev` is the only affected tool. It
states that `spawn_session_kandev` and UI-created tasks are not affected.
- The setting remains usable at narrow mobile widths without clipped text,
hover-only information, or horizontal page scrolling.
## Data model
The existing JSON settings object in `users.settings` retains:
```text
mcp_task_agent_profile_default string enum: current_task | workspace_default
```
No user-settings migration is required. The `current_task` value now means the
verified creating session when one exists.
Task launch metadata gains a typed initial-session runtime configuration. It
contains the effective `model`, `mode`, and `config_options`. It contains no
credentials, prompts, or provider capability catalog.
The task session copies this launch configuration into its existing
`runtime_config_overrides` metadata when Kandev creates the initial session.
Later sessions do not copy the initial-session value.
## API surface
- The `create_task_kandev` public input and output schemas do not change.
- The session-bound MCP transport adds internal `source_session_id` context to
the backend request. External MCP mode sends no session ID.
- `GET /api/v1/user/settings`, `PATCH /api/v1/user/settings`, the
`user.settings.updated` event, and the SPA boot payload retain the existing
`current_task | workspace_default` values.
- The MCP tool description explains creating-session inheritance, effective
runtime configuration, override precedence, and the external fallback.
## Permissions
- Existing user-settings and task-creation permissions remain in force.
- The backend derives creator identity from the MCP server bound to the live
session. The tool caller cannot supply or override that identity.
- Session lookup uses the existing task-session access rules.
## Failure modes
- If a request contains server-supplied creator context that does not resolve to
the declared source task, task creation fails and creates no partial task.
- If Kandev cannot read the verified creator session, task creation fails and
creates no partial task.
- If `workspace_default` is selected and no workflow or target-workspace profile
exists, task creation returns a validation error and creates no task.
- If user settings cannot be read for an omitted-profile request, task creation
fails. An explicit profile does not read this setting.
- If a provider no longer supports a copied model or option, the existing
session-start error and model-fallback policy apply. Kandev does not silently
substitute the source task's original profile configuration.
## Persistence guarantees
- The user preference survives restart as portable user settings.
- The resolved profile and initial runtime configuration survive restart in task
metadata, including for `start_agent=false`.
- The initial task session receives an immutable copy of the launch seed in its
own runtime overrides. Later changes to the source session do not change it.
- Existing installations with no stored preference continue to normalize to
`current_task`.
## Scenarios
- **GIVEN** a task started with profile A and a second live session that uses
profile B, **WHEN** session B creates a task without `agent_profile_id`,
**THEN** the created task records profile B.
- **GIVEN** a live session changed from its profile model to another model and
selected a new reasoning value, **WHEN** it creates a task without
`agent_profile_id`, **THEN** the initial child session starts with the changed
model and reasoning value.
- **GIVEN** a live session creates a top-level task in the same workspace,
**WHEN** it omits `agent_profile_id`, **THEN** the new task inherits that
session's profile and effective runtime configuration.
- **GIVEN** a live session creates a subtask under another task, **WHEN** it
omits `agent_profile_id`, **THEN** the subtask inherits the creating session's
agent configuration and the parent task's executor configuration.
- **GIVEN** `current_task` is selected and an external MCP caller has no session,
**WHEN** it creates a subtask without `agent_profile_id`, **THEN** profile
resolution uses the parent task compatibility fallback.
- **GIVEN** `workspace_default` is selected, **WHEN** a live session creates a
task without `agent_profile_id`, **THEN** Kandev does not copy the source
session profile or runtime configuration.
- **GIVEN** a call supplies `agent_profile_id`, **WHEN** the target task does not
land on a workflow step, **THEN** Kandev uses that profile and does not copy
the creating session runtime configuration.
- **GIVEN** a workflow step selects profile W, **WHEN** a live session creates a
task on that step, **THEN** the created task uses profile W and does not copy
the creating session runtime configuration.
- **GIVEN** a live session creates a task with `start_agent=false`, **WHEN** the
user later starts its first session, **THEN** that session uses the persisted
creator profile and runtime configuration.
- **GIVEN** creator context names a session from another task, **WHEN** Kandev
handles the request, **THEN** creation fails before any task persists.
- **GIVEN** the Task Actions setting is open on a phone, **WHEN** the user reads
and changes the choice, **THEN** all precedence information is touch-visible
and the page has no horizontal overflow.
## Out of scope
- Changing profile resolution for UI-created tasks, API-created tasks,
automations, Office routing, utility agents, or `spawn_session_kandev`.
- Changing executor or executor-profile inheritance.
- Adding a third preference value or changing the stored enum names.
- Copying credentials, environment variables, CLI flags, or MCP configuration
from the creating session.
- Changing provider model fallback policy.
## Implementation plan
See [`../../../plans/creator-session-task-inheritance/plan.md`](../../../plans/creator-session-task-inheritance/plan.md).