feat(v0.6): launch path carries ResolvedAgent (command + args + env)

LaunchOpts.Agent (string) and WorkspaceEntryOptions.Agent (string) are
replaced by *agent.Resolved, carrying Command, Args, and Env. The five
entry commands (new, resume, last, open, attach) each construct an
AgentSpec from the workspace metadata, apply --agent as a one-shot
agent.command override (Open Q 1 — keeps muscle memory for users
passing executable paths), call agent.Resolve, and pass the result
through. resolveEntryAgent centralises the resume/last/open/attach path.

shell.ExecAgent and shell.ExecTmuxAgent gain an args parameter; agent.env
is merged into the env map at the session.Run launch switch, AFTER
ctask's exported CTASK_* vars (per spec §5: agent.env wins on collision).
mergeAgentEnv is the centralised merge.

Lease, manifest, write lock, heartbeat, summary, and provisional
cleanup are unchanged. The Agent string fields on Lease, SessionSummary,
and SessionInfo continue to record the launched command for diagnostics.

internal/session/adopt.go

@@ -68,7 +68,7 @@ func AdoptExistingPersistentSession(tmuxPath, sessionName, wsDir string, opts La
 				fmt.Fprintf(os.Stderr,
 					"[ctask] warning: failed to remove orphaned lease: %v\n", rmErr)
 			}
-			lease := NewLease(startTime, opts.Agent, opts.Mode)
+			lease := NewLease(startTime, leaseAgentCommand(opts), opts.Mode)
 			if err := WriteLease(leasePath, lease); err != nil {
 				return fmt.Errorf("writing lease: %w", err)
 			}
@@ -152,12 +152,12 @@ func finalizeAdopted(opts LaunchOpts, wsDir string, startManifest *Manifest, sta
 	}
 	diff := DiffManifests(startManifest, endManifest)
 
-	agent := opts.Agent
+	agentCmd := leaseAgentCommand(opts)
 	if opts.Shell {
-		agent = "shell"
+		agentCmd = "shell"
 	}
 	info := &SessionInfo{
-		Agent:     agent,
+		Agent:     agentCmd,
 		Mode:      opts.Mode,
 		StartTime: startTime,
 		EndTime:   endTime,
@@ -170,7 +170,7 @@ func finalizeAdopted(opts LaunchOpts, wsDir string, startManifest *Manifest, sta
 	}
 
 	summary := SummarizeFromDiff(
-		sessionID, currentHostname(), agent, opts.Mode,
+		sessionID, currentHostname(), agentCmd, opts.Mode,
 		startTime, endTime, diff, endManifest,
 	)
 	summary.EndReason = "tmux_session_ended"

internal/session/adopt_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/warrenronsiek/ctask/internal/agent"
 	"github.com/warrenronsiek/ctask/internal/workspace"
 )
 
@@ -76,14 +77,14 @@ func (fx *adoptionFixture) stubSeams(t *testing.T) {
 
 func defaultAdoptionOpts(wsDir string) LaunchOpts {
 	return LaunchOpts{
-		WsDir:       wsDir,
-		Agent:       "claude",
-		Mode:        "local",
-		Slug:        "demo",
-		Category:    "projects",
-		SessionMode: "persistent",
-		SessionName: "ctask-projects-demo-abc123",
-		TmuxPath:    "/usr/bin/tmux",
+		WsDir:         wsDir,
+		ResolvedAgent: &agent.Resolved{Command: "claude"},
+		Mode:          "local",
+		Slug:          "demo",
+		Category:      "projects",
+		SessionMode:   "persistent",
+		SessionName:   "ctask-projects-demo-abc123",
+		TmuxPath:      "/usr/bin/tmux",
 	}
 }
 

internal/session/run.go

@@ -7,19 +7,57 @@ import (
 	"path/filepath"
 	"time"
 
+	"github.com/warrenronsiek/ctask/internal/agent"
 	"github.com/warrenronsiek/ctask/internal/lockfile"
 	"github.com/warrenronsiek/ctask/internal/shell"
 	"github.com/warrenronsiek/ctask/internal/workspace"
 )
 
+// execAgent is the test seam for the direct-mode child launch. Tests
+// replace this to capture the (command, args, wsDir, env) tuple Run
+// would have passed to shell.ExecAgent. Restored via t.Cleanup.
+var execAgent = shell.ExecAgent
+
+// mergeAgentEnv overlays agentEnv on top of base, returning a new map.
+// Per v0.6 spec §5 ("merged into the agent's environment, after ctask's
+// own exported vars"), agentEnv keys WIN on collision — the spec is
+// explicit that user-supplied env vars take precedence. Callers that
+// want a warning for shadowed CTASK_* keys must emit it themselves
+// (ctask agents check surfaces this).
+func mergeAgentEnv(base, agentEnv map[string]string) map[string]string {
+	out := make(map[string]string, len(base)+len(agentEnv))
+	for k, v := range base {
+		out[k] = v
+	}
+	for k, v := range agentEnv {
+		out[k] = v
+	}
+	return out
+}
+
+// leaseAgentCommand returns the command string recorded in leases and
+// summaries for diagnostics. A nil ResolvedAgent yields "" (only happens
+// in tests that do not exercise a launch).
+func leaseAgentCommand(opts LaunchOpts) string {
+	if opts.ResolvedAgent != nil {
+		return opts.ResolvedAgent.Command
+	}
+	return ""
+}
+
 // LaunchOpts configures a session launch.
 type LaunchOpts struct {
 	WsDir   string
 	EnvVars map[string]string
-	Agent   string
-	Mode    string
-	Slug    string
-	Shell   bool // true = interactive shell, false = agent
+
+	// ResolvedAgent is the launch-ready agent (command + args + env),
+	// produced by the cmd layer via agent.Resolve. Required in agent mode;
+	// in shell mode it is still populated for lease/summary diagnostics.
+	ResolvedAgent *agent.Resolved
+
+	Mode  string
+	Slug  string
+	Shell bool // true = interactive shell, false = agent
 
 	// LaunchDir is the workspace-relative launch directory (v0.5). Empty for
 	// tasks and pre-v0.5 projects. When set, Run resolves the absolute path
@@ -127,7 +165,7 @@ func Run(opts LaunchOpts) error {
 	leasePath := LeasePath(opts.WsDir)
 	ownLease := !preflight.ActiveLeaseFound
 	if ownLease {
-		lease := NewLease(startTime, opts.Agent, opts.Mode)
+		lease := NewLease(startTime, leaseAgentCommand(opts), opts.Mode)
 		skipped, lockErr := lockfile.WithLock(
 			ctaskWriteLockPath(opts.WsDir),
 			sessionWriteLockTimeout, sessionWriteLockStaleAfter,
@@ -187,6 +225,15 @@ func Run(opts LaunchOpts) error {
 		fmt.Fprintln(os.Stderr, launchWarn)
 	}
 
+	// Agent-launch branches dereference ResolvedAgent; a nil here is an
+	// internal wiring bug (the cmd layer must always Resolve before Run).
+	if !opts.Shell && opts.ResolvedAgent == nil {
+		if hb != nil {
+			hb.Stop()
+		}
+		return fmt.Errorf("internal error: LaunchOpts.ResolvedAgent is nil in agent mode")
+	}
+
 	// ---- Run the child ----
 	var childErr error
 	switch {
@@ -213,7 +260,9 @@ func Run(opts LaunchOpts) error {
 		if opts.Shell {
 			childErr = shell.ExecTmuxShell(opts.TmuxPath, opts.SessionName, launchAbs, opts.EnvVars)
 		} else {
-			childErr = shell.ExecTmuxAgent(opts.TmuxPath, opts.SessionName, launchAbs, opts.EnvVars, opts.Agent)
+			childErr = shell.ExecTmuxAgent(opts.TmuxPath, opts.SessionName, launchAbs,
+				mergeAgentEnv(opts.EnvVars, opts.ResolvedAgent.Env),
+				opts.ResolvedAgent.Command, opts.ResolvedAgent.Args)
 		}
 	case opts.Shell:
 		childErr = shell.ExecShell(launchAbs, opts.EnvVars, opts.Slug, opts.Mode)
@@ -221,7 +270,8 @@ func Run(opts LaunchOpts) error {
 		for _, line := range shell.BannerLines(opts.Mode, opts.Slug, opts.WsDir, opts.LaunchDir) {
 			fmt.Println(line)
 		}
-		childErr = shell.ExecAgent(opts.Agent, launchAbs, opts.EnvVars)
+		childErr = execAgent(opts.ResolvedAgent.Command, opts.ResolvedAgent.Args, launchAbs,
+			mergeAgentEnv(opts.EnvVars, opts.ResolvedAgent.Env))
 	}
 
 	if hb != nil {
@@ -284,12 +334,12 @@ func finalize(opts LaunchOpts, startManifest *Manifest, startTime, endTime time.
 	}
 	diff := DiffManifests(startManifest, endManifest)
 
-	agent := opts.Agent
+	agentCmd := leaseAgentCommand(opts)
 	if opts.Shell {
-		agent = "shell"
+		agentCmd = "shell"
 	}
 	info := &SessionInfo{
-		Agent:     agent,
+		Agent:     agentCmd,
 		Mode:      opts.Mode,
 		StartTime: startTime,
 		EndTime:   endTime,
@@ -307,7 +357,7 @@ func finalize(opts LaunchOpts, startManifest *Manifest, startTime, endTime time.
 	}
 
 	summary := SummarizeFromDiff(
-		sessionID, currentHostname(), agent, opts.Mode,
+		sessionID, currentHostname(), agentCmd, opts.Mode,
 		startTime, endTime, diff, endManifest,
 	)
 	if opts.SessionMode == "persistent" {

internal/session/run_env_test.go

@@ -0,0 +1,72 @@
+package session
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/warrenronsiek/ctask/internal/agent"
+)
+
+func TestMergeAgentEnvOverlays(t *testing.T) {
+	base := map[string]string{"CTASK_WORKSPACE": "/ws", "PATH": "/bin"}
+	agentEnv := map[string]string{"OPENAI_API_KEY": "x", "CTASK_WORKSPACE": "shadowed"}
+	got := mergeAgentEnv(base, agentEnv)
+
+	if got["OPENAI_API_KEY"] != "x" {
+		t.Errorf("OPENAI_API_KEY = %q, want x", got["OPENAI_API_KEY"])
+	}
+	if got["PATH"] != "/bin" {
+		t.Errorf("PATH = %q, want /bin (untouched base)", got["PATH"])
+	}
+	if got["CTASK_WORKSPACE"] != "shadowed" {
+		t.Errorf("CTASK_WORKSPACE = %q, want shadowed (agent.env wins per spec §5)",
+			got["CTASK_WORKSPACE"])
+	}
+}
+
+func TestRunMergesAgentEnvIntoChildEnvironment(t *testing.T) {
+	wsDir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(wsDir, ".ctask"), 0755); err != nil {
+		t.Fatalf("mkdir .ctask: %v", err)
+	}
+
+	var capturedEnv map[string]string
+	prev := execAgent
+	execAgent = func(command string, args []string, dir string, env map[string]string) error {
+		capturedEnv = env
+		return nil
+	}
+	t.Cleanup(func() { execAgent = prev })
+
+	err := Run(LaunchOpts{
+		WsDir: wsDir,
+		EnvVars: map[string]string{
+			"CTASK_WORKSPACE": "/ws-base",
+			"PATH":            "/bin",
+		},
+		Mode: "local",
+		Slug: "env-merge",
+		ResolvedAgent: &agent.Resolved{
+			Command: "go",
+			Args:    nil,
+			Env: map[string]string{
+				"OPENAI_API_KEY":  "x",
+				"CTASK_WORKSPACE": "shadowed-by-agent-env",
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if capturedEnv["OPENAI_API_KEY"] != "x" {
+		t.Errorf("OPENAI_API_KEY = %q, want x", capturedEnv["OPENAI_API_KEY"])
+	}
+	if capturedEnv["PATH"] != "/bin" {
+		t.Errorf("PATH = %q, want /bin", capturedEnv["PATH"])
+	}
+	if capturedEnv["CTASK_WORKSPACE"] != "shadowed-by-agent-env" {
+		t.Errorf("CTASK_WORKSPACE = %q, want shadowed-by-agent-env (spec §5: agent.env wins)",
+			capturedEnv["CTASK_WORKSPACE"])
+	}
+}

internal/session/run_integration_test.go

@@ -6,6 +6,8 @@ import (
 	"path/filepath"
 	"testing"
 	"time"
+
+	"github.com/warrenronsiek/ctask/internal/agent"
 )
 
 func TestFinalizeWritesSummaryAndClearsLease(t *testing.T) {
@@ -31,10 +33,10 @@ func TestFinalizeWritesSummaryAndClearsLease(t *testing.T) {
 
 	end := time.Now().UTC().Truncate(time.Second)
 	opts := LaunchOpts{
-		WsDir: wsDir,
-		Agent: "claude",
-		Mode:  "local",
-		Slug:  "test",
+		WsDir:         wsDir,
+		ResolvedAgent: &agent.Resolved{Command: "claude"},
+		Mode:          "local",
+		Slug:          "test",
 	}
 
 	if err := finalize(opts, startManifest, start, end, true); err != nil {

internal/shell/launch.go

@@ -54,14 +54,29 @@ func ContainerNotice() string {
 	return "[ctask] container mode is not available in v0.1. Use local mode or see docs for manual container setup."
 }
 
-// ExecAgent launches the agent command in the workspace directory.
-func ExecAgent(agent string, wsDir string, envVars map[string]string) error {
+// execAgentArgs is the pure helper: returns the (path, argv) pair that
+// ExecAgent will hand to exec.Command. Extracted so unit tests can
+// assert argv shape without spawning a real child.
+func execAgentArgs(agent string, args []string) (string, []string, error) {
 	path, err := exec.LookPath(agent)
 	if err != nil {
-		return fmt.Errorf("agent command not found: %s", agent)
+		return "", nil, fmt.Errorf("agent command not found: %s", agent)
+	}
+	return path, args, nil
+}
+
+// ExecAgent launches the agent command in the workspace directory.
+// args is appended after the executable; envVars is merged into the
+// process environment via BuildEnvList (which keeps os.Environ() as the
+// base — agent.env entries layered into envVars by the caller take
+// precedence on collision, per v0.6 spec §5).
+func ExecAgent(agent string, args []string, wsDir string, envVars map[string]string) error {
+	path, argv, err := execAgentArgs(agent, args)
+	if err != nil {
+		return err
 	}
 
-	cmd := exec.Command(path)
+	cmd := exec.Command(path, argv...)
 	cmd.Dir = wsDir
 	cmd.Stdin = os.Stdin
 	cmd.Stdout = os.Stdout

internal/shell/launch_test.go

@@ -6,6 +6,28 @@ import (
 	"testing"
 )
 
+func TestExecAgentArgsAppendedAfterPath(t *testing.T) {
+	// Use any executable guaranteed to exist on PATH. "go" works on dev
+	// machines; the test suite already assumes Go is present.
+	path, argv, err := execAgentArgs("go", []string{"version"})
+	if err != nil {
+		t.Skipf("go not on PATH: %v", err)
+	}
+	if !strings.HasSuffix(path, "go") && !strings.HasSuffix(path, "go.exe") {
+		t.Errorf("path = %q, want suffix 'go' or 'go.exe'", path)
+	}
+	if len(argv) != 1 || argv[0] != "version" {
+		t.Errorf("argv = %v, want [version]", argv)
+	}
+}
+
+func TestExecAgentArgsCommandNotFound(t *testing.T) {
+	_, _, err := execAgentArgs("definitely-not-on-path-zzz", nil)
+	if err == nil || !strings.Contains(err.Error(), "not found") {
+		t.Fatalf("err = %v, want command-not-found error", err)
+	}
+}
+
 func TestDefaultShell(t *testing.T) {
 	cmd := DefaultShell()
 	if runtime.GOOS == "windows" {

internal/shell/tmux.go

@@ -183,13 +183,15 @@ func pollSessionEndWith(tmuxPath, name string, interval time.Duration, hs func(s
 }
 
 // ExecTmuxAgent orchestrates the three-call pattern for agent mode:
-// NewSession -> AttachSession -> PollSessionEnd.
+// NewSession -> AttachSession -> PollSessionEnd. args (when non-empty)
+// are appended after the agent command on the tmux session's child
+// invocation.
 //
 // AttachSession failures abort early — the polling loop is meaningful only
 // after a successful attach (otherwise we'd block waiting for a session
 // the user never connected to).
-func ExecTmuxAgent(tmuxPath, sessionName, launchAbs string, env map[string]string, agent string) error {
-	if err := NewSession(tmuxPath, sessionName, launchAbs, env, agent); err != nil {
+func ExecTmuxAgent(tmuxPath, sessionName, launchAbs string, env map[string]string, agent string, args []string) error {
+	if err := NewSession(tmuxPath, sessionName, launchAbs, env, agent, args...); err != nil {
 		return err
 	}
 	if err := AttachSession(tmuxPath, sessionName); err != nil {

internal/shell/tmux_test.go

@@ -11,6 +11,21 @@ import (
 	"time"
 )
 
+func TestTmuxArgsIncludesCommandArgs(t *testing.T) {
+	got := tmuxArgs("session-x", "/tmp/ws", map[string]string{"K": "v"}, "claude", "--debug", "--mode=foo")
+	// Tail of args must be: -- claude --debug --mode=foo
+	if len(got) < 4 {
+		t.Fatalf("argv too short: %v", got)
+	}
+	tail := got[len(got)-4:]
+	want := []string{"--", "claude", "--debug", "--mode=foo"}
+	for i, w := range want {
+		if tail[i] != w {
+			t.Fatalf("tail = %v, want %v", tail, want)
+		}
+	}
+}
+
 func TestParseTmuxVersionMajor(t *testing.T) {
 	cases := []struct {
 		raw       string