182 lines
9.2 KiB
Markdown
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).
|