kandev/docs/plans/creator-session-task-inheritance/plan.md

---
spec: docs/specs/tasks/requirements/mcp-task-agent-profile-default.md
created: 2026-08-12
status: complete
---

# Implementation Plan: Creator-Session Task Inheritance

## Overview

Replace task-origin profile inheritance with verified creator-session
inheritance for session-bound `create_task_kandev` calls. First add a typed
initial-session runtime seed. Then carry trusted session identity through the MCP
transport and apply the seed during profile resolution. Update the visible
setting, tool contract, public docs, and existing desktop/mobile E2E coverage.

## Backend

### Initial-session runtime seed

- Add a task metadata key in `apps/backend/internal/task/models/models.go` for
  the initial session runtime configuration.
- Add a model helper that resolves one effective `SessionRuntimeConfig` from a
  task session. Start with `AgentProfileSnapshot`, then apply
  `runtime_config`, `session_mode`, and `runtime_config_overrides` in precedence
  order. Clone option maps so source and target metadata never alias.
- In `apps/backend/internal/orchestrator/executor/executor_execute.go`, map the
  task launch seed to `SessionMetaKeyRuntimeConfigOverrides` only when
  `PrepareSession` creates the task's initial session. Remove the launch-only
  key from the session metadata copy.
- Cover profile-only state, live runtime updates, explicit overrides, option
  replacement, and initial-versus-later session preparation.

### Trusted creator context

- In `apps/backend/internal/mcp/server/handlers.go`, add the server's own
  `sessionID` to the create-task backend payload as `source_session_id`. Keep it
  absent in external mode.
- In `apps/backend/internal/mcp/handlers/handlers.go`, parse the internal field
  and load it through `taskSvc.GetTaskSession`. Require the session's `TaskID`
  to equal `source_task_id` before using any profile or runtime data.
- Refactor `resolveMCPAutoStartConfigWithError` to return profile, executor, and
  optional initial runtime seed. In `current_task` mode, a verified creator
  session wins over parent/source task profile metadata for both top-level tasks
  and subtasks.
- Preserve the existing executor chain. A subtask still inherits executor state
  from its parent. A top-level task still inherits it from its source task.
- Persist the runtime seed beside the resolved task launch profile before
  `CreateTask`, including when `start_agent=false`.
- Suppress the seed when `agent_profile_id` is explicit, when a workflow launch
  profile wins, or when the user selected `workspace_default`.
- Fail before task persistence when supplied session context cannot be verified.
  Calls with no session context retain the current parent/source compatibility
  fallback.

### MCP contract text

- Update `apps/backend/internal/mcp/server/server.go` so task-mode descriptions
  name the creating session and its effective configuration.
- Keep external-mode descriptions explicit that there is no creating session
  and that `current_task` falls back to the parent task.
- Add focused schema/description and forwarded-payload tests in
  `apps/backend/internal/mcp/server/handlers_test.go` and `server_test.go`.

## Frontend

### Task Actions setting

- Change the visible `current_task` label to **Creating session profile** in
  `apps/web/src/locales/en/settings.json` and every locale catalog.
- Rewrite the setting description and option help in
  `apps/web/components/settings/mcp-task-agent-profile-default-settings.tsx`.
  State the affected tool, effective model/options behavior, precedence, cost
  risk, external fallback, and exclusions without relying on hover help.
- Update the component test to prove that the saved enum remains `current_task`
  and that the new explanation is visible.

Mobile uses the existing Task Behavior page and radio-card layout. The nearest
mobile exemplar is the shipped settings card in
`mobile-mcp-task-agent-profile-default.spec.ts`. The page remains the single
scroll owner. Radio rows retain 44px touch targets, and all explanatory text
wraps inside the card without horizontal overflow.

## Public documentation

- Update the explanation section in `docs/public/tasks-and-workflows.md`. This
  page remains an explanation page with a short configuration procedure.
- Explain that `current_task` follows the creating session for live task-mode
  calls, including model and reasoning changes. Document the external fallback
  and the cases that prevent runtime inheritance.

## Tests

- **What:** effective creator configuration merges profile snapshot, provider
  state, session mode, and explicit overrides.
  **File:** `apps/backend/internal/task/models/session_runtime_config_test.go`.
  **How:** table-driven unit tests with cloned-map assertions.
- **What:** only the initial task session receives the persisted runtime seed.
  **File:** `apps/backend/internal/orchestrator/executor/executor_test.go`.
  **How:** prepare two sessions and inspect their persisted metadata.
- **What:** the MCP server forwards its bound session identity and external mode
  does not invent one.
  **File:** `apps/backend/internal/mcp/server/handlers_test.go`.
  **How:** focused handler payload tests.
- **What:** a verified non-primary session wins task profile resolution for a
  subtask and a top-level task, while executor inheritance remains unchanged.
  **File:** `apps/backend/internal/mcp/handlers/create_task_creator_session_test.go`.
  **How:** service-backed handler tests with two source-task sessions.
- **What:** explicit, workflow, and workspace-default profiles suppress copied
  runtime values. Mismatched session identity fails before persistence.
  **File:** `apps/backend/internal/mcp/handlers/create_task_creator_session_test.go`.
  **How:** table-driven handler and resolver tests.
- **What:** the renamed setting retains the `current_task` wire value and shows
  the precedence contract.
  **File:**
  `apps/web/components/settings/mcp-task-agent-profile-default-settings.test.tsx`.
  **How:** rendered component assertions and save-payload assertion.

## E2E Tests

- **Scenario:** a second session uses another profile and changes model/options,
  then creates a subtask and a top-level task.
  **File:** `apps/web/e2e/tests/task/subtask.spec.ts`.
  **What to verify:** both created initial sessions use the creator profile and
  effective runtime values. The subtask keeps the parent executor profile.
- **Scenario:** workspace-default policy prevents creator-session inheritance.
  **File:**
  `apps/web/e2e/tests/task/mcp-task-agent-profile-default.spec.ts`.
  **What to verify:** the created session uses the target workspace profile and
  does not contain the creator runtime seed.
- **Scenario:** the revised setting is touch-readable and viewport-safe.
  **File:**
  `apps/web/e2e/tests/task/mobile-mcp-task-agent-profile-default.spec.ts`.
  **What to verify:** the new label and explanation are visible, the option
  persists, each choice remains touch-usable, and no horizontal overflow occurs.

## Verification Results

All implementation waves are complete. The focused backend, frontend, i18n,
documentation, and managed E2E checks pass:

```text
rtk go test ./internal/mcp/server ./internal/mcp/handlers ./internal/task/models ./internal/task/service ./internal/orchestrator/executor -count=1  PASS
rtk go test ./internal/task/repository/sqlite -run TestCreateTaskSessionWithInitialRuntimeSeedConsumesOnceAcrossConcurrentAndReplacementSessions -count=1  PASS
GOCACHE=/tmp/kandev-go-build GOLANGCI_LINT_CACHE=/tmp/kandev-golangci-lint make lint  PASS
pnpm --filter @kandev/web test -- components/settings/mcp-task-agent-profile-default-settings.test.tsx  PASS (4 tests)
pnpm --filter @kandev/web typecheck  PASS
pnpm --filter @kandev/web i18n:check  PASS (existing locale parity/orphan advisories only)
node --test scripts/validate-public-docs.test.mjs  PASS (60 tests)
node scripts/validate-public-docs.mjs  PASS (41 public pages)
pnpm e2e:run --no-build tests/task/subtask.spec.ts  PASS (15 tests)
pnpm e2e:run --no-build tests/task/mcp-task-agent-profile-default.spec.ts  PASS (1 test)
pnpm e2e:run --no-build --project mobile-chrome tests/task/mobile-mcp-task-agent-profile-default.spec.ts  PASS (1 test)
```

The PR capture run also passed and produced validated, compressed desktop and
mobile settings screenshots in the ignored `.pr-assets` directory.

Review follow-up added the repository-level persistence guarantee for the
launch-only seed. Session creation now reads and removes the seed in the same
transaction as the first-session insert, and the SQLite regression covers
concurrent launches plus deletion and replacement of the seed-bearing session.
The MCP server also omits `source_session_id` unless its bound task context is
present.

## Implementation Waves And Parallel Candidates

The default is sequential execution in the primary conversation. These waves do
not authorize subagents.

Wave 1:
- [x] [task-01-initial-runtime-seed](task-01-initial-runtime-seed.md)

Wave 2:
- [x] [task-02-creator-session-resolution](task-02-creator-session-resolution.md)

Wave 3:
- [x] [task-03-explain-session-default](task-03-explain-session-default.md)

Wave 4:
- [x] [task-04-end-to-end-inheritance](task-04-end-to-end-inheritance.md)

## Risks

- Task metadata is copied into every prepared session today. The executor must
  translate the launch-only seed only for the initial session and must not leak
  the task-only key into session metadata.
- Runtime options are provider-specific. Copy them only with the verified
  creator profile. Never mix them into another resolved profile.
- Workflow profile precedence is subtle. Tests must cover a pinned step, an
  unpinned step with a workflow default, and a stepless workflow.
- `source_session_id` is trusted attribution. It must stay server-injected and
  must be checked against `source_task_id` before use.