Files
kandev/docs/specs/agents/requirements/spawn-session-effective-profile.md
T
2026-08-24 11:09:03 +00:00

90 lines
4.7 KiB
Markdown

---
status: active
system: agents
created: 2026-08-12
owners:
- kandev
---
# Spawn Session Effective Agent Profile Requirements
## Overview
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.
## Requirements
### REQ-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001: Spawn Session Effective Agent Profile
**Intent:** 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.
#### Acceptance criteria
- **AC-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001.1:** `spawn_session_kandev` reports the effective agent profile for each successful launch.
- **AC-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001.2:** The reported profile is the profile on the new session, after workflow profile resolution.
- **AC-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001.3:** A workflow step launch profile keeps its current precedence. A pinned step profile wins first. Otherwise, the workflow default wins on that step.
- **AC-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001.4:** Without a workflow launch profile, an explicit `agent_profile_id` keeps its current precedence.
- **AC-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001.5:** Without an explicit profile, the current inheritance rules remain unchanged.
- **AC-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001.6:** The tool description explains the precedence and the response field.
- **AC-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001.7:** **GIVEN** an unpinned workflow step with workflow default A, **WHEN** a caller requests profile B, **THEN** the new session and response use profile A.
- **AC-AGENTS-SPAWN-SESSION-EFFECTIVE-PROFILE-001.8:** **GIVEN** a workflow step pinned to profile A, **WHEN** a caller requests profile B, **THEN** the new session and response use profile A.
## Migrated source detail
## 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.
- If the task workspace is still materializing, the tool returns `CONFLICT`
with `reason: workspace_preparing`, `recoverable: true`, and retry guidance.
- If the canonical workspace cannot be safely attached, the tool returns
`CONFLICT` with `reason: workspace_reuse_unsafe`; it never provisions a
replacement checkout as part of spawning a session.
- 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).