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

status, created, owner

status	created	owner
shipped	2026-07-19	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:

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.