Carlos Florêncio
61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
---
|
|
status: shipped
|
|
created: 2026-08-12
|
|
owner: 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:
|
|
|
|
```json
|
|
{
|
|
"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`](../../plans/spawn-session-effective-profile/plan.md).
|