kandev/docs/specs/spawn-session-effective-profile/spec.md

status, created, owner

status	created	owner
shipped	2026-08-12	kandev

Spawn Session Effective Agent Profile

Why

Agents use spawn_session_kandev to start another session with a selected agent profile. The tool must report the profile that the new session uses.

Without this guarantee, a caller can receive confirmation for one profile while a workflow profile starts instead.

What

• spawn_session_kandev reports the effective agent profile for each successful launch.
• The reported profile is the profile on the new session, after workflow profile resolution.
• A workflow step launch profile keeps its current precedence. A pinned step profile wins first. Otherwise, the workflow default wins on that step.
• Without a workflow launch profile, an explicit agent_profile_id keeps its current precedence.
• Without an explicit profile, the current inheritance rules remain unchanged.
• The tool description explains the precedence and the response field.

API surface

The successful spawn_session_kandev response has this shape:

{
  "task_id": "string",
  "session_id": "string",
  "state": "string",
  "agent_profile_id": "string"
}

agent_profile_id identifies the effective profile on the new session. It does not echo an earlier profile choice when workflow resolution selects another profile.

Failure modes

• If the session launch fails, the tool returns the existing launch error and no success response.
• A successful session launch returns the nonempty effective profile from the launch result.
• A session name update can still fail without changing the successful launch result.

Scenarios

• GIVEN an unpinned workflow step with workflow default A, WHEN a caller requests profile B, THEN the new session and response use profile A.
• GIVEN a workflow step pinned to profile A, WHEN a caller requests profile B, THEN the new session and response use profile A.
• GIVEN no workflow launch profile, WHEN a caller requests profile B, THEN the new session and response use profile B.
• GIVEN no explicit profile or workflow launch profile, WHEN a same-task session spawns another session, THEN the new session and response use the inherited profile.

Out of scope

• Changing workflow, step, explicit, or inherited profile precedence.
• Changing create_task_kandev. Its workflow-default response behavior is already covered by the MCP-created task profile spec.
• Changing session persistence, executor selection, or profile validation.

Implementation plan

See ../../plans/spawn-session-effective-profile/plan.md.