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

spec, created, status

spec	created	status
docs/specs/tasks/requirements/mcp-task-agent-profile-default.md	2026-08-12	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:

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:

• task-01-initial-runtime-seed

Wave 2:

• task-02-creator-session-resolution

Wave 3:

• task-03-explain-session-default

Wave 4:

• task-04-end-to-end-inheritance

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.