From c7d95f3992d24f86ff71e5f3e18260a8ef8a09f0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 24 May 2026 08:47:07 +0000
Subject: feat(executor): introduce AgentChannel seam for runner signals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Defines AgentChannel — the normalized interface by which a runner reports
agent-originated signals (AskUser, ReportSummary, SpawnSubtask,
RecordProgress) — plus a default storeChannel implementation backed by
storage. Runner.Run now takes an AgentChannel; the pool constructs one
per execution.

The file transport routes its post-exit summary detection through
ch.ReportSummary (buffered onto the execution so the pool still applies
its extract/synthesize fallbacks, no double-write). AskUser returns
ErrAgentBlocked since write-and-exit cannot answer in-session; question
persistence stays with the pool's BlockedError handling. SpawnSubtask
and RecordProgress are implemented and tested, ready for the MCP
transport in Phase 2 where the channel becomes fully load-bearing.

Store gains CreateEvent so the channel can emit agent_message events.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/executor/channel.go        | 117 +++++++++++++++++++++++++++++++++++
 internal/executor/channel_test.go   | 118 ++++++++++++++++++++++++++++++++++++
 internal/executor/claude.go         |   6 +-
 internal/executor/claude_test.go    |   8 +--
 internal/executor/container.go      |  12 ++--
 internal/executor/container_test.go |  12 ++--
 internal/executor/executor.go       |  12 ++--
 internal/executor/executor_test.go  |   8 ++-
 internal/executor/gemini.go         |   6 +-
 internal/executor/gemini_test.go    |  14 ++---
 internal/executor/local.go          |   2 +-
 internal/executor/local_test.go     |   6 +-
 12 files changed, 281 insertions(+), 40 deletions(-)
 create mode 100644 internal/executor/channel.go
 create mode 100644 internal/executor/channel_test.go

(limited to 'internal/executor')

diff --git a/internal/executor/channel.go b/internal/executor/channel.go
new file mode 100644
index 0000000..76df94f
--- /dev/null
+++ b/internal/executor/channel.go
@@ -0,0 +1,117 @@
+package executor
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"time"
+
+	"github.com/thepeterstone/claudomator/internal/event"
+	"github.com/thepeterstone/claudomator/internal/storage"
+	"github.com/thepeterstone/claudomator/internal/task"
+	"github.com/google/uuid"
+)
+
+// ErrAgentBlocked is returned by AgentChannel.AskUser when the transport cannot
+// deliver an answer within the current run — e.g. the file transport, which can
+// only write-and-exit. Runners translate it into a *BlockedError so the task
+// blocks and resumes later. Transports that can suspend the agent in-session
+// (MCP, Phase 2) instead block and return the answer.
+var ErrAgentBlocked = errors.New("agent blocked awaiting user input")
+
+// SubtaskSpec describes a child task an agent wants to spawn.
+type SubtaskSpec struct {
+	Name         string
+	Instructions string
+	Model        string
+	MaxBudgetUSD float64
+}
+
+// AgentChannel is how a Runner reports agent-originated signals to the rest of
+// the system. Implementations translate these into stored artifacts and events.
+// The transport by which a Runner detects these signals — post-exit files
+// today, MCP/tool-use in Phase 2 — is the Runner's private concern.
+type AgentChannel interface {
+	// AskUser records that the agent needs human input. Transports that can
+	// suspend the agent in-session return the answer; those that cannot return
+	// ErrAgentBlocked.
+	AskUser(ctx context.Context, questionJSON string) (answer string, err error)
+	// ReportSummary records the agent's final summary text.
+	ReportSummary(ctx context.Context, summary string) error
+	// SpawnSubtask creates a child task and returns its ID.
+	SpawnSubtask(ctx context.Context, spec SubtaskSpec) (taskID string, err error)
+	// RecordProgress records a free-form progress note from the agent.
+	RecordProgress(ctx context.Context, message string) error
+}
+
+// channelStore is the subset of storage the default channel needs.
+type channelStore interface {
+	CreateTask(t *task.Task) error
+	CreateEvent(e *event.Event) error
+}
+
+// storeChannel is the default AgentChannel backed by storage. Summary reports
+// are buffered onto the execution record so the pool persists them once (with
+// its extract/synthesize fallbacks); other signals are written immediately.
+type storeChannel struct {
+	store  channelStore
+	taskID string
+	exec   *storage.Execution
+}
+
+var _ AgentChannel = (*storeChannel)(nil)
+
+func newStoreChannel(store channelStore, taskID string, exec *storage.Execution) *storeChannel {
+	return &storeChannel{store: store, taskID: taskID, exec: exec}
+}
+
+// AskUser on the default (file-transport) channel cannot deliver an answer
+// in-session, so it always reports the run as blocked. Question persistence is
+// owned by the pool's BlockedError handling.
+func (c *storeChannel) AskUser(_ context.Context, _ string) (string, error) {
+	return "", ErrAgentBlocked
+}
+
+// ReportSummary buffers the summary onto the execution record. The pool persists
+// it (preferring this value over its extract/synthesize fallbacks).
+func (c *storeChannel) ReportSummary(_ context.Context, summary string) error {
+	if c.exec != nil {
+		c.exec.Summary = summary
+	}
+	return nil
+}
+
+func (c *storeChannel) SpawnSubtask(_ context.Context, spec SubtaskSpec) (string, error) {
+	now := time.Now().UTC()
+	child := &task.Task{
+		ID:           uuid.NewString(),
+		Name:         spec.Name,
+		ParentTaskID: c.taskID,
+		Agent: task.AgentConfig{
+			Type:         "claude",
+			Model:        spec.Model,
+			Instructions: spec.Instructions,
+			MaxBudgetUSD: spec.MaxBudgetUSD,
+		},
+		Priority:  task.PriorityNormal,
+		State:     task.StatePending,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := c.store.CreateTask(child); err != nil {
+		return "", err
+	}
+	return child.ID, nil
+}
+
+func (c *storeChannel) RecordProgress(_ context.Context, message string) error {
+	payload, _ := json.Marshal(struct {
+		Message string `json:"message"`
+	}{Message: message})
+	return c.store.CreateEvent(&event.Event{
+		TaskID:  c.taskID,
+		Kind:    event.KindAgentMessage,
+		Actor:   event.ActorAgent,
+		Payload: payload,
+	})
+}
\ No newline at end of file
diff --git a/internal/executor/channel_test.go b/internal/executor/channel_test.go
new file mode 100644
index 0000000..822dd35
--- /dev/null
+++ b/internal/executor/channel_test.go
@@ -0,0 +1,118 @@
+package executor
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/thepeterstone/claudomator/internal/event"
+	"github.com/thepeterstone/claudomator/internal/storage"
+	"github.com/thepeterstone/claudomator/internal/task"
+)
+
+type fakeChannelStore struct {
+	createdTasks  []*task.Task
+	createdEvents []*event.Event
+	createTaskErr error
+}
+
+func (f *fakeChannelStore) CreateTask(t *task.Task) error {
+	if f.createTaskErr != nil {
+		return f.createTaskErr
+	}
+	f.createdTasks = append(f.createdTasks, t)
+	return nil
+}
+
+func (f *fakeChannelStore) CreateEvent(e *event.Event) error {
+	f.createdEvents = append(f.createdEvents, e)
+	return nil
+}
+
+func TestStoreChannel_AskUser_ReturnsBlocked(t *testing.T) {
+	ch := newStoreChannel(&fakeChannelStore{}, "task-1", &storage.Execution{})
+	answer, err := ch.AskUser(context.Background(), `{"text":"q"}`)
+	if !errors.Is(err, ErrAgentBlocked) {
+		t.Errorf("expected ErrAgentBlocked, got %v", err)
+	}
+	if answer != "" {
+		t.Errorf("expected empty answer, got %q", answer)
+	}
+}
+
+func TestStoreChannel_ReportSummary_BuffersOntoExec(t *testing.T) {
+	e := &storage.Execution{}
+	ch := newStoreChannel(&fakeChannelStore{}, "task-1", e)
+	if err := ch.ReportSummary(context.Background(), "did the thing"); err != nil {
+		t.Fatalf("ReportSummary: %v", err)
+	}
+	if e.Summary != "did the thing" {
+		t.Errorf("expected exec.Summary set, got %q", e.Summary)
+	}
+}
+
+func TestStoreChannel_ReportSummary_NilExec(t *testing.T) {
+	ch := newStoreChannel(&fakeChannelStore{}, "task-1", nil)
+	if err := ch.ReportSummary(context.Background(), "x"); err != nil {
+		t.Errorf("expected nil err with nil exec, got %v", err)
+	}
+}
+
+func TestStoreChannel_SpawnSubtask_CreatesChildWithParent(t *testing.T) {
+	store := &fakeChannelStore{}
+	ch := newStoreChannel(store, "parent-1", &storage.Execution{})
+	id, err := ch.SpawnSubtask(context.Background(), SubtaskSpec{
+		Name:         "child",
+		Instructions: "do it",
+		Model:        "sonnet",
+		MaxBudgetUSD: 1.5,
+	})
+	if err != nil {
+		t.Fatalf("SpawnSubtask: %v", err)
+	}
+	if id == "" {
+		t.Error("expected non-empty subtask ID")
+	}
+	if len(store.createdTasks) != 1 {
+		t.Fatalf("expected 1 created task, got %d", len(store.createdTasks))
+	}
+	ct := store.createdTasks[0]
+	if ct.ParentTaskID != "parent-1" {
+		t.Errorf("ParentTaskID: got %q want parent-1", ct.ParentTaskID)
+	}
+	if ct.ID != id {
+		t.Errorf("returned id %q != created task id %q", id, ct.ID)
+	}
+	if ct.Agent.Instructions != "do it" || ct.Agent.Model != "sonnet" || ct.Agent.MaxBudgetUSD != 1.5 {
+		t.Errorf("agent config not propagated: %+v", ct.Agent)
+	}
+	if ct.State != task.StatePending {
+		t.Errorf("expected PENDING child, got %s", ct.State)
+	}
+}
+
+func TestStoreChannel_SpawnSubtask_PropagatesError(t *testing.T) {
+	store := &fakeChannelStore{createTaskErr: errors.New("boom")}
+	ch := newStoreChannel(store, "parent-1", &storage.Execution{})
+	if _, err := ch.SpawnSubtask(context.Background(), SubtaskSpec{Name: "x"}); err == nil {
+		t.Error("expected error from CreateTask")
+	}
+}
+
+func TestStoreChannel_RecordProgress_EmitsAgentMessage(t *testing.T) {
+	store := &fakeChannelStore{}
+	ch := newStoreChannel(store, "task-1", &storage.Execution{})
+	if err := ch.RecordProgress(context.Background(), "halfway done"); err != nil {
+		t.Fatalf("RecordProgress: %v", err)
+	}
+	if len(store.createdEvents) != 1 {
+		t.Fatalf("expected 1 event, got %d", len(store.createdEvents))
+	}
+	e := store.createdEvents[0]
+	if e.Kind != event.KindAgentMessage || e.Actor != event.ActorAgent {
+		t.Errorf("got kind=%v actor=%v want agent_message/agent", e.Kind, e.Actor)
+	}
+	if e.TaskID != "task-1" {
+		t.Errorf("TaskID: got %q want task-1", e.TaskID)
+	}
+}
diff --git a/internal/executor/claude.go b/internal/executor/claude.go
index 3c87f26..0123754 100644
--- a/internal/executor/claude.go
+++ b/internal/executor/claude.go
@@ -51,7 +51,7 @@ func (r *ClaudeRunner) binaryPath() string {
 // project into a temp sandbox, runs the agent there, then merges committed
 // changes back to project_dir. On failure the sandbox is preserved and its
 // path is included in the error.
-func (r *ClaudeRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution) error {
+func (r *ClaudeRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, ch AgentChannel) error {
 	projectDir := t.Agent.ProjectDir
 
 	// Validate project_dir exists when set.
@@ -164,7 +164,7 @@ func (r *ClaudeRunner) Run(ctx context.Context, t *task.Task, e *storage.Executi
 		// extract the text as the summary and fall through to normal completion.
 		if isCompletionReport(questionJSON) {
 			r.Logger.Info("treating question file as completion report", "taskID", e.TaskID)
-			e.Summary = extractQuestionText(questionJSON)
+			_ = ch.ReportSummary(ctx, extractQuestionText(questionJSON))
 		} else {
 			// Preserve sandbox on BLOCKED — agent may have partial work and its
 			// Claude session files are stored under the sandbox's project slug.
@@ -177,7 +177,7 @@ func (r *ClaudeRunner) Run(ctx context.Context, t *task.Task, e *storage.Executi
 	summaryFile := filepath.Join(logDir, "summary.txt")
 	if summaryData, readErr := os.ReadFile(summaryFile); readErr == nil {
 		os.Remove(summaryFile) // consumed
-		e.Summary = strings.TrimSpace(string(summaryData))
+		_ = ch.ReportSummary(ctx, strings.TrimSpace(string(summaryData)))
 	}
 
 	// Merge sandbox back to project_dir and clean up.
diff --git a/internal/executor/claude_test.go b/internal/executor/claude_test.go
index c01e160..0e76260 100644
--- a/internal/executor/claude_test.go
+++ b/internal/executor/claude_test.go
@@ -259,7 +259,7 @@ func TestClaudeRunner_Run_ResumeSetsSessionIDFromResumeSession(t *testing.T) {
 	}
 
 	// Run completes successfully (binary is "true").
-	_ = r.Run(context.Background(), tk, exec)
+	_ = r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
 
 	// SessionID must be the original session (ResumeSessionID), not the new
 	// exec's own ID. If it were exec.ID, a second blocked-then-resumed cycle
@@ -284,7 +284,7 @@ func TestClaudeRunner_Run_InaccessibleWorkingDir_ReturnsError(t *testing.T) {
 	}
 	exec := &storage.Execution{ID: "test-exec"}
 
-	err := r.Run(context.Background(), tk, exec)
+	err := r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
 
 	if err == nil {
 		t.Fatal("expected error for inaccessible working_dir, got nil")
@@ -732,7 +732,7 @@ func TestClaudeRunner_Run_ResumeUsesStoredSandboxDir(t *testing.T) {
 		SandboxDir:      sandboxDir,
 	}
 
-	_ = r.Run(context.Background(), tk, exec)
+	_ = r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
 
 	got, err := os.ReadFile(cwdFile)
 	if err != nil {
@@ -778,7 +778,7 @@ func TestClaudeRunner_Run_StaleSandboxDir_ClonesAfresh(t *testing.T) {
 		SandboxDir:      staleSandbox,
 	}
 
-	if err := r.Run(context.Background(), tk, e); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
 		t.Fatalf("Run with stale sandbox: %v", err)
 	}
 
diff --git a/internal/executor/container.go b/internal/executor/container.go
index 61ac29c..4269ef1 100644
--- a/internal/executor/container.go
+++ b/internal/executor/container.go
@@ -100,7 +100,7 @@ func (r *ContainerRunner) ensureStoryBranch(ctx context.Context, remoteURL, bran
 	return nil
 }
 
-func (r *ContainerRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution) error {
+func (r *ContainerRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, ch AgentChannel) error {
 	var err error
 	repoURL := t.RepositoryURL
 	if repoURL == "" {
@@ -227,7 +227,7 @@ func (r *ContainerRunner) Run(ctx context.Context, t *task.Task, e *storage.Exec
 	}
 
 	// Run container (with auth retry on failure).
-	runErr := r.runContainer(ctx, t, e, workspace, agentHome, isResume, storyBranch)
+	runErr := r.runContainer(ctx, t, e, workspace, agentHome, isResume, storyBranch, ch)
 	if runErr != nil && isAuthError(runErr) && r.CredentialSyncCmd != "" {
 		r.Logger.Warn("auth failure detected, syncing credentials and retrying once", "taskID", t.ID)
 		syncOut, syncErr := r.command(ctx, r.CredentialSyncCmd).CombinedOutput()
@@ -241,7 +241,7 @@ func (r *ContainerRunner) Run(ctx context.Context, t *task.Task, e *storage.Exec
 		if srcData, readErr := os.ReadFile(filepath.Join(r.ClaudeConfigDir, ".claude.json")); readErr == nil {
 			_ = os.WriteFile(filepath.Join(agentHome, ".claude.json"), srcData, 0644)
 		}
-		runErr = r.runContainer(ctx, t, e, workspace, agentHome, isResume, storyBranch)
+		runErr = r.runContainer(ctx, t, e, workspace, agentHome, isResume, storyBranch, ch)
 	}
 
 	if runErr == nil {
@@ -257,7 +257,7 @@ func (r *ContainerRunner) Run(ctx context.Context, t *task.Task, e *storage.Exec
 
 // runContainer runs the docker container for the given task and handles log setup,
 // environment files, instructions, and post-execution git operations.
-func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *storage.Execution, workspace, agentHome string, isResume bool, storyBranch string) error {
+func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *storage.Execution, workspace, agentHome string, isResume bool, storyBranch string, ch AgentChannel) error {
 	repoURL := t.RepositoryURL
 
 	image := t.Agent.ContainerImage
@@ -372,7 +372,7 @@ func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *sto
 		questionJSON := strings.TrimSpace(string(data))
 		if isCompletionReport(questionJSON) {
 			r.Logger.Info("treating question file as completion report", "taskID", e.TaskID)
-			e.Summary = extractQuestionText(questionJSON)
+			_ = ch.ReportSummary(ctx, extractQuestionText(questionJSON))
 		} else {
 			if e.SessionID == "" {
 				r.Logger.Warn("missing session ID; resume will start fresh", "taskID", e.TaskID)
@@ -389,7 +389,7 @@ func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *sto
 	summaryFile := filepath.Join(logDir, "summary.txt")
 	if summaryData, readErr := os.ReadFile(summaryFile); readErr == nil {
 		os.Remove(summaryFile) // consumed
-		e.Summary = strings.TrimSpace(string(summaryData))
+		_ = ch.ReportSummary(ctx, strings.TrimSpace(string(summaryData)))
 	}
 
 	// 5. Post-execution: push changes if successful
diff --git a/internal/executor/container_test.go b/internal/executor/container_test.go
index f0b2a3a..5ee3a3c 100644
--- a/internal/executor/container_test.go
+++ b/internal/executor/container_test.go
@@ -139,7 +139,7 @@ func TestContainerRunner_Run_PreservesWorkspaceOnFailure(t *testing.T) {
 	}
 	exec := &storage.Execution{ID: "test-exec", TaskID: "test-task"}
 
-	err := runner.Run(context.Background(), tk, exec)
+	err := runner.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
 	if err == nil {
 		t.Fatal("expected error due to mocked docker failure")
 	}
@@ -378,7 +378,7 @@ func TestContainerRunner_MissingCredentials_FailsFast(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "test-exec", TaskID: "test-missing-creds"}
 
-	err := runner.Run(context.Background(), tk, e)
+	err := runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
 	if err == nil {
 		t.Fatal("expected error due to missing credentials, got nil")
 	}
@@ -418,7 +418,7 @@ func TestContainerRunner_MissingSettings_FailsFast(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "test-exec-2", TaskID: "test-missing-settings"}
 
-	err := runner.Run(context.Background(), tk, e)
+	err := runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
 	if err == nil {
 		t.Fatal("expected error due to missing settings, got nil")
 	}
@@ -504,7 +504,7 @@ func TestContainerRunner_AuthError_SyncsAndRetries(t *testing.T) {
 	e := &storage.Execution{ID: "auth-retry-exec", TaskID: "auth-retry-test"}
 
 	// Run — first attempt will fail with auth error, triggering sync+retry
-	runner.Run(context.Background(), tk, e)
+	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
 	// We don't check error strictly since second run may also fail (git push etc.)
 	// What we care about is that docker was called twice and sync was called
 	if callCount < 2 {
@@ -550,7 +550,7 @@ func TestContainerRunner_ClonesStoryBranch(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "exec-1", TaskID: "story-branch-test"}
 
-	runner.Run(context.Background(), tk, e)
+	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
 	os.RemoveAll(e.SandboxDir)
 
 	// Assert git checkout was called with the story branch name.
@@ -597,7 +597,7 @@ func TestContainerRunner_ClonesDefaultBranchWhenNoBranchName(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "exec-2", TaskID: "no-branch-test"}
 
-	runner.Run(context.Background(), tk, e)
+	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
 	os.RemoveAll(e.SandboxDir)
 
 	for _, a := range cloneArgs {
diff --git a/internal/executor/executor.go b/internal/executor/executor.go
index 09169bd..76e67b8 100644
--- a/internal/executor/executor.go
+++ b/internal/executor/executor.go
@@ -12,6 +12,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/thepeterstone/claudomator/internal/event"
 	"github.com/thepeterstone/claudomator/internal/llm"
 	"github.com/thepeterstone/claudomator/internal/retry"
 	"github.com/thepeterstone/claudomator/internal/storage"
@@ -41,6 +42,7 @@ type Store interface {
 	ListTasksByStory(storyID string) ([]*task.Task, error)
 	UpdateStoryStatus(id string, status task.StoryState) error
 	CreateTask(t *task.Task) error
+	CreateEvent(e *event.Event) error
 	UpdateTaskCheckerReport(id, report string) error
 	GetCheckerTask(checkedTaskID string) (*task.Task, error)
 }
@@ -52,9 +54,11 @@ type LogPather interface {
 	ExecLogDir(execID string) string
 }
 
-// Runner executes a single task and returns the result.
+// Runner executes a single task and returns the result. The AgentChannel is how
+// the runner reports agent-originated signals (summary, questions, subtasks,
+// progress) back to the system.
 type Runner interface {
-	Run(ctx context.Context, t *task.Task, exec *storage.Execution) error
+	Run(ctx context.Context, t *task.Task, exec *storage.Execution, ch AgentChannel) error
 }
 
 // workItem is an entry in the pool's internal work queue.
@@ -352,7 +356,7 @@ func (p *Pool) executeResume(ctx context.Context, t *task.Task, exec *storage.Ex
 		}
 	}
 
-	err = runner.Run(ctx, t, exec)
+	err = runner.Run(ctx, t, exec, newStoreChannel(p.store, t.ID, exec))
 	exec.EndTime = time.Now().UTC()
 
 	p.decActiveAgent(agentType, &cleaned)
@@ -1073,7 +1077,7 @@ func (p *Pool) execute(ctx context.Context, t *task.Task) {
 	}
 
 	// Run the task.
-	err = runner.Run(ctx, t, exec)
+	err = runner.Run(ctx, t, exec, newStoreChannel(p.store, t.ID, exec))
 	exec.EndTime = time.Now().UTC()
 
 	p.decActiveAgent(agentType, &cleaned)
diff --git a/internal/executor/executor_test.go b/internal/executor/executor_test.go
index 9214872..d98efbf 100644
--- a/internal/executor/executor_test.go
+++ b/internal/executor/executor_test.go
@@ -12,6 +12,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/thepeterstone/claudomator/internal/event"
 	"github.com/thepeterstone/claudomator/internal/storage"
 	"github.com/thepeterstone/claudomator/internal/task"
 )
@@ -63,7 +64,7 @@ type mockRunner struct {
 	onRun    func(*task.Task, *storage.Execution) error
 }
 
-func (m *mockRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution) error {
+func (m *mockRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, _ AgentChannel) error {
 	m.mu.Lock()
 	m.calls++
 	cb := m.onRun
@@ -391,11 +392,11 @@ func (m *logPatherMockRunner) ExecLogDir(execID string) string {
 	return filepath.Join(m.logDir, execID)
 }
 
-func (m *logPatherMockRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution) error {
+func (m *logPatherMockRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, ch AgentChannel) error {
 	m.mu.Lock()
 	m.capturedPath = e.StdoutPath
 	m.mu.Unlock()
-	return m.mockRunner.Run(ctx, t, e)
+	return m.mockRunner.Run(ctx, t, e, ch)
 }
 
 // TestPool_Execute_LogPathsPreSetBeforeRun verifies that when the runner
@@ -1194,6 +1195,7 @@ func (m *minimalMockStore) GetStory(_ string) (*task.Story, error)
 func (m *minimalMockStore) ListTasksByStory(_ string) ([]*task.Task, error)     { return nil, nil }
 func (m *minimalMockStore) UpdateStoryStatus(_ string, _ task.StoryState) error { return nil }
 func (m *minimalMockStore) CreateTask(_ *task.Task) error                      { return nil }
+func (m *minimalMockStore) CreateEvent(_ *event.Event) error                   { return nil }
 func (m *minimalMockStore) UpdateTaskCheckerReport(_ string, _ string) error   { return nil }
 func (m *minimalMockStore) GetCheckerTask(_ string) (*task.Task, error)        { return nil, nil }
 
diff --git a/internal/executor/gemini.go b/internal/executor/gemini.go
index 3abec05..d229361 100644
--- a/internal/executor/gemini.go
+++ b/internal/executor/gemini.go
@@ -49,7 +49,7 @@ func (r *GeminiRunner) binaryPath() string {
 // inspect partial work. If the agent writes a question file before exiting,
 // Run returns *BlockedError with SandboxDir populated so a resume execution
 // can pick up in the same directory.
-func (r *GeminiRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution) error {
+func (r *GeminiRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, ch AgentChannel) error {
 	projectDir := t.Agent.ProjectDir
 
 	if projectDir != "" {
@@ -136,7 +136,7 @@ func (r *GeminiRunner) Run(ctx context.Context, t *task.Task, e *storage.Executi
 		questionJSON := strings.TrimSpace(string(data))
 		if isCompletionReport(questionJSON) {
 			r.Logger.Info("treating question file as completion report", "taskID", e.TaskID)
-			e.Summary = extractQuestionText(questionJSON)
+			_ = ch.ReportSummary(ctx, extractQuestionText(questionJSON))
 		} else {
 			// Preserve sandbox on BLOCKED so a resume can pick up in the same dir.
 			return &BlockedError{QuestionJSON: questionJSON, SessionID: e.SessionID, SandboxDir: sandboxDir}
@@ -147,7 +147,7 @@ func (r *GeminiRunner) Run(ctx context.Context, t *task.Task, e *storage.Executi
 	summaryFile := filepath.Join(logDir, "summary.txt")
 	if summaryData, readErr := os.ReadFile(summaryFile); readErr == nil {
 		os.Remove(summaryFile)
-		e.Summary = strings.TrimSpace(string(summaryData))
+		_ = ch.ReportSummary(ctx, strings.TrimSpace(string(summaryData)))
 	}
 
 	// Merge sandbox back to project_dir and clean up.
diff --git a/internal/executor/gemini_test.go b/internal/executor/gemini_test.go
index cd11ebc..c8f7422 100644
--- a/internal/executor/gemini_test.go
+++ b/internal/executor/gemini_test.go
@@ -125,7 +125,7 @@ func TestGeminiRunner_Run_InaccessibleProjectDir_ReturnsError(t *testing.T) {
 	}
 	exec := &storage.Execution{ID: "test-exec"}
 
-	err := r.Run(context.Background(), tk, exec)
+	err := r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
 
 	if err == nil {
 		t.Fatal("expected error for inaccessible project_dir, got nil")
@@ -213,7 +213,7 @@ func TestGeminiRunner_Run_ProjectDir_RunsInSandbox(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "sandbox-exec", TaskID: "task-1"}
 
-	if err := r.Run(context.Background(), tk, e); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
 		t.Fatalf("Run: %v", err)
 	}
 
@@ -261,7 +261,7 @@ fi
 	}
 	e := &storage.Execution{ID: "blocked-gemini-exec", TaskID: "task-1"}
 
-	err := r.Run(context.Background(), tk, e)
+	err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
 
 	var blocked *BlockedError
 	if !errors.As(err, &blocked) {
@@ -301,7 +301,7 @@ func TestGeminiRunner_Run_ExecError_PreservesSandbox(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "err-gemini-exec", TaskID: "task-1"}
 
-	err := r.Run(context.Background(), tk, e)
+	err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
 	if err == nil {
 		t.Fatal("expected error from failing gemini exit")
 	}
@@ -352,7 +352,7 @@ func TestGeminiRunner_Run_ResumeUsesStoredSandboxDir(t *testing.T) {
 		SandboxDir:      sandboxDir,
 	}
 
-	if err := r.Run(context.Background(), tk, e); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
 		t.Fatalf("Run with preserved sandbox: %v", err)
 	}
 
@@ -400,7 +400,7 @@ func TestGeminiRunner_Run_StaleSandboxDir_ClonesAfresh(t *testing.T) {
 		SandboxDir:      staleSandbox,
 	}
 
-	if err := r.Run(context.Background(), tk, e); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
 		t.Fatalf("Run with stale sandbox: %v", err)
 	}
 
@@ -438,7 +438,7 @@ func TestGeminiRunner_Run_NoProjectDir_SkipsSandbox(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "no-pd-gemini", TaskID: "task-nopd"}
 
-	if err := r.Run(context.Background(), tk, e); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
 		t.Fatalf("Run without project_dir: %v", err)
 	}
 	if e.SandboxDir != "" {
diff --git a/internal/executor/local.go b/internal/executor/local.go
index 5d874c6..e3c9c2c 100644
--- a/internal/executor/local.go
+++ b/internal/executor/local.go
@@ -40,7 +40,7 @@ func (r *LocalRunner) ExecLogDir(execID string) string {
 // Run streams a chat completion to stdout.log. The response is wrapped in
 // stream-json envelopes line-by-line so downstream parsers (summary,
 // changestats) read it the same way they read Claude output.
-func (r *LocalRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution) error {
+func (r *LocalRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, _ AgentChannel) error {
 	if r.Client == nil {
 		return fmt.Errorf("local runner: no LLM client configured")
 	}
diff --git a/internal/executor/local_test.go b/internal/executor/local_test.go
index d8ab678..8aa8791 100644
--- a/internal/executor/local_test.go
+++ b/internal/executor/local_test.go
@@ -72,7 +72,7 @@ func TestLocalRunner_Run_WritesStreamJSON(t *testing.T) {
 	}
 	exec := &storage.Execution{ID: uuid.New().String(), TaskID: tt.ID}
 
-	if err := r.Run(context.Background(), tt, exec); err != nil {
+	if err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID, exec)); err != nil {
 		t.Fatalf("Run: %v", err)
 	}
 
@@ -121,7 +121,7 @@ func TestLocalRunner_Run_NoClient_Errors(t *testing.T) {
 	r := &LocalRunner{LogDir: t.TempDir()}
 	tt := &task.Task{ID: "x", Agent: task.AgentConfig{Instructions: "hi"}}
 	exec := &storage.Execution{ID: "exec-x"}
-	err := r.Run(context.Background(), tt, exec)
+	err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID, exec))
 	if err == nil || !strings.Contains(err.Error(), "no LLM client") {
 		t.Errorf("expected 'no LLM client' error, got %v", err)
 	}
@@ -134,7 +134,7 @@ func TestLocalRunner_Run_EmptyInstructions_Errors(t *testing.T) {
 	}
 	tt := &task.Task{ID: "x", Agent: task.AgentConfig{}}
 	exec := &storage.Execution{ID: "exec-x"}
-	err := r.Run(context.Background(), tt, exec)
+	err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID, exec))
 	if err == nil || !strings.Contains(err.Error(), "empty instructions") {
 		t.Errorf("expected empty-instructions error, got %v", err)
 	}
-- 
cgit v1.2.3


From 54f6631c28a8b85f6f874e17822549faba916a38 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 24 May 2026 09:38:06 +0000
Subject: feat(executor): per-task agent MCP server + token registry (Phase 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the agent-facing MCP transport foundation: a Registry that mints a
per-task bearer token bound to a freshly built MCP server exposing the four
agent tools (ask_user, report_summary, spawn_subtask, record_progress), and
an HTTP handler (StreamableHTTP) that resolves the token to that server. The
server never trusts an agent-supplied task ID — context comes from the token.

The default storeChannel now buffers summary and question signals under a
mutex (an MCP tool call lands on an HTTP-handler goroutine mid-run), exposing
ReportedSummary/PendingQuestion. The pool flushes the buffered summary onto
the execution after the run, replacing the runner's direct exec.Summary write
and keeping the read race-free.

ask_user follows the record-and-resume model: it buffers the question, returns
ErrAgentBlocked, and the tool tells the agent to end its turn; the run blocks
and resumes later via claude --resume (no live slot held).

Tests cover registry lifecycle, in-memory tool dispatch, and HTTP end-to-end
with bearer auth (valid token dispatches; invalid token rejected).

Not yet wired into the runners or mounted on the API server — next increment.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 go.mod                              |  14 ++-
 go.sum                              |  47 +++++++-
 internal/executor/agentmcp.go       | 160 ++++++++++++++++++++++++++
 internal/executor/agentmcp_test.go  | 218 ++++++++++++++++++++++++++++++++++++
 internal/executor/channel.go        |  59 +++++++---
 internal/executor/channel_test.go   |  42 ++++---
 internal/executor/claude_test.go    |   8 +-
 internal/executor/container_test.go |  12 +-
 internal/executor/executor.go       |  12 +-
 internal/executor/gemini_test.go    |  14 +--
 internal/executor/local_test.go     |   6 +-
 11 files changed, 531 insertions(+), 61 deletions(-)
 create mode 100644 internal/executor/agentmcp.go
 create mode 100644 internal/executor/agentmcp_test.go

(limited to 'internal/executor')

diff --git a/go.mod b/go.mod
index 54d5b32..fb2828c 100644
--- a/go.mod
+++ b/go.mod
@@ -3,27 +3,33 @@ module github.com/thepeterstone/claudomator
 go 1.25.3
 
 require (
+	github.com/BurntSushi/toml v1.6.0
+	github.com/SherClockHolmes/webpush-go v1.4.0
 	github.com/google/uuid v1.6.0
 	github.com/mattn/go-sqlite3 v1.14.33
+	github.com/modelcontextprotocol/go-sdk v1.6.1
 	github.com/spf13/cobra v1.10.2
 	golang.org/x/net v0.49.0
 	gopkg.in/yaml.v3 v3.0.1
+	modernc.org/sqlite v1.47.0
 )
 
 require (
-	github.com/BurntSushi/toml v1.6.0 // indirect
-	github.com/SherClockHolmes/webpush-go v1.4.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/golang-jwt/jwt/v5 v5.2.1 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
+	github.com/google/jsonschema-go v0.4.3 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	golang.org/x/crypto v0.47.0 // indirect
+	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
 	modernc.org/libc v1.70.0 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
-	modernc.org/sqlite v1.47.0 // indirect
 )
diff --git a/go.sum b/go.sum
index a202d97..e4d2f97 100644
--- a/go.sum
+++ b/go.sum
@@ -5,26 +5,43 @@ github.com/SherClockHolmes/webpush-go v1.4.0/go.mod h1:XSq8pKX11vNV8MJEMwjrlTkxh
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
-github.com/golang-jwt/jwt/v5 v5.2.1 h1:OuVbFODueb089Lh128TAcimifWaLhJwVflnrgM17wHk=
 github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
+github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-sqlite3 v1.14.33 h1:A5blZ5ulQo2AtayQ9/limgHEkFreKj1Dv226a1K73s0=
 github.com/mattn/go-sqlite3 v1.14.33/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/modelcontextprotocol/go-sdk v1.6.1 h1:0zOSupjKUxPKSocPT1Wtago+mUHU2/uZ4xSOY0FGReU=
+github.com/modelcontextprotocol/go-sdk v1.6.1/go.mod h1:kzm3kzFL1/+AziGOE0nUs3gvPoNxMCvkxokMkuFapXQ=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -40,6 +57,8 @@ golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
 golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
+golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
+golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
@@ -50,6 +69,8 @@ golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
 golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
 golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
+golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
+golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -57,6 +78,8 @@ golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
 golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
@@ -95,16 +118,38 @@ golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
 golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
 golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
+golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
+golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
+modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
+modernc.org/ccgo/v4 v4.32.0 h1:hjG66bI/kqIPX1b2yT6fr/jt+QedtP2fqojG2VrFuVw=
+modernc.org/ccgo/v4 v4.32.0/go.mod h1:6F08EBCx5uQc38kMGl+0Nm0oWczoo1c7cgpzEry7Uc0=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.2 h1:ZtDCnhonXSZexk/AYsegNRV1lJGgaNZJuKjJSWKyEqo=
+modernc.org/gc/v3 v3.1.2/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
 modernc.org/libc v1.70.0 h1:U58NawXqXbgpZ/dcdS9kMshu08aiA6b7gusEusqzNkw=
 modernc.org/libc v1.70.0/go.mod h1:OVmxFGP1CI/Z4L3E0Q3Mf1PDE0BucwMkcXjjLntvHJo=
 modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
 modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
 modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
 modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
+modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
 modernc.org/sqlite v1.47.0 h1:R1XyaNpoW4Et9yly+I2EeX7pBza/w+pmYee/0HJDyKk=
 modernc.org/sqlite v1.47.0/go.mod h1:hWjRO6Tj/5Ik8ieqxQybiEOUXy0NJFNp2tpvVpKlvig=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
diff --git a/internal/executor/agentmcp.go b/internal/executor/agentmcp.go
new file mode 100644
index 0000000..4368031
--- /dev/null
+++ b/internal/executor/agentmcp.go
@@ -0,0 +1,160 @@
+package executor
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"sync"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// Registry maps per-task MCP bearer tokens to a built agent MCP server. A token
+// is minted when a runner spawns an agent subprocess and revoked when it exits,
+// so the server resolves task context from the token alone and never trusts an
+// agent-supplied task ID.
+type Registry struct {
+	mu      sync.RWMutex
+	servers map[string]*mcp.Server
+}
+
+func NewRegistry() *Registry {
+	return &Registry{servers: make(map[string]*mcp.Server)}
+}
+
+// Mint creates a token bound to a freshly built MCP server for ch.
+func (r *Registry) Mint(ch AgentChannel) (string, error) {
+	buf := make([]byte, 32)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	token := hex.EncodeToString(buf)
+	r.mu.Lock()
+	r.servers[token] = newAgentServer(ch)
+	r.mu.Unlock()
+	return token, nil
+}
+
+func (r *Registry) server(token string) (*mcp.Server, bool) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	s, ok := r.servers[token]
+	return s, ok
+}
+
+func (r *Registry) Revoke(token string) {
+	r.mu.Lock()
+	delete(r.servers, token)
+	r.mu.Unlock()
+}
+
+type askUserInput struct {
+	Question string   `json:"question" jsonschema:"the question to ask the user; phrase it as a real question ending with a question mark"`
+	Options  []string `json:"options,omitempty" jsonschema:"optional list of suggested answer choices"`
+}
+
+type reportSummaryInput struct {
+	Summary string `json:"summary" jsonschema:"a 2-5 sentence summary of what you did and the outcome"`
+}
+
+type spawnSubtaskInput struct {
+	Name         string  `json:"name" jsonschema:"short descriptive name for the subtask"`
+	Instructions string  `json:"instructions" jsonschema:"complete instructions for the subtask agent"`
+	Model        string  `json:"model,omitempty" jsonschema:"optional model override, e.g. sonnet or opus"`
+	MaxBudgetUSD float64 `json:"max_budget_usd,omitempty" jsonschema:"optional budget cap in USD"`
+}
+
+type recordProgressInput struct {
+	Message string `json:"message" jsonschema:"a short progress note describing what you are doing"`
+}
+
+func textResult(text string) *mcp.CallToolResult {
+	return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: text}}}
+}
+
+// newAgentServer builds an MCP server exposing the four agent tools bound to ch.
+func newAgentServer(ch AgentChannel) *mcp.Server {
+	s := mcp.NewServer(&mcp.Implementation{Name: "claudomator", Version: "1"}, nil)
+
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "ask_user",
+		Description: "Ask the user a question when you genuinely need a decision to proceed. Your turn ends after calling this; the task is resumed with the user's answer. Prefer making a reasonable decision and noting it in report_summary over asking.",
+	}, func(ctx context.Context, _ *mcp.CallToolRequest, in askUserInput) (*mcp.CallToolResult, any, error) {
+		q := map[string]any{"text": in.Question}
+		if len(in.Options) > 0 {
+			q["options"] = in.Options
+		}
+		payload, _ := json.Marshal(q)
+		ans, err := ch.AskUser(ctx, string(payload))
+		if errors.Is(err, ErrAgentBlocked) {
+			return textResult("Question recorded. End your turn now without calling any more tools; the task will be resumed once the user answers."), nil, nil
+		}
+		if err != nil {
+			return nil, nil, err
+		}
+		return textResult(ans), nil, nil
+	})
+
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "report_summary",
+		Description: "Record a concise summary of what you accomplished. Call this before finishing.",
+	}, func(ctx context.Context, _ *mcp.CallToolRequest, in reportSummaryInput) (*mcp.CallToolResult, any, error) {
+		if err := ch.ReportSummary(ctx, in.Summary); err != nil {
+			return nil, nil, err
+		}
+		return textResult("Summary recorded."), nil, nil
+	})
+
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "spawn_subtask",
+		Description: "Create a child task to be executed separately. Use this to break large work into focused pieces, then finish your turn.",
+	}, func(ctx context.Context, _ *mcp.CallToolRequest, in spawnSubtaskInput) (*mcp.CallToolResult, any, error) {
+		id, err := ch.SpawnSubtask(ctx, SubtaskSpec{
+			Name:         in.Name,
+			Instructions: in.Instructions,
+			Model:        in.Model,
+			MaxBudgetUSD: in.MaxBudgetUSD,
+		})
+		if err != nil {
+			return nil, nil, err
+		}
+		return textResult("Created subtask " + id), nil, nil
+	})
+
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "record_progress",
+		Description: "Record a short progress note that appears in the task timeline.",
+	}, func(ctx context.Context, _ *mcp.CallToolRequest, in recordProgressInput) (*mcp.CallToolResult, any, error) {
+		if err := ch.RecordProgress(ctx, in.Message); err != nil {
+			return nil, nil, err
+		}
+		return textResult("Noted."), nil, nil
+	})
+
+	return s
+}
+
+func bearerToken(r *http.Request) string {
+	h := r.Header.Get("Authorization")
+	if h == "" {
+		return ""
+	}
+	return strings.TrimSpace(strings.TrimPrefix(h, "Bearer "))
+}
+
+// NewAgentMCPHandler returns the HTTP handler for the per-task agent MCP server.
+// It resolves the request's bearer token to the server for that task's run;
+// unknown tokens yield a 400 from the underlying handler.
+func NewAgentMCPHandler(reg *Registry) http.Handler {
+	return mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
+		s, ok := reg.server(bearerToken(r))
+		if !ok {
+			return nil
+		}
+		return s
+	}, nil)
+}
diff --git a/internal/executor/agentmcp_test.go b/internal/executor/agentmcp_test.go
new file mode 100644
index 0000000..3973af0
--- /dev/null
+++ b/internal/executor/agentmcp_test.go
@@ -0,0 +1,218 @@
+package executor
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// recordingChannel is a fake AgentChannel that records tool invocations.
+type recordingChannel struct {
+	asked    string
+	summary  string
+	spawned  []SubtaskSpec
+	progress []string
+	spawnID  string
+}
+
+func (c *recordingChannel) AskUser(_ context.Context, q string) (string, error) {
+	c.asked = q
+	return "", ErrAgentBlocked
+}
+func (c *recordingChannel) ReportSummary(_ context.Context, s string) error {
+	c.summary = s
+	return nil
+}
+func (c *recordingChannel) SpawnSubtask(_ context.Context, spec SubtaskSpec) (string, error) {
+	c.spawned = append(c.spawned, spec)
+	return c.spawnID, nil
+}
+func (c *recordingChannel) RecordProgress(_ context.Context, m string) error {
+	c.progress = append(c.progress, m)
+	return nil
+}
+
+func resultText(t *testing.T, res *mcp.CallToolResult) string {
+	t.Helper()
+	if len(res.Content) == 0 {
+		t.Fatal("expected content in tool result")
+	}
+	tc, ok := res.Content[0].(*mcp.TextContent)
+	if !ok {
+		t.Fatalf("expected TextContent, got %T", res.Content[0])
+	}
+	return tc.Text
+}
+
+func TestRegistry_MintLookupRevoke(t *testing.T) {
+	reg := NewRegistry()
+	tok, err := reg.Mint(&recordingChannel{})
+	if err != nil {
+		t.Fatalf("Mint: %v", err)
+	}
+	if tok == "" {
+		t.Fatal("expected non-empty token")
+	}
+	if _, ok := reg.server(tok); !ok {
+		t.Error("expected server for minted token")
+	}
+	if _, ok := reg.server("nonsense"); ok {
+		t.Error("expected no server for unknown token")
+	}
+	reg.Revoke(tok)
+	if _, ok := reg.server(tok); ok {
+		t.Error("expected no server after revoke")
+	}
+}
+
+func TestRegistry_MintUniqueTokens(t *testing.T) {
+	reg := NewRegistry()
+	a, _ := reg.Mint(&recordingChannel{})
+	b, _ := reg.Mint(&recordingChannel{})
+	if a == b {
+		t.Error("expected unique tokens per mint")
+	}
+}
+
+// connectInMemory wires a client to a server over the SDK's in-memory transport.
+func connectInMemory(t *testing.T, srv *mcp.Server) *mcp.ClientSession {
+	t.Helper()
+	ctx := context.Background()
+	clientT, serverT := mcp.NewInMemoryTransports()
+	if _, err := srv.Connect(ctx, serverT, nil); err != nil {
+		t.Fatalf("server connect: %v", err)
+	}
+	client := mcp.NewClient(&mcp.Implementation{Name: "test", Version: "1"}, nil)
+	cs, err := client.Connect(ctx, clientT, nil)
+	if err != nil {
+		t.Fatalf("client connect: %v", err)
+	}
+	t.Cleanup(func() { _ = cs.Close() })
+	return cs
+}
+
+func TestAgentServer_AskUser_RecordsAndInstructsStop(t *testing.T) {
+	ch := &recordingChannel{}
+	cs := connectInMemory(t, newAgentServer(ch))
+	res, err := cs.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      "ask_user",
+		Arguments: map[string]any{"question": "Proceed?", "options": []string{"yes", "no"}},
+	})
+	if err != nil {
+		t.Fatalf("CallTool: %v", err)
+	}
+	if !strings.Contains(ch.asked, `"text":"Proceed?"`) || !strings.Contains(ch.asked, "yes") {
+		t.Errorf("channel did not receive question+options: %q", ch.asked)
+	}
+	if txt := resultText(t, res); !strings.Contains(strings.ToLower(txt), "recorded") {
+		t.Errorf("expected stop instruction, got %q", txt)
+	}
+}
+
+func TestAgentServer_ReportSummary(t *testing.T) {
+	ch := &recordingChannel{}
+	cs := connectInMemory(t, newAgentServer(ch))
+	if _, err := cs.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      "report_summary",
+		Arguments: map[string]any{"summary": "did the work"},
+	}); err != nil {
+		t.Fatalf("CallTool: %v", err)
+	}
+	if ch.summary != "did the work" {
+		t.Errorf("summary not recorded, got %q", ch.summary)
+	}
+}
+
+func TestAgentServer_SpawnSubtask(t *testing.T) {
+	ch := &recordingChannel{spawnID: "sub-1"}
+	cs := connectInMemory(t, newAgentServer(ch))
+	res, err := cs.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      "spawn_subtask",
+		Arguments: map[string]any{"name": "child", "instructions": "do it", "model": "sonnet"},
+	})
+	if err != nil {
+		t.Fatalf("CallTool: %v", err)
+	}
+	if len(ch.spawned) != 1 || ch.spawned[0].Name != "child" || ch.spawned[0].Instructions != "do it" || ch.spawned[0].Model != "sonnet" {
+		t.Errorf("subtask spec not propagated: %+v", ch.spawned)
+	}
+	if txt := resultText(t, res); !strings.Contains(txt, "sub-1") {
+		t.Errorf("expected returned subtask ID in result, got %q", txt)
+	}
+}
+
+func TestAgentServer_RecordProgress(t *testing.T) {
+	ch := &recordingChannel{}
+	cs := connectInMemory(t, newAgentServer(ch))
+	if _, err := cs.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      "record_progress",
+		Arguments: map[string]any{"message": "halfway"},
+	}); err != nil {
+		t.Fatalf("CallTool: %v", err)
+	}
+	if len(ch.progress) != 1 || ch.progress[0] != "halfway" {
+		t.Errorf("progress not recorded: %+v", ch.progress)
+	}
+}
+
+type bearerRT struct {
+	token string
+	base  http.RoundTripper
+}
+
+func (b bearerRT) RoundTrip(r *http.Request) (*http.Response, error) {
+	r = r.Clone(r.Context())
+	if b.token != "" {
+		r.Header.Set("Authorization", "Bearer "+b.token)
+	}
+	return b.base.RoundTrip(r)
+}
+
+func TestAgentMCPHandler_HTTP_AuthAndDispatch(t *testing.T) {
+	ch := &recordingChannel{}
+	reg := NewRegistry()
+	tok, _ := reg.Mint(ch)
+
+	httpSrv := httptest.NewServer(NewAgentMCPHandler(reg))
+	defer httpSrv.Close()
+
+	ctx := context.Background()
+	client := mcp.NewClient(&mcp.Implementation{Name: "test", Version: "1"}, nil)
+	cs, err := client.Connect(ctx, &mcp.StreamableClientTransport{
+		Endpoint:   httpSrv.URL,
+		HTTPClient: &http.Client{Transport: bearerRT{token: tok, base: http.DefaultTransport}},
+	}, nil)
+	if err != nil {
+		t.Fatalf("client connect with valid token: %v", err)
+	}
+	defer cs.Close()
+
+	if _, err := cs.CallTool(ctx, &mcp.CallToolParams{
+		Name:      "record_progress",
+		Arguments: map[string]any{"message": "over http"},
+	}); err != nil {
+		t.Fatalf("CallTool over HTTP: %v", err)
+	}
+	if len(ch.progress) != 1 || ch.progress[0] != "over http" {
+		t.Errorf("HTTP dispatch did not reach channel: %+v", ch.progress)
+	}
+}
+
+func TestAgentMCPHandler_HTTP_BadTokenRejected(t *testing.T) {
+	reg := NewRegistry()
+	httpSrv := httptest.NewServer(NewAgentMCPHandler(reg))
+	defer httpSrv.Close()
+
+	client := mcp.NewClient(&mcp.Implementation{Name: "test", Version: "1"}, nil)
+	_, err := client.Connect(context.Background(), &mcp.StreamableClientTransport{
+		Endpoint:   httpSrv.URL,
+		HTTPClient: &http.Client{Transport: bearerRT{token: "invalid", base: http.DefaultTransport}},
+	}, nil)
+	if err == nil {
+		t.Fatal("expected connect to fail with invalid token")
+	}
+}
diff --git a/internal/executor/channel.go b/internal/executor/channel.go
index 76df94f..541694b 100644
--- a/internal/executor/channel.go
+++ b/internal/executor/channel.go
@@ -4,10 +4,10 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"sync"
 	"time"
 
 	"github.com/thepeterstone/claudomator/internal/event"
-	"github.com/thepeterstone/claudomator/internal/storage"
 	"github.com/thepeterstone/claudomator/internal/task"
 	"github.com/google/uuid"
 )
@@ -50,37 +50,64 @@ type channelStore interface {
 	CreateEvent(e *event.Event) error
 }
 
-// storeChannel is the default AgentChannel backed by storage. Summary reports
-// are buffered onto the execution record so the pool persists them once (with
-// its extract/synthesize fallbacks); other signals are written immediately.
+// storeChannel is the default AgentChannel backed by storage. Summary and
+// question signals are buffered here under a mutex (they may arrive on an MCP
+// handler goroutine mid-run); the pool flushes the summary to the execution and
+// the runner reads the pending question to build a BlockedError after the
+// subprocess exits. SpawnSubtask/RecordProgress write immediately.
 type storeChannel struct {
 	store  channelStore
 	taskID string
-	exec   *storage.Execution
+
+	mu         sync.Mutex
+	summary    string
+	summarySet bool
+	question   string
+	blocked    bool
 }
 
 var _ AgentChannel = (*storeChannel)(nil)
 
-func newStoreChannel(store channelStore, taskID string, exec *storage.Execution) *storeChannel {
-	return &storeChannel{store: store, taskID: taskID, exec: exec}
+func newStoreChannel(store channelStore, taskID string) *storeChannel {
+	return &storeChannel{store: store, taskID: taskID}
 }
 
-// AskUser on the default (file-transport) channel cannot deliver an answer
-// in-session, so it always reports the run as blocked. Question persistence is
-// owned by the pool's BlockedError handling.
-func (c *storeChannel) AskUser(_ context.Context, _ string) (string, error) {
+// AskUser buffers the question and flags the run as blocked. The default
+// transport cannot deliver an answer in-session, so it returns ErrAgentBlocked;
+// the runner converts the buffered question into a BlockedError after exit, and
+// question persistence is owned by the pool's BlockedError handling.
+func (c *storeChannel) AskUser(_ context.Context, questionJSON string) (string, error) {
+	c.mu.Lock()
+	c.question = questionJSON
+	c.blocked = true
+	c.mu.Unlock()
 	return "", ErrAgentBlocked
 }
 
-// ReportSummary buffers the summary onto the execution record. The pool persists
-// it (preferring this value over its extract/synthesize fallbacks).
+// ReportSummary buffers the summary; the pool flushes it onto the execution
+// after the run (preferring it over its extract/synthesize fallbacks).
 func (c *storeChannel) ReportSummary(_ context.Context, summary string) error {
-	if c.exec != nil {
-		c.exec.Summary = summary
-	}
+	c.mu.Lock()
+	c.summary = summary
+	c.summarySet = true
+	c.mu.Unlock()
 	return nil
 }
 
+// ReportedSummary returns the buffered summary if report_summary was called.
+func (c *storeChannel) ReportedSummary() (string, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.summary, c.summarySet
+}
+
+// PendingQuestion returns the buffered ask_user question if the run is blocked.
+func (c *storeChannel) PendingQuestion() (string, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.question, c.blocked
+}
+
 func (c *storeChannel) SpawnSubtask(_ context.Context, spec SubtaskSpec) (string, error) {
 	now := time.Now().UTC()
 	child := &task.Task{
diff --git a/internal/executor/channel_test.go b/internal/executor/channel_test.go
index 822dd35..250e8eb 100644
--- a/internal/executor/channel_test.go
+++ b/internal/executor/channel_test.go
@@ -6,7 +6,6 @@ import (
 	"testing"
 
 	"github.com/thepeterstone/claudomator/internal/event"
-	"github.com/thepeterstone/claudomator/internal/storage"
 	"github.com/thepeterstone/claudomator/internal/task"
 )
 
@@ -29,8 +28,8 @@ func (f *fakeChannelStore) CreateEvent(e *event.Event) error {
 	return nil
 }
 
-func TestStoreChannel_AskUser_ReturnsBlocked(t *testing.T) {
-	ch := newStoreChannel(&fakeChannelStore{}, "task-1", &storage.Execution{})
+func TestStoreChannel_AskUser_BuffersAndBlocks(t *testing.T) {
+	ch := newStoreChannel(&fakeChannelStore{}, "task-1")
 	answer, err := ch.AskUser(context.Background(), `{"text":"q"}`)
 	if !errors.Is(err, ErrAgentBlocked) {
 		t.Errorf("expected ErrAgentBlocked, got %v", err)
@@ -38,29 +37,36 @@ func TestStoreChannel_AskUser_ReturnsBlocked(t *testing.T) {
 	if answer != "" {
 		t.Errorf("expected empty answer, got %q", answer)
 	}
+	q, blocked := ch.PendingQuestion()
+	if !blocked || q != `{"text":"q"}` {
+		t.Errorf("expected buffered question, got q=%q blocked=%v", q, blocked)
+	}
 }
 
-func TestStoreChannel_ReportSummary_BuffersOntoExec(t *testing.T) {
-	e := &storage.Execution{}
-	ch := newStoreChannel(&fakeChannelStore{}, "task-1", e)
-	if err := ch.ReportSummary(context.Background(), "did the thing"); err != nil {
-		t.Fatalf("ReportSummary: %v", err)
-	}
-	if e.Summary != "did the thing" {
-		t.Errorf("expected exec.Summary set, got %q", e.Summary)
+func TestStoreChannel_PendingQuestion_DefaultNotBlocked(t *testing.T) {
+	ch := newStoreChannel(&fakeChannelStore{}, "task-1")
+	if q, blocked := ch.PendingQuestion(); blocked || q != "" {
+		t.Errorf("expected no pending question, got q=%q blocked=%v", q, blocked)
 	}
 }
 
-func TestStoreChannel_ReportSummary_NilExec(t *testing.T) {
-	ch := newStoreChannel(&fakeChannelStore{}, "task-1", nil)
-	if err := ch.ReportSummary(context.Background(), "x"); err != nil {
-		t.Errorf("expected nil err with nil exec, got %v", err)
+func TestStoreChannel_ReportSummary_Buffers(t *testing.T) {
+	ch := newStoreChannel(&fakeChannelStore{}, "task-1")
+	if _, ok := ch.ReportedSummary(); ok {
+		t.Error("expected no summary before report")
+	}
+	if err := ch.ReportSummary(context.Background(), "did the thing"); err != nil {
+		t.Fatalf("ReportSummary: %v", err)
+	}
+	sum, ok := ch.ReportedSummary()
+	if !ok || sum != "did the thing" {
+		t.Errorf("expected buffered summary, got %q ok=%v", sum, ok)
 	}
 }
 
 func TestStoreChannel_SpawnSubtask_CreatesChildWithParent(t *testing.T) {
 	store := &fakeChannelStore{}
-	ch := newStoreChannel(store, "parent-1", &storage.Execution{})
+	ch := newStoreChannel(store, "parent-1")
 	id, err := ch.SpawnSubtask(context.Background(), SubtaskSpec{
 		Name:         "child",
 		Instructions: "do it",
@@ -93,7 +99,7 @@ func TestStoreChannel_SpawnSubtask_CreatesChildWithParent(t *testing.T) {
 
 func TestStoreChannel_SpawnSubtask_PropagatesError(t *testing.T) {
 	store := &fakeChannelStore{createTaskErr: errors.New("boom")}
-	ch := newStoreChannel(store, "parent-1", &storage.Execution{})
+	ch := newStoreChannel(store, "parent-1")
 	if _, err := ch.SpawnSubtask(context.Background(), SubtaskSpec{Name: "x"}); err == nil {
 		t.Error("expected error from CreateTask")
 	}
@@ -101,7 +107,7 @@ func TestStoreChannel_SpawnSubtask_PropagatesError(t *testing.T) {
 
 func TestStoreChannel_RecordProgress_EmitsAgentMessage(t *testing.T) {
 	store := &fakeChannelStore{}
-	ch := newStoreChannel(store, "task-1", &storage.Execution{})
+	ch := newStoreChannel(store, "task-1")
 	if err := ch.RecordProgress(context.Background(), "halfway done"); err != nil {
 		t.Fatalf("RecordProgress: %v", err)
 	}
diff --git a/internal/executor/claude_test.go b/internal/executor/claude_test.go
index 0e76260..414f6cf 100644
--- a/internal/executor/claude_test.go
+++ b/internal/executor/claude_test.go
@@ -259,7 +259,7 @@ func TestClaudeRunner_Run_ResumeSetsSessionIDFromResumeSession(t *testing.T) {
 	}
 
 	// Run completes successfully (binary is "true").
-	_ = r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
+	_ = r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
 
 	// SessionID must be the original session (ResumeSessionID), not the new
 	// exec's own ID. If it were exec.ID, a second blocked-then-resumed cycle
@@ -284,7 +284,7 @@ func TestClaudeRunner_Run_InaccessibleWorkingDir_ReturnsError(t *testing.T) {
 	}
 	exec := &storage.Execution{ID: "test-exec"}
 
-	err := r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
+	err := r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
 
 	if err == nil {
 		t.Fatal("expected error for inaccessible working_dir, got nil")
@@ -732,7 +732,7 @@ func TestClaudeRunner_Run_ResumeUsesStoredSandboxDir(t *testing.T) {
 		SandboxDir:      sandboxDir,
 	}
 
-	_ = r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
+	_ = r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
 
 	got, err := os.ReadFile(cwdFile)
 	if err != nil {
@@ -778,7 +778,7 @@ func TestClaudeRunner_Run_StaleSandboxDir_ClonesAfresh(t *testing.T) {
 		SandboxDir:      staleSandbox,
 	}
 
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
 		t.Fatalf("Run with stale sandbox: %v", err)
 	}
 
diff --git a/internal/executor/container_test.go b/internal/executor/container_test.go
index 5ee3a3c..9cd80dc 100644
--- a/internal/executor/container_test.go
+++ b/internal/executor/container_test.go
@@ -139,7 +139,7 @@ func TestContainerRunner_Run_PreservesWorkspaceOnFailure(t *testing.T) {
 	}
 	exec := &storage.Execution{ID: "test-exec", TaskID: "test-task"}
 
-	err := runner.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
+	err := runner.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
 	if err == nil {
 		t.Fatal("expected error due to mocked docker failure")
 	}
@@ -378,7 +378,7 @@ func TestContainerRunner_MissingCredentials_FailsFast(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "test-exec", TaskID: "test-missing-creds"}
 
-	err := runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
+	err := runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
 	if err == nil {
 		t.Fatal("expected error due to missing credentials, got nil")
 	}
@@ -418,7 +418,7 @@ func TestContainerRunner_MissingSettings_FailsFast(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "test-exec-2", TaskID: "test-missing-settings"}
 
-	err := runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
+	err := runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
 	if err == nil {
 		t.Fatal("expected error due to missing settings, got nil")
 	}
@@ -504,7 +504,7 @@ func TestContainerRunner_AuthError_SyncsAndRetries(t *testing.T) {
 	e := &storage.Execution{ID: "auth-retry-exec", TaskID: "auth-retry-test"}
 
 	// Run — first attempt will fail with auth error, triggering sync+retry
-	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
+	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
 	// We don't check error strictly since second run may also fail (git push etc.)
 	// What we care about is that docker was called twice and sync was called
 	if callCount < 2 {
@@ -550,7 +550,7 @@ func TestContainerRunner_ClonesStoryBranch(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "exec-1", TaskID: "story-branch-test"}
 
-	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
+	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
 	os.RemoveAll(e.SandboxDir)
 
 	// Assert git checkout was called with the story branch name.
@@ -597,7 +597,7 @@ func TestContainerRunner_ClonesDefaultBranchWhenNoBranchName(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "exec-2", TaskID: "no-branch-test"}
 
-	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
+	runner.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
 	os.RemoveAll(e.SandboxDir)
 
 	for _, a := range cloneArgs {
diff --git a/internal/executor/executor.go b/internal/executor/executor.go
index 76e67b8..6d6c528 100644
--- a/internal/executor/executor.go
+++ b/internal/executor/executor.go
@@ -356,8 +356,12 @@ func (p *Pool) executeResume(ctx context.Context, t *task.Task, exec *storage.Ex
 		}
 	}
 
-	err = runner.Run(ctx, t, exec, newStoreChannel(p.store, t.ID, exec))
+	sc := newStoreChannel(p.store, t.ID)
+	err = runner.Run(ctx, t, exec, sc)
 	exec.EndTime = time.Now().UTC()
+	if sum, ok := sc.ReportedSummary(); ok {
+		exec.Summary = sum
+	}
 
 	p.decActiveAgent(agentType, &cleaned)
 	p.handleRunResult(ctx, t, exec, err, agentType)
@@ -1077,8 +1081,12 @@ func (p *Pool) execute(ctx context.Context, t *task.Task) {
 	}
 
 	// Run the task.
-	err = runner.Run(ctx, t, exec, newStoreChannel(p.store, t.ID, exec))
+	sc := newStoreChannel(p.store, t.ID)
+	err = runner.Run(ctx, t, exec, sc)
 	exec.EndTime = time.Now().UTC()
+	if sum, ok := sc.ReportedSummary(); ok {
+		exec.Summary = sum
+	}
 
 	p.decActiveAgent(agentType, &cleaned)
 	p.handleRunResult(ctx, t, exec, err, agentType)
diff --git a/internal/executor/gemini_test.go b/internal/executor/gemini_test.go
index c8f7422..a906f2c 100644
--- a/internal/executor/gemini_test.go
+++ b/internal/executor/gemini_test.go
@@ -125,7 +125,7 @@ func TestGeminiRunner_Run_InaccessibleProjectDir_ReturnsError(t *testing.T) {
 	}
 	exec := &storage.Execution{ID: "test-exec"}
 
-	err := r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID, exec))
+	err := r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
 
 	if err == nil {
 		t.Fatal("expected error for inaccessible project_dir, got nil")
@@ -213,7 +213,7 @@ func TestGeminiRunner_Run_ProjectDir_RunsInSandbox(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "sandbox-exec", TaskID: "task-1"}
 
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
 		t.Fatalf("Run: %v", err)
 	}
 
@@ -261,7 +261,7 @@ fi
 	}
 	e := &storage.Execution{ID: "blocked-gemini-exec", TaskID: "task-1"}
 
-	err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
+	err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
 
 	var blocked *BlockedError
 	if !errors.As(err, &blocked) {
@@ -301,7 +301,7 @@ func TestGeminiRunner_Run_ExecError_PreservesSandbox(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "err-gemini-exec", TaskID: "task-1"}
 
-	err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e))
+	err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
 	if err == nil {
 		t.Fatal("expected error from failing gemini exit")
 	}
@@ -352,7 +352,7 @@ func TestGeminiRunner_Run_ResumeUsesStoredSandboxDir(t *testing.T) {
 		SandboxDir:      sandboxDir,
 	}
 
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
 		t.Fatalf("Run with preserved sandbox: %v", err)
 	}
 
@@ -400,7 +400,7 @@ func TestGeminiRunner_Run_StaleSandboxDir_ClonesAfresh(t *testing.T) {
 		SandboxDir:      staleSandbox,
 	}
 
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
 		t.Fatalf("Run with stale sandbox: %v", err)
 	}
 
@@ -438,7 +438,7 @@ func TestGeminiRunner_Run_NoProjectDir_SkipsSandbox(t *testing.T) {
 	}
 	e := &storage.Execution{ID: "no-pd-gemini", TaskID: "task-nopd"}
 
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID, e)); err != nil {
+	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
 		t.Fatalf("Run without project_dir: %v", err)
 	}
 	if e.SandboxDir != "" {
diff --git a/internal/executor/local_test.go b/internal/executor/local_test.go
index 8aa8791..ffe87f9 100644
--- a/internal/executor/local_test.go
+++ b/internal/executor/local_test.go
@@ -72,7 +72,7 @@ func TestLocalRunner_Run_WritesStreamJSON(t *testing.T) {
 	}
 	exec := &storage.Execution{ID: uuid.New().String(), TaskID: tt.ID}
 
-	if err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID, exec)); err != nil {
+	if err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID)); err != nil {
 		t.Fatalf("Run: %v", err)
 	}
 
@@ -121,7 +121,7 @@ func TestLocalRunner_Run_NoClient_Errors(t *testing.T) {
 	r := &LocalRunner{LogDir: t.TempDir()}
 	tt := &task.Task{ID: "x", Agent: task.AgentConfig{Instructions: "hi"}}
 	exec := &storage.Execution{ID: "exec-x"}
-	err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID, exec))
+	err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID))
 	if err == nil || !strings.Contains(err.Error(), "no LLM client") {
 		t.Errorf("expected 'no LLM client' error, got %v", err)
 	}
@@ -134,7 +134,7 @@ func TestLocalRunner_Run_EmptyInstructions_Errors(t *testing.T) {
 	}
 	tt := &task.Task{ID: "x", Agent: task.AgentConfig{}}
 	exec := &storage.Execution{ID: "exec-x"}
-	err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID, exec))
+	err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID))
 	if err == nil || !strings.Contains(err.Error(), "empty instructions") {
 		t.Errorf("expected empty-instructions error, got %v", err)
 	}
-- 
cgit v1.2.3


From 952b7623ee9dceec15099043086622aa2aab4741 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 24 May 2026 09:45:16 +0000
Subject: feat(executor,api): wire agent MCP into ContainerRunner + mount /mcp
 (Phase 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ContainerRunner now mints a per-task MCP token (from an injected Registry),
writes a claude mcp-config into the workspace pointing at the host agent MCP
server over host.docker.internal with that bearer, and adds --mcp-config to the
in-container claude invocation. The token is revoked when the run ends. After
the run, a buffered ask_user (PendingQuestion on the channel) is converted into
a BlockedError — the MCP path to BLOCKED — with the file-based question.json
kept as a fallback for in-flight tasks started on the old wire.

The API server mounts the StreamableHTTP MCP handler at POST/GET/DELETE /mcp
when a registry is provided; serve.go constructs one Registry shared by the
runners (mint) and the server (resolve). Minting is skipped for gemini agents.

Tests: writeMCPConfig output shape, buildInnerCmd flag presence/absence, and an
api-level end-to-end MCP tool call through NewServer/Handler proving the route
is mounted (and absent without a registry).

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/api/agentmcp_endpoint_test.go | 104 +++++++++++++++++++++++++++++++++
 internal/api/server.go                 |  13 ++++-
 internal/api/server_test.go            |   4 +-
 internal/cli/serve.go                  |   8 ++-
 internal/executor/channel.go           |  15 +++++
 internal/executor/container.go         |  63 +++++++++++++++++++-
 internal/executor/container_test.go    |  58 ++++++++++++++++--
 7 files changed, 253 insertions(+), 12 deletions(-)
 create mode 100644 internal/api/agentmcp_endpoint_test.go

(limited to 'internal/executor')

diff --git a/internal/api/agentmcp_endpoint_test.go b/internal/api/agentmcp_endpoint_test.go
new file mode 100644
index 0000000..b2f77d3
--- /dev/null
+++ b/internal/api/agentmcp_endpoint_test.go
@@ -0,0 +1,104 @@
+package api
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/thepeterstone/claudomator/internal/executor"
+	"github.com/thepeterstone/claudomator/internal/storage"
+)
+
+type fakeAgentChannel struct{ progress []string }
+
+func (f *fakeAgentChannel) AskUser(context.Context, string) (string, error) {
+	return "", executor.ErrAgentBlocked
+}
+func (f *fakeAgentChannel) ReportSummary(context.Context, string) error { return nil }
+func (f *fakeAgentChannel) SpawnSubtask(context.Context, executor.SubtaskSpec) (string, error) {
+	return "sub", nil
+}
+func (f *fakeAgentChannel) RecordProgress(_ context.Context, m string) error {
+	f.progress = append(f.progress, m)
+	return nil
+}
+
+type tokenRT struct {
+	token string
+	base  http.RoundTripper
+}
+
+func (b tokenRT) RoundTrip(r *http.Request) (*http.Response, error) {
+	r = r.Clone(r.Context())
+	r.Header.Set("Authorization", "Bearer "+b.token)
+	return b.base.RoundTrip(r)
+}
+
+func TestServer_MountsAgentMCPEndpoint(t *testing.T) {
+	store, err := storage.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer store.Close()
+	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError}))
+	pool := executor.NewPool(1, map[string]executor.Runner{}, store, logger)
+
+	reg := executor.NewRegistry()
+	fc := &fakeAgentChannel{}
+	token, _ := reg.Mint(fc)
+
+	srv := NewServer(store, pool, reg, logger, "claude", "gemini")
+	ts := httptest.NewServer(srv.Handler())
+	defer ts.Close()
+
+	client := mcp.NewClient(&mcp.Implementation{Name: "test", Version: "1"}, nil)
+	cs, err := client.Connect(context.Background(), &mcp.StreamableClientTransport{
+		Endpoint:   ts.URL + "/mcp",
+		HTTPClient: &http.Client{Transport: tokenRT{token: token, base: http.DefaultTransport}},
+	}, nil)
+	if err != nil {
+		t.Fatalf("connect to mounted /mcp: %v", err)
+	}
+	defer cs.Close()
+
+	if _, err := cs.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      "record_progress",
+		Arguments: map[string]any{"message": "via api server"},
+	}); err != nil {
+		t.Fatalf("CallTool through api server: %v", err)
+	}
+	if len(fc.progress) != 1 || fc.progress[0] != "via api server" {
+		t.Errorf("tool call did not reach channel: %+v", fc.progress)
+	}
+}
+
+func TestServer_NoRegistry_NoMCPRoute(t *testing.T) {
+	store, err := storage.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer store.Close()
+	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError}))
+	pool := executor.NewPool(1, map[string]executor.Runner{}, store, logger)
+
+	// nil registry → /mcp must not be mounted.
+	srv := NewServer(store, pool, nil, logger, "claude", "gemini")
+	ts := httptest.NewServer(srv.Handler())
+	defer ts.Close()
+
+	resp, err := http.Post(ts.URL+"/mcp", "application/json", http.NoBody)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	// Unmounted: the catch-all "GET /" route rejects POST with 405. A mounted
+	// MCP handler would instead respond (e.g. 400 for the missing token).
+	if resp.StatusCode == http.StatusBadRequest {
+		t.Errorf("expected /mcp to be absent without a registry, got 400 (handler ran)")
+	}
+}
diff --git a/internal/api/server.go b/internal/api/server.go
index ff3a111..1522b72 100644
--- a/internal/api/server.go
+++ b/internal/api/server.go
@@ -39,6 +39,7 @@ type Server struct {
 	taskLogStore     taskLogStore   // injectable for tests; defaults to store
 	questionStore    questionStore  // injectable for tests; defaults to store
 	pool             *executor.Pool
+	registry         *executor.Registry // per-task agent MCP token registry; mounts /mcp when set
 	hub              *Hub
 	logger           *slog.Logger
 	mux              *http.ServeMux
@@ -100,7 +101,7 @@ func (s *Server) SetLLM(c *llm.Client) {
 }
 
 
-func NewServer(store *storage.DB, pool *executor.Pool, logger *slog.Logger, claudeBinPath, geminiBinPath string) *Server {
+func NewServer(store *storage.DB, pool *executor.Pool, registry *executor.Registry, logger *slog.Logger, claudeBinPath, geminiBinPath string) *Server {
 	wd, _ := os.Getwd()
 	s := &Server{
 		ctx:           context.Background(),
@@ -109,6 +110,7 @@ func NewServer(store *storage.DB, pool *executor.Pool, logger *slog.Logger, clau
 		taskLogStore:  store,
 		questionStore: store,
 		pool:          pool,
+		registry:      registry,
 		hub:           NewHub(),
 		logger:        logger,
 		mux:           http.NewServeMux(),
@@ -180,6 +182,15 @@ func (s *Server) routes() {
 	s.mux.HandleFunc("GET /api/drops", s.handleListDrops)
 	s.mux.HandleFunc("GET /api/drops/{filename}", s.handleGetDrop)
 	s.mux.HandleFunc("POST /api/drops", s.handlePostDrop)
+	if s.registry != nil {
+		mcpHandler := executor.NewAgentMCPHandler(s.registry)
+		// The streamable HTTP transport uses POST (messages), GET (SSE stream),
+		// and DELETE (session end). Register them explicitly so the patterns are
+		// more specific than the "GET /" catch-all and don't conflict.
+		s.mux.Handle("POST /mcp", mcpHandler)
+		s.mux.Handle("GET /mcp", mcpHandler)
+		s.mux.Handle("DELETE /mcp", mcpHandler)
+	}
 	s.mux.Handle("GET /", http.FileServerFS(webui.Files))
 }
 
diff --git a/internal/api/server_test.go b/internal/api/server_test.go
index f902495..dd6eed5 100644
--- a/internal/api/server_test.go
+++ b/internal/api/server_test.go
@@ -98,7 +98,7 @@ func testServerWithRunner(t *testing.T, runner executor.Runner) (*Server, *stora
 		"gemini": runner,
 	}
 	pool := executor.NewPool(2, runners, store, logger)
-	srv := NewServer(store, pool, logger, "claude", "gemini")
+	srv := NewServer(store, pool, nil, logger, "claude", "gemini")
 	return srv, store
 }
 
@@ -194,7 +194,7 @@ func testServerWithGeminiMockRunner(t *testing.T) (*Server, *storage.DB) {
 		"gemini": mr,
 	}
 	pool := executor.NewPool(2, runners, store, logger)
-	srv := NewServer(store, pool, logger, "claude", "gemini")
+	srv := NewServer(store, pool, nil, logger, "claude", "gemini")
 	return srv, store
 }
 
diff --git a/internal/cli/serve.go b/internal/cli/serve.go
index 459c35b..b23304b 100644
--- a/internal/cli/serve.go
+++ b/internal/cli/serve.go
@@ -79,6 +79,9 @@ func serve(addr string) error {
 	claudeConfigDir := cfg.ClaudeConfigDir
 
 	repoDir, _ := os.Getwd()
+	// Shared per-task agent MCP token registry: runners mint tokens; the API
+	// server mounts /mcp and resolves them.
+	agentRegistry := executor.NewRegistry()
 	runners := map[string]executor.Runner{
 		// ContainerRunner: binaries are resolved via PATH inside the container image,
 		// so ClaudeBinary/GeminiBinary are left empty (host paths would not exist inside).
@@ -92,6 +95,7 @@ func serve(addr string) error {
 			ClaudeConfigDir:   claudeConfigDir,
 			CredentialSyncCmd: filepath.Join(repoDir, "scripts", "sync-credentials"),
 			Store:             store,
+			Registry:          agentRegistry,
 		},
 		"gemini": &executor.ContainerRunner{
 			Image:             cfg.GeminiImage,
@@ -103,6 +107,7 @@ func serve(addr string) error {
 			ClaudeConfigDir:   claudeConfigDir,
 			CredentialSyncCmd: filepath.Join(repoDir, "scripts", "sync-credentials"),
 			Store:             store,
+			Registry:          agentRegistry,
 		},
 		"container": &executor.ContainerRunner{
 			Image:             "claudomator-agent:latest",
@@ -114,6 +119,7 @@ func serve(addr string) error {
 			ClaudeConfigDir:   claudeConfigDir,
 			CredentialSyncCmd: filepath.Join(repoDir, "scripts", "sync-credentials"),
 			Store:             store,
+			Registry:          agentRegistry,
 		},
 	}
 
@@ -146,7 +152,7 @@ func serve(addr string) error {
 	pool.RecoverStaleQueued(context.Background())
 	pool.RecoverStaleBlocked()
 
-	srv := api.NewServer(store, pool, logger, cfg.ClaudeBinaryPath, cfg.GeminiBinaryPath)
+	srv := api.NewServer(store, pool, agentRegistry, logger, cfg.ClaudeBinaryPath, cfg.GeminiBinaryPath)
 
 	// Configure notifiers: combine webhook (if set) with web push.
 	notifiers := []notify.Notifier{}
diff --git a/internal/executor/channel.go b/internal/executor/channel.go
index 541694b..8605ffa 100644
--- a/internal/executor/channel.go
+++ b/internal/executor/channel.go
@@ -50,6 +50,21 @@ type channelStore interface {
 	CreateEvent(e *event.Event) error
 }
 
+// pendingAsker is implemented by channels that buffer an ask_user call so the
+// runner can convert it into a BlockedError after the agent subprocess exits.
+type pendingAsker interface {
+	PendingQuestion() (questionJSON string, blocked bool)
+}
+
+// channelPendingQuestion reports whether the agent asked a question via the
+// channel during the run (the MCP transport's ask_user path).
+func channelPendingQuestion(ch AgentChannel) (string, bool) {
+	if pa, ok := ch.(pendingAsker); ok {
+		return pa.PendingQuestion()
+	}
+	return "", false
+}
+
 // storeChannel is the default AgentChannel backed by storage. Summary and
 // question signals are buffered here under a mutex (they may arrive on an MCP
 // handler goroutine mid-run); the pool flushes the summary to the execution and
diff --git a/internal/executor/container.go b/internal/executor/container.go
index 4269ef1..f0f728c 100644
--- a/internal/executor/container.go
+++ b/internal/executor/container.go
@@ -2,6 +2,7 @@ package executor
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -29,6 +30,9 @@ type ContainerRunner struct {
 	ClaudeConfigDir    string // host path to ~/.claude; mounted into container for auth credentials
 	CredentialSyncCmd  string // optional path to sync-credentials script for auth-error auto-recovery
 	Store              Store  // optional; used to look up stories and projects for story-aware cloning
+	// Registry mints the per-task MCP token; when set, the agent gets an
+	// mcp-config pointing at the host agent MCP server.
+	Registry *Registry
 	// Command allows mocking exec.CommandContext for tests.
 	Command func(ctx context.Context, name string, arg ...string) *exec.Cmd
 }
@@ -307,8 +311,24 @@ func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *sto
 		return fmt.Errorf("writing instructions: %w", err)
 	}
 
+	// Per-task MCP back-channel: mint a scoped token bound to this run's channel
+	// and write an mcp-config pointing the agent at the host agent MCP server.
+	mcpEnabled := false
+	if r.Registry != nil && t.Agent.Type != "gemini" {
+		token, mintErr := r.Registry.Mint(ch)
+		if mintErr != nil {
+			return fmt.Errorf("minting agent mcp token: %w", mintErr)
+		}
+		defer r.Registry.Revoke(token)
+		mcpURL := strings.TrimRight(strings.ReplaceAll(r.APIURL, "localhost", "host.docker.internal"), "/") + "/mcp"
+		if err := writeMCPConfig(workspace, mcpURL, token); err != nil {
+			return fmt.Errorf("writing mcp config: %w", err)
+		}
+		mcpEnabled = true
+	}
+
 	args := r.buildDockerArgs(workspace, agentHome, e.TaskID)
-	innerCmd := r.buildInnerCmd(t, e, isResume)
+	innerCmd := r.buildInnerCmd(t, e, isResume, mcpEnabled)
 
 	fullArgs := append(args, image)
 	fullArgs = append(fullArgs, innerCmd...)
@@ -365,7 +385,17 @@ func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *sto
 		e.SessionID = sessionID
 	}
 
-	// Check whether the agent left a question before exiting.
+	// MCP transport: if the agent called ask_user, the question is buffered on
+	// the channel. Block so the task resumes with the user's answer.
+	if q, blocked := channelPendingQuestion(ch); blocked {
+		if e.SessionID == "" {
+			r.Logger.Warn("missing session ID; resume will start fresh", "taskID", e.TaskID)
+		}
+		return &BlockedError{QuestionJSON: q, SessionID: e.SessionID, SandboxDir: workspace}
+	}
+
+	// Check whether the agent left a question before exiting (file fallback for
+	// in-flight tasks started on the pre-MCP wire).
 	questionFile := filepath.Join(logDir, "question.json")
 	if data, readErr := os.ReadFile(questionFile); readErr == nil {
 		os.Remove(questionFile) // consumed
@@ -467,7 +497,30 @@ func (r *ContainerRunner) buildDockerArgs(workspace, claudeHome, taskID string)
 	return args
 }
 
-func (r *ContainerRunner) buildInnerCmd(t *task.Task, e *storage.Execution, isResume bool) []string {
+// mcpConfigContainerPath is where the agent mcp-config is mounted in-container
+// (the workspace is bind-mounted at /workspace).
+const mcpConfigContainerPath = "/workspace/.claudomator-mcp.json"
+
+// writeMCPConfig writes a claude CLI mcp-config that registers the per-task
+// agent MCP server over HTTP with a bearer token.
+func writeMCPConfig(workspace, mcpURL, token string) error {
+	cfg := map[string]any{
+		"mcpServers": map[string]any{
+			"claudomator": map[string]any{
+				"type":    "http",
+				"url":     mcpURL,
+				"headers": map[string]string{"Authorization": "Bearer " + token},
+			},
+		},
+	}
+	data, err := json.Marshal(cfg)
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(filepath.Join(workspace, ".claudomator-mcp.json"), data, 0600)
+}
+
+func (r *ContainerRunner) buildInnerCmd(t *task.Task, e *storage.Execution, isResume, mcpEnabled bool) []string {
 	// Claude CLI uses -p for prompt text. To pass a file, we use a shell to cat it.
 	// We use a shell variable to capture the expansion to avoid quoting issues with instructions contents.
 	// The outer single quotes around the sh -c argument prevent host-side expansion.
@@ -491,6 +544,9 @@ func (r *ContainerRunner) buildInnerCmd(t *task.Task, e *storage.Execution, isRe
 	if isResume && e.ResumeSessionID != "" {
 		claudeCmd.WriteString(fmt.Sprintf(" --resume %s", e.ResumeSessionID))
 	}
+	if mcpEnabled {
+		claudeCmd.WriteString(" --mcp-config " + mcpConfigContainerPath)
+	}
 	claudeCmd.WriteString(" --output-format stream-json --verbose --permission-mode bypassPermissions")
 
 	return []string{"sh", "-c", claudeCmd.String()}
@@ -501,6 +557,7 @@ func (r *ContainerRunner) buildInnerCmd(t *task.Task, e *storage.Execution, isRe
 var scaffoldPrefixes = []string{
 	".claudomator-env",
 	".claudomator-instructions.txt",
+	".claudomator-mcp.json",
 	".agent-home",
 }
 
diff --git a/internal/executor/container_test.go b/internal/executor/container_test.go
index 9cd80dc..86e95e2 100644
--- a/internal/executor/container_test.go
+++ b/internal/executor/container_test.go
@@ -2,6 +2,7 @@ package executor
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"log/slog"
@@ -53,13 +54,44 @@ func TestContainerRunner_BuildDockerArgs(t *testing.T) {
 	}
 }
 
+func TestWriteMCPConfig(t *testing.T) {
+	dir := t.TempDir()
+	if err := writeMCPConfig(dir, "http://host.docker.internal:8484/mcp", "tok-abc"); err != nil {
+		t.Fatalf("writeMCPConfig: %v", err)
+	}
+	data, err := os.ReadFile(filepath.Join(dir, ".claudomator-mcp.json"))
+	if err != nil {
+		t.Fatalf("read config: %v", err)
+	}
+	var parsed struct {
+		MCPServers map[string]struct {
+			Type    string            `json:"type"`
+			URL     string            `json:"url"`
+			Headers map[string]string `json:"headers"`
+		} `json:"mcpServers"`
+	}
+	if err := json.Unmarshal(data, &parsed); err != nil {
+		t.Fatalf("config is not valid JSON: %v", err)
+	}
+	srv, ok := parsed.MCPServers["claudomator"]
+	if !ok {
+		t.Fatal("expected claudomator server entry")
+	}
+	if srv.Type != "http" || srv.URL != "http://host.docker.internal:8484/mcp" {
+		t.Errorf("unexpected server config: %+v", srv)
+	}
+	if srv.Headers["Authorization"] != "Bearer tok-abc" {
+		t.Errorf("expected bearer header, got %q", srv.Headers["Authorization"])
+	}
+}
+
 func TestContainerRunner_BuildInnerCmd(t *testing.T) {
 	runner := &ContainerRunner{}
 	
 	t.Run("claude-fresh", func(t *testing.T) {
 		tk := &task.Task{Agent: task.AgentConfig{Type: "claude"}}
 		exec := &storage.Execution{}
-		cmd := runner.buildInnerCmd(tk, exec, false)
+		cmd := runner.buildInnerCmd(tk, exec, false, false)
 		
 		cmdStr := strings.Join(cmd, " ")
 		if strings.Contains(cmdStr, "--resume") {
@@ -73,7 +105,7 @@ func TestContainerRunner_BuildInnerCmd(t *testing.T) {
 	t.Run("claude-resume", func(t *testing.T) {
 		tk := &task.Task{Agent: task.AgentConfig{Type: "claude"}}
 		exec := &storage.Execution{ResumeSessionID: "orig-session-123"}
-		cmd := runner.buildInnerCmd(tk, exec, true)
+		cmd := runner.buildInnerCmd(tk, exec, true, false)
 		
 		cmdStr := strings.Join(cmd, " ")
 		if !strings.Contains(cmdStr, "--resume orig-session-123") {
@@ -81,10 +113,26 @@ func TestContainerRunner_BuildInnerCmd(t *testing.T) {
 		}
 	})
 
+	t.Run("claude-mcp-enabled", func(t *testing.T) {
+		tk := &task.Task{Agent: task.AgentConfig{Type: "claude"}}
+		cmdStr := strings.Join(runner.buildInnerCmd(tk, &storage.Execution{}, false, true), " ")
+		if !strings.Contains(cmdStr, "--mcp-config "+mcpConfigContainerPath) {
+			t.Errorf("expected --mcp-config flag when MCP enabled, got %q", cmdStr)
+		}
+	})
+
+	t.Run("claude-mcp-disabled", func(t *testing.T) {
+		tk := &task.Task{Agent: task.AgentConfig{Type: "claude"}}
+		cmdStr := strings.Join(runner.buildInnerCmd(tk, &storage.Execution{}, false, false), " ")
+		if strings.Contains(cmdStr, "--mcp-config") {
+			t.Errorf("did not expect --mcp-config flag when MCP disabled, got %q", cmdStr)
+		}
+	})
+
 	t.Run("gemini", func(t *testing.T) {
 		tk := &task.Task{Agent: task.AgentConfig{Type: "gemini"}}
 		exec := &storage.Execution{}
-		cmd := runner.buildInnerCmd(tk, exec, false)
+		cmd := runner.buildInnerCmd(tk, exec, false, false)
 
 		cmdStr := strings.Join(cmd, " ")
 		if !strings.Contains(cmdStr, "gemini -p \"$INST\"") {
@@ -99,13 +147,13 @@ func TestContainerRunner_BuildInnerCmd(t *testing.T) {
 		}
 		
 		tkClaude := &task.Task{Agent: task.AgentConfig{Type: "claude"}}
-		cmdClaude := runnerCustom.buildInnerCmd(tkClaude, &storage.Execution{}, false)
+		cmdClaude := runnerCustom.buildInnerCmd(tkClaude, &storage.Execution{}, false, false)
 		if !strings.Contains(strings.Join(cmdClaude, " "), "/usr/bin/claude-v2 -p") {
 			t.Errorf("expected custom claude binary, got %q", cmdClaude)
 		}
 
 		tkGemini := &task.Task{Agent: task.AgentConfig{Type: "gemini"}}
-		cmdGemini := runnerCustom.buildInnerCmd(tkGemini, &storage.Execution{}, false)
+		cmdGemini := runnerCustom.buildInnerCmd(tkGemini, &storage.Execution{}, false, false)
 		if !strings.Contains(strings.Join(cmdGemini, " "), "/usr/local/bin/gemini-pro -p") {
 			t.Errorf("expected custom gemini binary, got %q", cmdGemini)
 		}
-- 
cgit v1.2.3


From 473d80224880dd718cb2612fd49b987cd6097b2c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 24 May 2026 17:38:53 +0000
Subject: feat(executor): MCP-oriented planning preamble, applied by
 ContainerRunner (Phase 2)

Rewrites the planning preamble to point the agent at the four MCP tools
(ask_user/report_summary/spawn_subtask/record_progress) instead of the
CLAUDOMATOR_QUESTION_FILE / CLAUDOMATOR_SUMMARY_FILE conventions: ask_user ends
the turn, report_summary replaces the summary file, spawn_subtask replaces the
POST-to-/api/tasks planning step. Git discipline is retained.

ContainerRunner previously applied no preamble at all; it now prepends this
preamble (via buildAgentInstructions) when the MCP back-channel is active and
skip_planning is false, so the in-container agent is actually guided to use the
tools. Gemini agents (no MCP) are unaffected.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/executor/container.go      | 26 ++++++++++----
 internal/executor/container_test.go | 22 ++++++++++++
 internal/executor/preamble.go       | 67 +++++++++++++++----------------------
 internal/executor/preamble_test.go  | 30 +++++++++++------
 4 files changed, 89 insertions(+), 56 deletions(-)

(limited to 'internal/executor')

diff --git a/internal/executor/container.go b/internal/executor/container.go
index f0f728c..78c3ed7 100644
--- a/internal/executor/container.go
+++ b/internal/executor/container.go
@@ -305,12 +305,6 @@ func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *sto
 		return fmt.Errorf("writing env file: %w", err)
 	}
 
-	// Inject custom instructions via file to avoid CLI length limits
-	instructionsFile := filepath.Join(workspace, ".claudomator-instructions.txt")
-	if err := os.WriteFile(instructionsFile, []byte(t.Agent.Instructions), 0644); err != nil {
-		return fmt.Errorf("writing instructions: %w", err)
-	}
-
 	// Per-task MCP back-channel: mint a scoped token bound to this run's channel
 	// and write an mcp-config pointing the agent at the host agent MCP server.
 	mcpEnabled := false
@@ -327,6 +321,15 @@ func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *sto
 		mcpEnabled = true
 	}
 
+	// Inject custom instructions via file to avoid CLI length limits. When the
+	// MCP back-channel is active, prepend the planning preamble that points the
+	// agent at the ask_user/report_summary/spawn_subtask/record_progress tools.
+	instructions := buildAgentInstructions(t, mcpEnabled)
+	instructionsFile := filepath.Join(workspace, ".claudomator-instructions.txt")
+	if err := os.WriteFile(instructionsFile, []byte(instructions), 0644); err != nil {
+		return fmt.Errorf("writing instructions: %w", err)
+	}
+
 	args := r.buildDockerArgs(workspace, agentHome, e.TaskID)
 	innerCmd := r.buildInnerCmd(t, e, isResume, mcpEnabled)
 
@@ -501,6 +504,17 @@ func (r *ContainerRunner) buildDockerArgs(workspace, claudeHome, taskID string)
 // (the workspace is bind-mounted at /workspace).
 const mcpConfigContainerPath = "/workspace/.claudomator-mcp.json"
 
+// buildAgentInstructions returns the agent's instructions, prepending the
+// MCP-tool planning preamble when the back-channel is active and planning is
+// not skipped.
+func buildAgentInstructions(t *task.Task, mcpEnabled bool) string {
+	instructions := t.Agent.Instructions
+	if mcpEnabled && !t.Agent.SkipPlanning {
+		instructions = withPlanningPreamble(instructions)
+	}
+	return instructions
+}
+
 // writeMCPConfig writes a claude CLI mcp-config that registers the per-task
 // agent MCP server over HTTP with a bearer token.
 func writeMCPConfig(workspace, mcpURL, token string) error {
diff --git a/internal/executor/container_test.go b/internal/executor/container_test.go
index 86e95e2..3d0887c 100644
--- a/internal/executor/container_test.go
+++ b/internal/executor/container_test.go
@@ -54,6 +54,28 @@ func TestContainerRunner_BuildDockerArgs(t *testing.T) {
 	}
 }
 
+func TestBuildAgentInstructions(t *testing.T) {
+	t.Run("mcp enabled prepends preamble", func(t *testing.T) {
+		tk := &task.Task{Agent: task.AgentConfig{Instructions: "do the thing"}}
+		got := buildAgentInstructions(tk, true)
+		if !strings.HasPrefix(got, planningPreamble) || !strings.HasSuffix(got, "do the thing") {
+			t.Errorf("expected preamble + instructions, got %q", got)
+		}
+	})
+	t.Run("mcp disabled keeps raw instructions", func(t *testing.T) {
+		tk := &task.Task{Agent: task.AgentConfig{Instructions: "do the thing"}}
+		if got := buildAgentInstructions(tk, false); got != "do the thing" {
+			t.Errorf("expected raw instructions, got %q", got)
+		}
+	})
+	t.Run("skip planning keeps raw instructions even with mcp", func(t *testing.T) {
+		tk := &task.Task{Agent: task.AgentConfig{Instructions: "do the thing", SkipPlanning: true}}
+		if got := buildAgentInstructions(tk, true); got != "do the thing" {
+			t.Errorf("expected raw instructions when skip_planning, got %q", got)
+		}
+	})
+}
+
 func TestWriteMCPConfig(t *testing.T) {
 	dir := t.TempDir()
 	if err := writeMCPConfig(dir, "http://host.docker.internal:8484/mcp", "tok-abc"); err != nil {
diff --git a/internal/executor/preamble.go b/internal/executor/preamble.go
index b949986..77fae3c 100644
--- a/internal/executor/preamble.go
+++ b/internal/executor/preamble.go
@@ -2,61 +2,48 @@ package executor
 
 const planningPreamble = `## Runtime Environment
 
-You are running as a background agent inside Claudomator. You cannot interact
-with the user directly. However, if you need a decision or clarification:
-
-**To ask the user a question and pause:**
-1. Write a JSON object to the path in $CLAUDOMATOR_QUESTION_FILE:
-   {"text": "Your question here?", "options": ["option A", "option B"]}
-   (options is optional — omit it for free-text answers)
-2. Exit immediately. Do not wait. The task will be resumed with the user's answer
-   as the next message in this conversation.
-
-Only use this when you genuinely need user input to proceed. The text MUST be a
-real question ending with "?". Do NOT write completion reports or status updates
-here — use $CLAUDOMATOR_SUMMARY_FILE for those. Prefer making a reasonable
-decision and noting it in your summary rather than asking.
+You are running as a background agent inside Claudomator. You cannot chat with
+the user directly, but you have these tools to coordinate:
+
+- **ask_user** — ask the user a question when you genuinely need a decision to
+  proceed. After calling it, end your turn immediately; the task pauses and is
+  resumed with the user's answer. Prefer making a reasonable decision and noting
+  it via report_summary over asking.
+- **report_summary** — record a 2-5 sentence summary of what you did. Call this
+  before you finish so the user knows the outcome.
+- **spawn_subtask** — create a child task to be run separately.
+- **record_progress** — leave a short progress note in the task timeline.
 
 ---
 
 ## Planning Step (do this first)
 
-Before doing any implementation work:
-
-1. Estimate: will this task take more than 3 minutes of implementation effort?
+Before doing any implementation work, estimate whether the task will take more
+than ~3 minutes of effort.
 
-2. If YES — break it down:
-   - Create 3–7 discrete subtasks by POSTing to $CLAUDOMATOR_API_URL/api/tasks
-   - Each subtask POST body should be JSON with: name, agent.instructions, agent.project_dir (copy from $CLAUDOMATOR_PROJECT_DIR), agent.model, agent.allowed_tools, and agent.skip_planning set to true
-   - Set parent_task_id to $CLAUDOMATOR_TASK_ID in each POST body
-   - After creating all subtasks, output a brief summary and STOP. Do not implement anything.
-   - You can also specify agent.type (either "claude" or "gemini") to choose the agent for subtasks.
-
-3. If NO — proceed with the task instructions below.
+- If YES — break it into 3-7 focused pieces with spawn_subtask, then call
+  report_summary describing the breakdown and STOP. Do not implement anything.
+- If NO — proceed with the task instructions below.
 
 ---
 
-## Git Discipline (mandatory when project_dir is set)
+## Git Discipline (mandatory when working in a repository)
 
-Every change you make to the working directory **must be committed before you finish**.
-The sandbox is rejected if there are any uncommitted modifications.
+Every change you make **must be committed before you finish** — the workspace is
+rejected if there are uncommitted modifications.
 
-- After completing work: run "git add -A && git commit -m 'concise description'"
-- One commit is fine. Multiple focused commits are also fine.
-- If you realise the task was already done and you made no changes, that is also fine — just exit cleanly without committing.
-- Do not exit with uncommitted edits.
-- **CRITICAL:** Run ALL git commands from your current directory — do NOT use absolute paths or "cd <project_path> && git ...". Your working directory IS the project. Using absolute paths bypasses the sandbox and breaks commit tracking.
+- After completing work: run "git add -A && git commit -m 'concise description'".
+- One commit is fine; multiple focused commits are also fine.
+- If the task was already done and you made no changes, just exit cleanly.
+- Run ALL git commands from your current directory — do NOT use absolute paths
+  or "cd <path> && git ...". Your working directory IS the project.
 
 ---
 
-## Final Summary (mandatory)
-
-Before exiting, write a brief summary paragraph (2–5 sentences) describing what you did
-and the outcome. Write it to the path in $CLAUDOMATOR_SUMMARY_FILE:
-
-  echo "Your summary here." > "$CLAUDOMATOR_SUMMARY_FILE"
+## Before Finishing
 
-This summary is displayed in the task UI so the user knows what happened.
+Call report_summary with a brief paragraph describing what you did and the
+outcome. This is shown in the task UI.
 
 ---
 `
diff --git a/internal/executor/preamble_test.go b/internal/executor/preamble_test.go
index 5c31b4f..77a8fca 100644
--- a/internal/executor/preamble_test.go
+++ b/internal/executor/preamble_test.go
@@ -5,27 +5,37 @@ import (
 	"testing"
 )
 
-func TestPlanningPreamble_ContainsFinalSummarySection(t *testing.T) {
-	if !strings.Contains(planningPreamble, "## Final Summary (mandatory)") {
-		t.Error("planningPreamble missing '## Final Summary (mandatory)' heading")
+func TestPlanningPreamble_ReferencesMCPTools(t *testing.T) {
+	for _, tool := range []string{"ask_user", "report_summary", "spawn_subtask", "record_progress"} {
+		if !strings.Contains(planningPreamble, tool) {
+			t.Errorf("planningPreamble should mention the %q tool", tool)
+		}
 	}
 }
 
-func TestPlanningPreamble_SummaryUsesFileEnvVar(t *testing.T) {
-	if !strings.Contains(planningPreamble, "CLAUDOMATOR_SUMMARY_FILE") {
-		t.Error("planningPreamble should instruct agent to write summary to $CLAUDOMATOR_SUMMARY_FILE")
+func TestPlanningPreamble_NoFileEscapeHatches(t *testing.T) {
+	for _, marker := range []string{"CLAUDOMATOR_SUMMARY_FILE", "CLAUDOMATOR_QUESTION_FILE"} {
+		if strings.Contains(planningPreamble, marker) {
+			t.Errorf("planningPreamble should no longer reference %s", marker)
+		}
 	}
 }
 
-func TestPlanningPreamble_SummaryInstructsEchoToFile(t *testing.T) {
-	if !strings.Contains(planningPreamble, `"$CLAUDOMATOR_SUMMARY_FILE"`) {
-		t.Error("planningPreamble should show example of writing to $CLAUDOMATOR_SUMMARY_FILE via echo")
+func TestPlanningPreamble_AskUserEndsTurn(t *testing.T) {
+	if !strings.Contains(planningPreamble, "end your turn") {
+		t.Error("planningPreamble should instruct the agent to end its turn after ask_user")
 	}
 }
 
 func TestPlanningPreamble_GitDiscipline_ForbidsAbsolutePaths(t *testing.T) {
-	// Agents must not bypass the sandbox by using absolute project paths in git commands.
 	if !strings.Contains(planningPreamble, "do NOT use absolute paths") {
 		t.Error("planningPreamble should warn agents not to use absolute paths in git commands")
 	}
 }
+
+func TestWithPlanningPreamble_PrependsToInstructions(t *testing.T) {
+	got := withPlanningPreamble("DO THE THING")
+	if !strings.HasPrefix(got, planningPreamble) || !strings.HasSuffix(got, "DO THE THING") {
+		t.Error("withPlanningPreamble should prepend the preamble to the instructions")
+	}
+}
-- 
cgit v1.2.3


From 1ea57a7dbf4d34045a361e9bba9191de06cd1749 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 24 May 2026 17:42:45 +0000
Subject: refactor(executor): delete unused ClaudeRunner; keep sandbox helpers
 (Phase 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ClaudeRunner was never instantiated in production (serve.go wires only
ContainerRunner) and was not wired for MCP. Remove it and its CLI/buildArgs/
execOnce tests. The sandbox helpers it defined (sandboxCloneSource, setupSandbox,
teardownSandbox) are still used by GeminiRunner, so they move to sandbox.go;
their tests (plus the shared initGitRepo helper and the tailFile test) move to
sandbox_test.go.

No production behavior change — this removes dead code and the last file-based
agent wire that lived in ClaudeRunner.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/executor/claude.go       | 552 --------------------------
 internal/executor/claude_test.go  | 810 --------------------------------------
 internal/executor/sandbox.go      | 187 +++++++++
 internal/executor/sandbox_test.go | 366 +++++++++++++++++
 4 files changed, 553 insertions(+), 1362 deletions(-)
 delete mode 100644 internal/executor/claude.go
 delete mode 100644 internal/executor/claude_test.go
 create mode 100644 internal/executor/sandbox.go
 create mode 100644 internal/executor/sandbox_test.go

(limited to 'internal/executor')

diff --git a/internal/executor/claude.go b/internal/executor/claude.go
deleted file mode 100644
index 0123754..0000000
--- a/internal/executor/claude.go
+++ /dev/null
@@ -1,552 +0,0 @@
-package executor
-
-import (
-	"context"
-	"fmt"
-	"log/slog"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-	"sync"
-	"syscall"
-	"time"
-
-	"github.com/thepeterstone/claudomator/internal/retry"
-	"github.com/thepeterstone/claudomator/internal/storage"
-	"github.com/thepeterstone/claudomator/internal/task"
-)
-
-// ClaudeRunner spawns the `claude` CLI in non-interactive mode.
-type ClaudeRunner struct {
-	BinaryPath string // defaults to "claude"
-	Logger     *slog.Logger
-	LogDir     string // base directory for execution logs
-	APIURL     string // base URL of the Claudomator API, passed to subprocesses
-}
-
-// BlockedError is returned by Run when the agent wrote a question file and exited.
-// The pool transitions the task to BLOCKED and stores the question for the user.
-// ExecLogDir returns the log directory for the given execution ID.
-// Implements LogPather so the pool can persist paths before execution starts.
-func (r *ClaudeRunner) ExecLogDir(execID string) string {
-	if r.LogDir == "" {
-		return ""
-	}
-	return filepath.Join(r.LogDir, execID)
-}
-
-func (r *ClaudeRunner) binaryPath() string {
-	if r.BinaryPath != "" {
-		return r.BinaryPath
-	}
-	return "claude"
-}
-
-// Run executes a claude -p invocation, streaming output to log files.
-// It retries up to 3 times on rate-limit errors using exponential backoff.
-// If the agent writes a question file and exits, Run returns *BlockedError.
-//
-// When project_dir is set and this is not a resume execution, Run clones the
-// project into a temp sandbox, runs the agent there, then merges committed
-// changes back to project_dir. On failure the sandbox is preserved and its
-// path is included in the error.
-func (r *ClaudeRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, ch AgentChannel) error {
-	projectDir := t.Agent.ProjectDir
-
-	// Validate project_dir exists when set.
-	if projectDir != "" {
-		if _, err := os.Stat(projectDir); err != nil {
-			return fmt.Errorf("project_dir %q: %w", projectDir, err)
-		}
-	}
-
-	// Setup log directory once; retries overwrite the log files.
-	logDir := r.ExecLogDir(e.ID)
-	if logDir == "" {
-		logDir = e.ID // fallback for tests without LogDir set
-	}
-	if err := os.MkdirAll(logDir, 0700); err != nil {
-		return fmt.Errorf("creating log dir: %w", err)
-	}
-	if e.StdoutPath == "" {
-		e.StdoutPath = filepath.Join(logDir, "stdout.log")
-		e.StderrPath = filepath.Join(logDir, "stderr.log")
-		e.ArtifactDir = logDir
-	}
-
-	// Pre-assign session ID so we can resume after a BLOCKED state.
-	// For resume executions, the claude session continues under the original
-	// session ID (the one passed to --resume). Using the new exec's own UUID
-	// would cause a second block-and-resume cycle to pass the wrong --resume
-	// argument.
-	if e.SessionID == "" {
-		if e.ResumeSessionID != "" {
-			e.SessionID = e.ResumeSessionID
-		} else {
-			e.SessionID = e.ID // reuse execution UUID as session UUID (both are UUIDs)
-		}
-	}
-
-	// For new (non-resume) executions with a project_dir, clone into a sandbox.
-	// Resume executions run in the preserved sandbox (e.SandboxDir) so Claude
-	// finds its session files under the same project slug. If no sandbox was
-	// preserved (e.g. task had no project_dir), fall back to project_dir.
-	var sandboxDir string
-	var startHEAD string
-	effectiveWorkingDir := projectDir
-	if e.ResumeSessionID != "" {
-		if e.SandboxDir != "" {
-			if _, statErr := os.Stat(e.SandboxDir); statErr == nil {
-				effectiveWorkingDir = e.SandboxDir
-			} else {
-				// Preserved sandbox was cleaned up (e.g. /tmp purge after reboot).
-				// Clone a fresh sandbox so the task can run rather than fail immediately.
-				r.Logger.Warn("preserved sandbox missing, cloning fresh", "sandbox", e.SandboxDir, "project_dir", projectDir)
-				e.SandboxDir = ""
-				if projectDir != "" {
-					var err error
-					sandboxDir, err = setupSandbox(t.Agent.ProjectDir, r.Logger)
-					if err != nil {
-						return fmt.Errorf("setting up sandbox: %w", err)
-					}
-
-					effectiveWorkingDir = sandboxDir
-					r.Logger.Info("fresh sandbox created for resume", "sandbox", sandboxDir, "project_dir", projectDir)
-				}
-			}
-		}
-	} else if projectDir != "" {
-		var err error
-		sandboxDir, err = setupSandbox(t.Agent.ProjectDir, r.Logger)
-		if err != nil {
-			return fmt.Errorf("setting up sandbox: %w", err)
-		}
-
-		effectiveWorkingDir = sandboxDir
-		r.Logger.Info("sandbox created", "sandbox", sandboxDir, "project_dir", projectDir)
-	}
-
-	if effectiveWorkingDir != "" {
-		// Capture the initial HEAD so we can identify new commits later.
-		headOut, _ := exec.Command("git", gitSafe("-C", effectiveWorkingDir, "rev-parse", "HEAD")...).Output()
-		startHEAD = strings.TrimSpace(string(headOut))
-	}
-
-	questionFile := filepath.Join(logDir, "question.json")
-	args := r.buildArgs(t, e, questionFile)
-
-	attempt := 0
-	err := retry.RunWithBackoff(ctx, 3, 5*time.Second, func() error {
-		if attempt > 0 {
-			delay := 5 * time.Second * (1 << (attempt - 1))
-			r.Logger.Warn("rate-limited by Claude API, retrying",
-				"attempt", attempt,
-				"delay", delay,
-			)
-		}
-		attempt++
-		return r.execOnce(ctx, args, effectiveWorkingDir, projectDir, e)
-	})
-	if err != nil {
-		if sandboxDir != "" {
-			return fmt.Errorf("%w (sandbox preserved at %s)", err, sandboxDir)
-		}
-		return err
-	}
-
-	// Check whether the agent left a question before exiting.
-	data, readErr := os.ReadFile(questionFile)
-	if readErr == nil {
-		os.Remove(questionFile) // consumed
-		questionJSON := strings.TrimSpace(string(data))
-		// If the agent wrote a completion report instead of a real question,
-		// extract the text as the summary and fall through to normal completion.
-		if isCompletionReport(questionJSON) {
-			r.Logger.Info("treating question file as completion report", "taskID", e.TaskID)
-			_ = ch.ReportSummary(ctx, extractQuestionText(questionJSON))
-		} else {
-			// Preserve sandbox on BLOCKED — agent may have partial work and its
-			// Claude session files are stored under the sandbox's project slug.
-			// The resume execution must run in the same directory.
-			return &BlockedError{QuestionJSON: questionJSON, SessionID: e.SessionID, SandboxDir: sandboxDir}
-		}
-	}
-
-	// Read agent summary if written.
-	summaryFile := filepath.Join(logDir, "summary.txt")
-	if summaryData, readErr := os.ReadFile(summaryFile); readErr == nil {
-		os.Remove(summaryFile) // consumed
-		_ = ch.ReportSummary(ctx, strings.TrimSpace(string(summaryData)))
-	}
-
-	// Merge sandbox back to project_dir and clean up.
-	if sandboxDir != "" {
-		if mergeErr := teardownSandbox(projectDir, sandboxDir, startHEAD, r.Logger, e); mergeErr != nil {
-			return fmt.Errorf("sandbox teardown: %w (sandbox preserved at %s)", mergeErr, sandboxDir)
-		}
-	}
-	return nil
-}
-
-// sandboxCloneSource returns the URL to clone the sandbox from. It prefers a
-// remote named "local" (a local bare repo that accepts pushes cleanly), then
-// falls back to "origin", then to the working copy path itself.
-func sandboxCloneSource(projectDir string) string {
-	for _, remote := range []string{"local", "origin"} {
-		out, err := exec.Command("git", gitSafe("-C", projectDir, "remote", "get-url", remote)...).Output()
-		if err == nil {
-			u := strings.TrimSpace(string(out))
-			if u != "" && (strings.HasPrefix(u, "/") || strings.HasPrefix(u, "file://")) {
-				return u
-			}
-		}
-	}
-	return projectDir
-}
-
-// setupSandbox prepares a temporary git clone of projectDir.
-// If projectDir is not a git repo it is initialised with an initial commit first.
-func setupSandbox(projectDir string, logger *slog.Logger) (string, error) {
-	// Ensure projectDir is a git repo; initialise if not.
-	if err := exec.Command("git", gitSafe("-C", projectDir, "rev-parse", "--git-dir")...).Run(); err != nil {
-		cmds := [][]string{
-			gitSafe("-C", projectDir, "init"),
-			gitSafe("-C", projectDir, "add", "-A"),
-			gitSafe("-C", projectDir, "commit", "--allow-empty", "-m", "chore: initial commit"),
-		}
-		for _, args := range cmds {
-			if out, err := exec.Command("git", args...).CombinedOutput(); err != nil { //nolint:gosec
-				return "", fmt.Errorf("git init %s: %w\n%s", projectDir, err, out)
-			}
-		}
-	}
-
-	src := sandboxCloneSource(projectDir)
-
-	tempDir, err := os.MkdirTemp("", "claudomator-sandbox-*")
-	if err != nil {
-		return "", fmt.Errorf("creating sandbox dir: %w", err)
-	}
-	// git clone requires the target to not exist; remove the placeholder first.
-	if err := os.Remove(tempDir); err != nil {
-		return "", fmt.Errorf("removing temp dir placeholder: %w", err)
-	}
-	out, err := exec.Command("git", gitSafe("clone", "--no-hardlinks", src, tempDir)...).CombinedOutput()
-	if err != nil {
-		return "", fmt.Errorf("git clone: %w\n%s", err, out)
-	}
-	return tempDir, nil
-}
-
-// teardownSandbox verifies the sandbox is clean and pushes new commits to the
-// canonical bare repo. If the push is rejected because another task pushed
-// concurrently, it fetches and rebases then retries once.
-//
-// The working copy (projectDir) is NOT updated automatically — it is the
-// developer's workspace and is pulled manually. This avoids permission errors
-// from mixed-owner .git/objects directories.
-func teardownSandbox(projectDir, sandboxDir, startHEAD string, logger *slog.Logger, execRecord *storage.Execution) error {
-	// Automatically commit uncommitted changes.
-	out, err := exec.Command("git", "-C", sandboxDir, "status", "--porcelain").Output()
-	if err != nil {
-		return fmt.Errorf("git status: %w", err)
-	}
-	if len(strings.TrimSpace(string(out))) > 0 {
-		logger.Info("autocommitting uncommitted changes", "sandbox", sandboxDir)
-
-		// Run build before autocommitting.
-		if _, err := os.Stat(filepath.Join(sandboxDir, "Makefile")); err == nil {
-			logger.Info("running 'make build' before autocommit", "sandbox", sandboxDir)
-			if buildOut, buildErr := exec.Command("make", "-C", sandboxDir, "build").CombinedOutput(); buildErr != nil {
-				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
-			}
-		} else if _, err := os.Stat(filepath.Join(sandboxDir, "gradlew")); err == nil {
-			logger.Info("running './gradlew build' before autocommit", "sandbox", sandboxDir)
-			cmd := exec.Command("./gradlew", "build")
-			cmd.Dir = sandboxDir
-			if buildOut, buildErr := cmd.CombinedOutput(); buildErr != nil {
-				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
-			}
-		} else if _, err := os.Stat(filepath.Join(sandboxDir, "go.mod")); err == nil {
-			logger.Info("running 'go build ./...' before autocommit", "sandbox", sandboxDir)
-			cmd := exec.Command("go", "build", "./...")
-			cmd.Dir = sandboxDir
-			if buildOut, buildErr := cmd.CombinedOutput(); buildErr != nil {
-				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
-			}
-		}
-
-		cmds := [][]string{
-			gitSafe("-C", sandboxDir, "add", "-A"),
-			gitSafe("-C", sandboxDir, "commit", "-m", "chore: autocommit uncommitted changes"),
-		}
-		for _, args := range cmds {
-			if out, err := exec.Command("git", args...).CombinedOutput(); err != nil {
-				return fmt.Errorf("autocommit failed (%v): %w\n%s", args, err, out)
-			}
-		}
-	}
-
-	// Capture commits before pushing/deleting.
-	// Use startHEAD..HEAD to find all commits made during this execution.
-	logRange := "origin/HEAD..HEAD"
-	if startHEAD != "" && startHEAD != "HEAD" {
-		logRange = startHEAD + "..HEAD"
-	}
-
-	logCmd := exec.Command("git", gitSafe("-C", sandboxDir, "log", logRange, "--pretty=format:%H|%s")...)
-	logOut, logErr := logCmd.CombinedOutput()
-	if logErr == nil {
-		lines := strings.Split(strings.TrimSpace(string(logOut)), "\n")
-		logger.Debug("captured commits", "count", len(lines), "range", logRange)
-		for _, line := range lines {
-			if line == "" {
-				continue
-			}
-			parts := strings.SplitN(line, "|", 2)
-			if len(parts) == 2 {
-				execRecord.Commits = append(execRecord.Commits, task.GitCommit{
-					Hash:    parts[0],
-					Message: parts[1],
-				})
-			}
-		}
-	} else {
-		logger.Warn("failed to capture commits", "err", logErr, "range", logRange, "output", string(logOut))
-	}
-
-	// Check whether there are any new commits to push.
-	ahead, err := exec.Command("git", gitSafe("-C", sandboxDir, "rev-list", "--count", logRange)...).Output()
-	if err != nil {
-		logger.Warn("could not determine commits ahead of origin; proceeding", "err", err, "range", logRange)
-	}
-	if strings.TrimSpace(string(ahead)) == "0" {
-		os.RemoveAll(sandboxDir)
-		return nil
-	}
-
-	// Push from sandbox → bare repo (sandbox's origin is the bare repo).
-	if out, err := exec.Command("git", "-C", sandboxDir, "push", "origin", "HEAD").CombinedOutput(); err != nil {
-		// If rejected due to concurrent push, fetch+rebase and retry once.
-		if strings.Contains(string(out), "fetch first") || strings.Contains(string(out), "non-fast-forward") {
-			logger.Info("push rejected (concurrent task); rebasing and retrying", "sandbox", sandboxDir)
-			if out2, err2 := exec.Command("git", "-C", sandboxDir, "pull", "--rebase", "origin", "master").CombinedOutput(); err2 != nil {
-				return fmt.Errorf("git rebase before retry push: %w\n%s", err2, out2)
-			}
-			// Re-capture commits after rebase (hashes might have changed)
-			execRecord.Commits = nil
-			logOut, logErr = exec.Command("git", "-C", sandboxDir, "log", logRange, "--pretty=format:%H|%s").Output()
-			if logErr == nil {
-				lines := strings.Split(strings.TrimSpace(string(logOut)), "\n")
-				for _, line := range lines {
-					parts := strings.SplitN(line, "|", 2)
-					if len(parts) == 2 {
-						execRecord.Commits = append(execRecord.Commits, task.GitCommit{
-							Hash:    parts[0],
-							Message: parts[1],
-						})
-					}
-				}
-			}
-
-			if out3, err3 := exec.Command("git", "-C", sandboxDir, "push", "origin", "HEAD").CombinedOutput(); err3 != nil {
-				return fmt.Errorf("git push to origin (after rebase): %w\n%s", err3, out3)
-			}
-		} else {
-			return fmt.Errorf("git push to origin: %w\n%s", err, out)
-		}
-	}
-
-	logger.Info("sandbox pushed to bare repo", "sandbox", sandboxDir)
-	os.RemoveAll(sandboxDir)
-	return nil
-}
-
-// execOnce runs the claude subprocess once, streaming output to e's log paths.
-func (r *ClaudeRunner) execOnce(ctx context.Context, args []string, workingDir, projectDir string, e *storage.Execution) error {
-	cmd := exec.CommandContext(ctx, r.binaryPath(), args...)
-	cmd.Env = append(os.Environ(),
-		"CLAUDOMATOR_API_URL="+r.APIURL,
-		"CLAUDOMATOR_TASK_ID="+e.TaskID,
-		"CLAUDOMATOR_PROJECT_DIR="+projectDir,
-		"CLAUDOMATOR_QUESTION_FILE="+filepath.Join(e.ArtifactDir, "question.json"),
-		"CLAUDOMATOR_SUMMARY_FILE="+filepath.Join(e.ArtifactDir, "summary.txt"),
-	)
-	// Put the subprocess in its own process group so we can SIGKILL the entire
-	// group (MCP servers, bash children, etc.) on cancellation.
-	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
-	if workingDir != "" {
-		cmd.Dir = workingDir
-	}
-
-	stdoutFile, err := os.Create(e.StdoutPath)
-	if err != nil {
-		return fmt.Errorf("creating stdout log: %w", err)
-	}
-	defer stdoutFile.Close()
-
-	stderrFile, err := os.Create(e.StderrPath)
-	if err != nil {
-		return fmt.Errorf("creating stderr log: %w", err)
-	}
-	defer stderrFile.Close()
-
-	// Use os.Pipe for stdout so we own the read-end lifetime.
-	// cmd.StdoutPipe() would add the read-end to closeAfterWait, causing
-	// cmd.Wait() to close it before our goroutine finishes reading.
-	stdoutR, stdoutW, err := os.Pipe()
-	if err != nil {
-		return fmt.Errorf("creating stdout pipe: %w", err)
-	}
-	cmd.Stdout = stdoutW // *os.File — not added to closeAfterStart/Wait
-	cmd.Stderr = stderrFile
-
-	if err := cmd.Start(); err != nil {
-		stdoutW.Close()
-		stdoutR.Close()
-		return fmt.Errorf("starting claude: %w", err)
-	}
-	// Close our write-end immediately; the subprocess holds its own copy.
-	// The goroutine below gets EOF when the subprocess exits.
-	stdoutW.Close()
-
-	// killDone is closed when cmd.Wait() returns, stopping the pgid-kill goroutine.
-	//
-	// Safety: this goroutine cannot block indefinitely. The select has two arms:
-	//   • ctx.Done() — fires if the caller cancels (e.g. timeout, user cancel).
-	//     The goroutine sends SIGKILL and exits immediately.
-	//   • killDone — closed by close(killDone) below, immediately after cmd.Wait()
-	//     returns. This fires when the process exits for any reason (natural exit,
-	//     SIGKILL from the ctx arm, or any other signal). The goroutine exits without
-	//     doing anything.
-	//
-	// Therefore: for a task that completes normally with a long-lived (non-cancelled)
-	// context, the killDone arm fires and the goroutine exits. There is no path where
-	// this goroutine outlives execOnce().
-	killDone := make(chan struct{})
-	go func() {
-		select {
-		case <-ctx.Done():
-			// SIGKILL the entire process group to reap orphan children.
-			syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
-		case <-killDone:
-		}
-	}()
-
-	// Stream stdout to the log file and parse cost/errors.
-	// wg ensures costUSD and streamErr are fully written before we read them after cmd.Wait().
-	var costUSD float64
-	var streamErr error
-	var wg sync.WaitGroup
-	wg.Add(1)
-	go func() {
-		defer wg.Done()
-		costUSD, _, streamErr = parseStream(stdoutR, stdoutFile, r.Logger)
-		stdoutR.Close()
-	}()
-
-	waitErr := cmd.Wait()
-	close(killDone) // stop the pgid-kill goroutine
-	wg.Wait()       // drain remaining stdout before reading costUSD/streamErr
-
-	e.CostUSD = costUSD
-
-	if waitErr != nil {
-		if exitErr, ok := waitErr.(*exec.ExitError); ok {
-			e.ExitCode = exitErr.ExitCode()
-		}
-		// If the stream captured a rate-limit or quota message, return it
-		// so callers can distinguish it from a generic exit-status failure.
-		if retry.IsRateLimitError(streamErr) || isQuotaExhausted(streamErr) {
-			return streamErr
-		}
-		if tail := tailFile(e.StderrPath, 20); tail != "" {
-			return fmt.Errorf("claude exited with error: %w\nstderr:\n%s", waitErr, tail)
-		}
-		return fmt.Errorf("claude exited with error: %w", waitErr)
-	}
-
-	e.ExitCode = 0
-	if streamErr != nil {
-		return streamErr
-	}
-	return nil
-}
-
-func (r *ClaudeRunner) buildArgs(t *task.Task, e *storage.Execution, questionFile string) []string {
-	// Resume execution: the agent already has context; just deliver the answer.
-	if e.ResumeSessionID != "" {
-		args := []string{
-			"-p", e.ResumeAnswer,
-			"--resume", e.ResumeSessionID,
-			"--output-format", "stream-json",
-			"--verbose",
-		}
-		permMode := t.Agent.PermissionMode
-		if permMode == "" {
-			permMode = "bypassPermissions"
-		}
-		args = append(args, "--permission-mode", permMode)
-		if t.Agent.Model != "" {
-			args = append(args, "--model", t.Agent.Model)
-		}
-		return args
-	}
-
-	instructions := t.Agent.Instructions
-	allowedTools := t.Agent.AllowedTools
-
-	if !t.Agent.SkipPlanning {
-		instructions = withPlanningPreamble(instructions)
-		// Ensure Bash is available so the agent can POST subtasks and ask questions.
-		hasBash := false
-		for _, tool := range allowedTools {
-			if tool == "Bash" {
-				hasBash = true
-				break
-			}
-		}
-		if !hasBash {
-			allowedTools = append(allowedTools, "Bash")
-		}
-	}
-
-	args := []string{
-		"-p", instructions,
-		"--session-id", e.SessionID,
-		"--output-format", "stream-json",
-		"--verbose",
-	}
-
-	if t.Agent.Model != "" {
-		args = append(args, "--model", t.Agent.Model)
-	}
-	if t.Agent.MaxBudgetUSD > 0 {
-		args = append(args, "--max-budget-usd", fmt.Sprintf("%.2f", t.Agent.MaxBudgetUSD))
-	}
-	// Default to bypassPermissions — claudomator runs tasks unattended, so
-	// prompting for write access would always stall execution. Tasks that need
-	// a more restrictive mode can set permission_mode explicitly.
-	permMode := t.Agent.PermissionMode
-	if permMode == "" {
-		permMode = "bypassPermissions"
-	}
-	args = append(args, "--permission-mode", permMode)
-	if t.Agent.SystemPromptAppend != "" {
-		args = append(args, "--append-system-prompt", t.Agent.SystemPromptAppend)
-	}
-	for _, tool := range allowedTools {
-		args = append(args, "--allowedTools", tool)
-	}
-	for _, tool := range t.Agent.DisallowedTools {
-		args = append(args, "--disallowedTools", tool)
-	}
-	for _, f := range t.Agent.ContextFiles {
-		args = append(args, "--add-dir", f)
-	}
-	args = append(args, t.Agent.AdditionalArgs...)
-
-	return args
-}
-
diff --git a/internal/executor/claude_test.go b/internal/executor/claude_test.go
deleted file mode 100644
index 414f6cf..0000000
--- a/internal/executor/claude_test.go
+++ /dev/null
@@ -1,810 +0,0 @@
-package executor
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"log/slog"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/thepeterstone/claudomator/internal/storage"
-	"github.com/thepeterstone/claudomator/internal/task"
-)
-
-func TestClaudeRunner_BuildArgs_BasicTask(t *testing.T) {
-	r := &ClaudeRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			Instructions: "fix the bug",
-			Model:        "sonnet",
-			SkipPlanning: true,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	argMap := make(map[string]bool)
-	for _, a := range args {
-		argMap[a] = true
-	}
-	for _, want := range []string{"-p", "fix the bug", "--output-format", "stream-json", "--verbose", "--model", "sonnet"} {
-		if !argMap[want] {
-			t.Errorf("missing arg %q in %v", want, args)
-		}
-	}
-}
-
-func TestClaudeRunner_BuildArgs_FullConfig(t *testing.T) {
-	r := &ClaudeRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:               "claude",
-			Instructions:       "implement feature",
-			Model:              "opus",
-			MaxBudgetUSD:       5.0,
-			PermissionMode:     "bypassPermissions",
-			SystemPromptAppend: "Follow TDD",
-			AllowedTools:       []string{"Bash", "Edit"},
-			DisallowedTools:    []string{"Write"},
-			ContextFiles:       []string{"/src"},
-			AdditionalArgs:     []string{"--verbose"},
-			SkipPlanning:       true,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	// Check key args are present.
-	argMap := make(map[string]bool)
-	for _, a := range args {
-		argMap[a] = true
-	}
-
-	requiredArgs := []string{
-		"-p", "implement feature", "--output-format", "stream-json",
-		"--model", "opus", "--max-budget-usd", "5.00",
-		"--permission-mode", "bypassPermissions",
-		"--append-system-prompt", "Follow TDD",
-		"--allowedTools", "Bash", "Edit",
-		"--disallowedTools", "Write",
-		"--add-dir", "/src",
-		"--verbose",
-	}
-	for _, req := range requiredArgs {
-		if !argMap[req] {
-			t.Errorf("missing arg %q in %v", req, args)
-		}
-	}
-}
-
-func TestClaudeRunner_BuildArgs_DefaultsToBypassPermissions(t *testing.T) {
-	r := &ClaudeRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			Instructions: "do work",
-			SkipPlanning: true,
-			// PermissionMode intentionally not set
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	found := false
-	for i, a := range args {
-		if a == "--permission-mode" && i+1 < len(args) && args[i+1] == "bypassPermissions" {
-			found = true
-		}
-	}
-	if !found {
-		t.Errorf("expected --permission-mode bypassPermissions when PermissionMode is empty, args: %v", args)
-	}
-}
-
-func TestClaudeRunner_BuildArgs_RespectsExplicitPermissionMode(t *testing.T) {
-	r := &ClaudeRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:           "claude",
-			Instructions:   "do work",
-			PermissionMode: "default",
-			SkipPlanning:   true,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	for i, a := range args {
-		if a == "--permission-mode" && i+1 < len(args) {
-			if args[i+1] != "default" {
-				t.Errorf("expected --permission-mode default, got %q", args[i+1])
-			}
-			return
-		}
-	}
-	t.Errorf("--permission-mode flag not found in args: %v", args)
-}
-
-func TestClaudeRunner_BuildArgs_AlwaysIncludesVerbose(t *testing.T) {
-	r := &ClaudeRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			Instructions: "do something",
-			SkipPlanning: true,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	found := false
-	for _, a := range args {
-		if a == "--verbose" {
-			found = true
-			break
-		}
-	}
-	if !found {
-		t.Errorf("--verbose missing from args: %v", args)
-	}
-}
-
-func TestClaudeRunner_BuildArgs_PreamblePrepended(t *testing.T) {
-	r := &ClaudeRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			Instructions: "fix the bug",
-			SkipPlanning: false,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	// The -p value should start with the preamble and end with the original instructions.
-	if len(args) < 2 || args[0] != "-p" {
-		t.Fatalf("expected -p as first arg, got: %v", args)
-	}
-	if !strings.HasPrefix(args[1], "## Runtime Environment") {
-		t.Errorf("instructions should start with planning preamble, got prefix: %q", args[1][:min(len(args[1]), 20)])
-	}
-	if !strings.Contains(args[1], "$CLAUDOMATOR_PROJECT_DIR") {
-		t.Errorf("preamble should mention $CLAUDOMATOR_PROJECT_DIR")
-	}
-	if !strings.HasSuffix(args[1], "fix the bug") {
-		t.Errorf("instructions should end with original instructions")
-	}
-}
-
-func TestClaudeRunner_BuildArgs_PreambleAddsBash(t *testing.T) {
-	r := &ClaudeRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			Instructions: "do work",
-			AllowedTools: []string{"Read"},
-			SkipPlanning: false,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	// Bash should be appended to allowed tools.
-	foundBash := false
-	for i, a := range args {
-		if a == "--allowedTools" && i+1 < len(args) && args[i+1] == "Bash" {
-			foundBash = true
-		}
-	}
-	if !foundBash {
-		t.Errorf("Bash should be added to --allowedTools when preamble is active: %v", args)
-	}
-}
-
-func TestClaudeRunner_BuildArgs_PreambleBashNotDuplicated(t *testing.T) {
-	r := &ClaudeRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			Instructions: "do work",
-			AllowedTools: []string{"Bash", "Read"},
-			SkipPlanning: false,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	// Count Bash occurrences in --allowedTools values.
-	bashCount := 0
-	for i, a := range args {
-		if a == "--allowedTools" && i+1 < len(args) && args[i+1] == "Bash" {
-			bashCount++
-		}
-	}
-	if bashCount != 1 {
-		t.Errorf("Bash should appear exactly once in --allowedTools, got %d: %v", bashCount, args)
-	}
-}
-
-// TestClaudeRunner_Run_ResumeSetsSessionIDFromResumeSession verifies that when a
-// resume execution is itself blocked again, the stored SessionID is the original
-// resumed session, not the new execution's own UUID. Without this, a second
-// block-and-resume cycle passes the wrong --resume session ID and fails.
-func TestClaudeRunner_Run_ResumeSetsSessionIDFromResumeSession(t *testing.T) {
-	logDir := t.TempDir()
-	r := &ClaudeRunner{
-		BinaryPath: "true", // exits 0, no output
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			Instructions: "continue",
-			SkipPlanning: true,
-		},
-	}
-	exec := &storage.Execution{
-		ID:              "resume-exec-uuid",
-		TaskID:          "task-1",
-		ResumeSessionID: "original-session-uuid",
-		ResumeAnswer:    "yes",
-	}
-
-	// Run completes successfully (binary is "true").
-	_ = r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
-
-	// SessionID must be the original session (ResumeSessionID), not the new
-	// exec's own ID. If it were exec.ID, a second blocked-then-resumed cycle
-	// would use the wrong --resume argument and fail.
-	if exec.SessionID != "original-session-uuid" {
-		t.Errorf("SessionID after resume Run: want %q, got %q", "original-session-uuid", exec.SessionID)
-	}
-}
-
-func TestClaudeRunner_Run_InaccessibleWorkingDir_ReturnsError(t *testing.T) {
-	r := &ClaudeRunner{
-		BinaryPath: "true", // would succeed if it ran
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     t.TempDir(),
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			ProjectDir:   "/nonexistent/path/does/not/exist",
-			SkipPlanning: true,
-		},
-	}
-	exec := &storage.Execution{ID: "test-exec"}
-
-	err := r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
-
-	if err == nil {
-		t.Fatal("expected error for inaccessible working_dir, got nil")
-	}
-	if !strings.Contains(err.Error(), "project_dir") {
-		t.Errorf("expected 'project_dir' in error, got: %v", err)
-	}
-}
-
-func TestClaudeRunner_BinaryPath_Default(t *testing.T) {
-	r := &ClaudeRunner{}
-	if r.binaryPath() != "claude" {
-		t.Errorf("want 'claude', got %q", r.binaryPath())
-	}
-}
-
-func TestClaudeRunner_BinaryPath_Custom(t *testing.T) {
-	r := &ClaudeRunner{BinaryPath: "/usr/local/bin/claude"}
-	if r.binaryPath() != "/usr/local/bin/claude" {
-		t.Errorf("want custom path, got %q", r.binaryPath())
-	}
-}
-
-// TestExecOnce_NoGoroutineLeak_OnNaturalExit verifies that execOnce does not
-// leave behind any goroutines when the subprocess exits normally (no context
-// cancellation). Both the pgid-kill goroutine and the parseStream goroutine
-// must have exited before execOnce returns.
-func TestExecOnce_NoGoroutineLeak_OnNaturalExit(t *testing.T) {
-	logDir := t.TempDir()
-	r := &ClaudeRunner{
-		BinaryPath: "true", // exits immediately with status 0, produces no output
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	e := &storage.Execution{
-		ID:          "goroutine-leak-test",
-		TaskID:      "task-id",
-		StdoutPath:  filepath.Join(logDir, "stdout.log"),
-		StderrPath:  filepath.Join(logDir, "stderr.log"),
-		ArtifactDir: logDir,
-	}
-
-	// Let any goroutines from test infrastructure settle before sampling.
-	runtime.Gosched()
-	baseline := runtime.NumGoroutine()
-
-	if err := r.execOnce(context.Background(), []string{}, "", "", e); err != nil {
-		t.Fatalf("execOnce failed: %v", err)
-	}
-
-	// Give the scheduler a moment to let any leaked goroutines actually exit.
-	// In correct code the goroutines exit before execOnce returns, so this is
-	// just a safety buffer for the scheduler.
-	time.Sleep(10 * time.Millisecond)
-	runtime.Gosched()
-
-	after := runtime.NumGoroutine()
-	if after > baseline {
-		t.Errorf("goroutine leak: %d goroutines before execOnce, %d after (leaked %d)",
-			baseline, after, after-baseline)
-	}
-}
-
-// initGitRepo creates a git repo in dir with one commit so it is clonable.
-func initGitRepo(t *testing.T, dir string) {
-	t.Helper()
-	cmds := [][]string{
-		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "init", "-b", "main"},
-		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "config", "user.email", "test@test"},
-		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "config", "user.name", "test"},
-	}
-	for _, args := range cmds {
-		if out, err := exec.Command(args[0], args[1:]...).CombinedOutput(); err != nil {
-			t.Fatalf("%v: %v\n%s", args, err, out)
-		}
-	}
-	if err := os.WriteFile(filepath.Join(dir, "init.txt"), []byte("init"), 0644); err != nil {
-		t.Fatal(err)
-	}
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "add", ".").CombinedOutput(); err != nil {
-		t.Fatalf("git add: %v\n%s", err, out)
-	}
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "commit", "-m", "init").CombinedOutput(); err != nil {
-		t.Fatalf("git commit: %v\n%s", err, out)
-	}
-}
-
-func TestSandboxCloneSource_PrefersLocalRemote(t *testing.T) {
-	dir := t.TempDir()
-	initGitRepo(t, dir)
-	// Add a "local" remote pointing to a bare repo.
-	bare := t.TempDir()
-	exec.Command("git", "init", "--bare", bare).Run()
-	exec.Command("git", "-C", dir, "remote", "add", "local", bare).Run()
-	exec.Command("git", "-C", dir, "remote", "add", "origin", "https://example.com/repo").Run()
-
-	got := sandboxCloneSource(dir)
-	if got != bare {
-		t.Errorf("expected bare repo path %q, got %q", bare, got)
-	}
-}
-
-func TestSandboxCloneSource_FallsBackToOrigin(t *testing.T) {
-	dir := t.TempDir()
-	initGitRepo(t, dir)
-	// sandboxCloneSource intentionally filters to local-FS remotes (so
-	// `git clone <src>` doesn't go over the network). Use a local path
-	// for origin to verify the fallback semantics.
-	originURL := t.TempDir()
-	exec.Command("git", "-C", dir, "remote", "add", "origin", originURL).Run()
-
-	got := sandboxCloneSource(dir)
-	if got != originURL {
-		t.Errorf("expected origin URL %q, got %q", originURL, got)
-	}
-}
-
-func TestSandboxCloneSource_FallsBackToProjectDir(t *testing.T) {
-	dir := t.TempDir()
-	initGitRepo(t, dir)
-	// No remotes configured.
-	got := sandboxCloneSource(dir)
-	if got != dir {
-		t.Errorf("expected projectDir %q (no remotes), got %q", dir, got)
-	}
-}
-
-func TestSetupSandbox_ClonesGitRepo(t *testing.T) {
-	src := t.TempDir()
-	initGitRepo(t, src)
-
-	sandbox, err := setupSandbox(src, slog.Default())
-	if err != nil {
-		t.Fatalf("setupSandbox: %v", err)
-	}
-	t.Cleanup(func() { os.RemoveAll(sandbox) })
-
-	// Force sandbox to master if it cloned as main
-	exec.Command("git", gitSafe("-C", sandbox, "checkout", "master")...).Run()
-
-	// Debug sandbox
-	logOut, _ := exec.Command("git", "-C", sandbox, "log", "-1").CombinedOutput()
-	fmt.Printf("DEBUG: sandbox log: %s\n", string(logOut))
-
-	// Verify sandbox is a git repo with at least one commit.
-	out, err := exec.Command("git", "-C", sandbox, "log", "--oneline").Output()
-	if err != nil {
-		t.Fatalf("git log in sandbox: %v", err)
-	}
-	if len(strings.TrimSpace(string(out))) == 0 {
-		t.Error("expected at least one commit in sandbox, got empty log")
-	}
-}
-
-func TestSetupSandbox_InitialisesNonGitDir(t *testing.T) {
-	// A plain directory (not a git repo) should be initialised then cloned.
-	src := t.TempDir()
-
-	sandbox, err := setupSandbox(src, slog.Default())
-	if err != nil {
-		t.Fatalf("setupSandbox on plain dir: %v", err)
-	}
-	t.Cleanup(func() { os.RemoveAll(sandbox) })
-
-	if _, err := os.Stat(filepath.Join(sandbox, ".git")); err != nil {
-		t.Errorf("sandbox should be a git repo: %v", err)
-	}
-}
-
-func TestTeardownSandbox_AutocommitsChanges(t *testing.T) {
-	// Create a bare repo as origin so push succeeds.
-	bare := t.TempDir()
-	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git init bare: %v\n%s", err, out)
-	}
-
-	// Create a sandbox directly.
-	sandbox := t.TempDir()
-	initGitRepo(t, sandbox)
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git remote add: %v\n%s", err, out)
-	}
-	// Initial push to establish origin/main
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "push", "origin", "main").CombinedOutput(); err != nil {
-		t.Fatalf("git push initial: %v\n%s", err, out)
-	}
-
-	// Capture startHEAD
-	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
-	if err != nil {
-		t.Fatalf("rev-parse HEAD: %v", err)
-	}
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Leave an uncommitted file in the sandbox.
-	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("autocommit me"), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug}))
-	execRecord := &storage.Execution{}
-	
-	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
-	if err != nil {
-		t.Fatalf("expected autocommit to succeed, got error: %v", err)
-	}
-
-	// Sandbox should be removed after successful autocommit and push.
-	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
-		t.Error("sandbox should have been removed after successful autocommit and push")
-	}
-
-	// Verify the commit exists in the bare repo.
-	out, err := exec.Command("git", "-C", bare, "log", "-1", "--pretty=%B").Output()
-	if err != nil {
-		t.Fatalf("git log in bare repo: %v", err)
-	}
-	if !strings.Contains(string(out), "chore: autocommit uncommitted changes") {
-		t.Errorf("expected autocommit message in log, got: %q", string(out))
-	}
-
-	// Verify the commit was captured in execRecord.
-	if len(execRecord.Commits) == 0 {
-		t.Error("expected at least one commit in execRecord")
-	} else if !strings.Contains(execRecord.Commits[0].Message, "chore: autocommit uncommitted changes") {
-		t.Errorf("unexpected commit message: %q", execRecord.Commits[0].Message)
-	}
-}
-
-func TestTeardownSandbox_BuildFailure_BlocksAutocommit(t *testing.T) {
-	bare := t.TempDir()
-	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git init bare: %v\n%s", err, out)
-	}
-
-	sandbox := t.TempDir()
-	initGitRepo(t, sandbox)
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git remote add: %v\n%s", err, out)
-	}
-
-	// Capture startHEAD
-	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
-	if err != nil {
-		t.Fatalf("rev-parse HEAD: %v", err)
-	}
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Leave an uncommitted file.
-	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("dirty"), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	// Add a failing Makefile.
-	makefile := "build:\n\t@echo 'build failed'\n\texit 1\n"
-	if err := os.WriteFile(filepath.Join(sandbox, "Makefile"), []byte(makefile), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	execRecord := &storage.Execution{}
-
-	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
-	if err == nil {
-		t.Error("expected teardown to fail due to build failure, but it succeeded")
-	} else if !strings.Contains(err.Error(), "build failed before autocommit") {
-		t.Errorf("expected build failure error message, got: %v", err)
-	}
-
-	// Sandbox should NOT be removed if teardown failed.
-	if _, statErr := os.Stat(sandbox); os.IsNotExist(statErr) {
-		t.Error("sandbox should have been preserved after build failure")
-	}
-
-	// Verify no new commit in bare repo.
-	out, err := exec.Command("git", "-C", bare, "log", "HEAD").CombinedOutput()
-	if strings.Contains(string(out), "chore: autocommit uncommitted changes") {
-		t.Error("autocommit should not have been pushed after build failure")
-	}
-}
-
-func TestTeardownSandbox_BuildSuccess_ProceedsToAutocommit(t *testing.T) {
-	bare := t.TempDir()
-	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git init bare: %v\n%s", err, out)
-	}
-
-	sandbox := t.TempDir()
-	initGitRepo(t, sandbox)
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git remote add: %v\n%s", err, out)
-	}
-
-	// Capture startHEAD
-	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
-	if err != nil {
-		t.Fatalf("rev-parse HEAD: %v", err)
-	}
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Leave an uncommitted file.
-	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("dirty"), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	// Add a successful Makefile.
-	makefile := "build:\n\t@echo 'build succeeded'\n"
-	if err := os.WriteFile(filepath.Join(sandbox, "Makefile"), []byte(makefile), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	execRecord := &storage.Execution{}
-
-	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
-	if err != nil {
-		t.Fatalf("expected teardown to succeed after build success, got error: %v", err)
-	}
-
-	// Sandbox should be removed after success.
-	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
-		t.Error("sandbox should have been removed after successful build and autocommit")
-	}
-
-	// Verify new commit in bare repo.
-	out, err := exec.Command("git", "-C", bare, "log", "-1", "--pretty=%B").Output()
-	if err != nil {
-		t.Fatalf("git log in bare repo: %v", err)
-	}
-	if !strings.Contains(string(out), "chore: autocommit uncommitted changes") {
-		t.Errorf("expected autocommit message in log, got: %q", string(out))
-	}
-}
-
-
-func TestTeardownSandbox_CapturesExplicitCommits(t *testing.T) {
-	bare := t.TempDir()
-	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git init bare: %v\n%s", err, out)
-	}
-
-	sandbox := t.TempDir()
-	initGitRepo(t, sandbox)
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git remote add: %v\n%s", err, out)
-	}
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "push", "origin", "main").CombinedOutput(); err != nil {
-		t.Fatalf("git push initial: %v\n%s", err, out)
-	}
-
-	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
-	if err != nil {
-		t.Fatalf("rev-parse HEAD: %v", err)
-	}
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Simulate Claude explicitly committing changes.
-	if err := os.WriteFile(filepath.Join(sandbox, "work.txt"), []byte("done"), 0644); err != nil {
-		t.Fatal(err)
-	}
-	for _, args := range [][]string{
-		{"-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "add", "-A"},
-		{"-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "commit", "-m", "feat: implement the feature"},
-	} {
-		if out, err := exec.Command("git", args...).CombinedOutput(); err != nil {
-			t.Fatalf("git %v: %v\n%s", args, err, out)
-		}
-	}
-
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	execRecord := &storage.Execution{}
-
-	if err := teardownSandbox("", sandbox, startHEAD, logger, execRecord); err != nil {
-		t.Fatalf("teardownSandbox: %v", err)
-	}
-
-	if len(execRecord.Commits) == 0 {
-		t.Fatal("expected commits to be captured in execRecord")
-	}
-	if !strings.Contains(execRecord.Commits[0].Message, "feat: implement the feature") {
-		t.Errorf("unexpected commit message: %q", execRecord.Commits[0].Message)
-	}
-	if execRecord.Commits[0].Hash == "" {
-		t.Error("commit hash should not be empty")
-	}
-}
-
-func TestTeardownSandbox_CleanSandboxWithNoNewCommits_RemovesSandbox(t *testing.T) {
-	src := t.TempDir()
-	initGitRepo(t, src)
-	sandbox, err := setupSandbox(src, slog.Default())
-	if err != nil {
-		t.Fatalf("setupSandbox: %v", err)
-	}
-
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	execRecord := &storage.Execution{}
-	
-	headOut, _ := exec.Command("git", "-C", sandbox, "rev-parse", "HEAD").Output()
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Sandbox has no new commits beyond origin; teardown should succeed and remove it.
-	if err := teardownSandbox(src, sandbox, startHEAD, logger, execRecord); err != nil {
-		t.Fatalf("teardownSandbox: %v", err)
-	}
-	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
-		t.Error("sandbox should have been removed after clean teardown")
-		os.RemoveAll(sandbox)
-	}
-}
-
-
-// TestClaudeRunner_Run_ResumeUsesStoredSandboxDir verifies that when a resume
-// execution has SandboxDir set, the runner uses that directory (not project_dir)
-// as the working directory, so Claude finds its session files there.
-func TestClaudeRunner_Run_ResumeUsesStoredSandboxDir(t *testing.T) {
-	logDir := t.TempDir()
-	sandboxDir := t.TempDir()
-	cwdFile := filepath.Join(logDir, "cwd.txt")
-
-	// Use a script that writes its working directory to a file in logDir (stable path).
-	scriptPath := filepath.Join(t.TempDir(), "fake-claude.sh")
-	script := "#!/bin/sh\nprintf '%s' \"$PWD\" > " + cwdFile + "\n"
-	if err := os.WriteFile(scriptPath, []byte(script), 0755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-
-	r := &ClaudeRunner{
-		BinaryPath: scriptPath,
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			ProjectDir:   sandboxDir, // must exist; resume overrides it with SandboxDir anyway
-			SkipPlanning: true,
-		},
-	}
-	exec := &storage.Execution{
-		ID:              "resume-exec-uuid",
-		TaskID:          "task-1",
-		ResumeSessionID: "original-session",
-		ResumeAnswer:    "yes",
-		SandboxDir:      sandboxDir,
-	}
-
-	_ = r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
-
-	got, err := os.ReadFile(cwdFile)
-	if err != nil {
-		t.Fatalf("cwd file not written: %v", err)
-	}
-	// The runner should have executed claude in sandboxDir, not in project_dir.
-	if string(got) != sandboxDir {
-		t.Errorf("resume working dir: want %q, got %q", sandboxDir, string(got))
-	}
-}
-
-func TestClaudeRunner_Run_StaleSandboxDir_ClonesAfresh(t *testing.T) {
-	logDir := t.TempDir()
-	projectDir := t.TempDir()
-	initGitRepo(t, projectDir)
-
-	cwdFile := filepath.Join(logDir, "cwd.txt")
-	scriptPath := filepath.Join(t.TempDir(), "fake-claude.sh")
-	script := "#!/bin/sh\nprintf '%s' \"$PWD\" > " + cwdFile + "\n"
-	if err := os.WriteFile(scriptPath, []byte(script), 0755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-
-	r := &ClaudeRunner{
-		BinaryPath: scriptPath,
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "claude",
-			ProjectDir:   projectDir,
-			SkipPlanning: true,
-		},
-	}
-	// Point to a sandbox that no longer exists (e.g. /tmp was purged).
-	staleSandbox := filepath.Join(t.TempDir(), "gone")
-	e := &storage.Execution{
-		ID:              "resume-exec-2",
-		TaskID:          "task-2",
-		ResumeSessionID: "session-abc",
-		ResumeAnswer:    "ok",
-		SandboxDir:      staleSandbox,
-	}
-
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
-		t.Fatalf("Run with stale sandbox: %v", err)
-	}
-
-	got, err := os.ReadFile(cwdFile)
-	if err != nil {
-		t.Fatalf("cwd file not written: %v", err)
-	}
-	// Should have run in a fresh sandbox (not the stale path, not the raw projectDir).
-	// The sandbox is removed after teardown, so we only check what it wasn't.
-	cwd := string(got)
-	if cwd == staleSandbox {
-		t.Error("ran in stale sandbox dir that doesn't exist")
-	}
-	if cwd == projectDir {
-		t.Error("ran directly in project_dir; expected a fresh sandbox clone")
-	}
-	// cwd should look like a claudomator sandbox path.
-	if !strings.Contains(cwd, "claudomator-sandbox-") {
-		t.Errorf("expected sandbox path, got %q", cwd)
-	}
-}
-
-func TestTailFile_MissingFile_ReturnsEmpty(t *testing.T) {
-	got := tailFile("/nonexistent/path/file.log", 10)
-	if got != "" {
-		t.Errorf("want empty string for missing file, got %q", got)
-	}
-}
-
diff --git a/internal/executor/sandbox.go b/internal/executor/sandbox.go
new file mode 100644
index 0000000..a9248d1
--- /dev/null
+++ b/internal/executor/sandbox.go
@@ -0,0 +1,187 @@
+package executor
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	"github.com/thepeterstone/claudomator/internal/storage"
+	"github.com/thepeterstone/claudomator/internal/task"
+)
+
+// sandboxCloneSource returns the URL to clone the sandbox from. It prefers a
+// remote named "local" (a local bare repo that accepts pushes cleanly), then
+// falls back to "origin", then to the working copy path itself.
+func sandboxCloneSource(projectDir string) string {
+	for _, remote := range []string{"local", "origin"} {
+		out, err := exec.Command("git", gitSafe("-C", projectDir, "remote", "get-url", remote)...).Output()
+		if err == nil {
+			u := strings.TrimSpace(string(out))
+			if u != "" && (strings.HasPrefix(u, "/") || strings.HasPrefix(u, "file://")) {
+				return u
+			}
+		}
+	}
+	return projectDir
+}
+
+// setupSandbox prepares a temporary git clone of projectDir.
+// If projectDir is not a git repo it is initialised with an initial commit first.
+func setupSandbox(projectDir string, logger *slog.Logger) (string, error) {
+	// Ensure projectDir is a git repo; initialise if not.
+	if err := exec.Command("git", gitSafe("-C", projectDir, "rev-parse", "--git-dir")...).Run(); err != nil {
+		cmds := [][]string{
+			gitSafe("-C", projectDir, "init"),
+			gitSafe("-C", projectDir, "add", "-A"),
+			gitSafe("-C", projectDir, "commit", "--allow-empty", "-m", "chore: initial commit"),
+		}
+		for _, args := range cmds {
+			if out, err := exec.Command("git", args...).CombinedOutput(); err != nil { //nolint:gosec
+				return "", fmt.Errorf("git init %s: %w\n%s", projectDir, err, out)
+			}
+		}
+	}
+
+	src := sandboxCloneSource(projectDir)
+
+	tempDir, err := os.MkdirTemp("", "claudomator-sandbox-*")
+	if err != nil {
+		return "", fmt.Errorf("creating sandbox dir: %w", err)
+	}
+	// git clone requires the target to not exist; remove the placeholder first.
+	if err := os.Remove(tempDir); err != nil {
+		return "", fmt.Errorf("removing temp dir placeholder: %w", err)
+	}
+	out, err := exec.Command("git", gitSafe("clone", "--no-hardlinks", src, tempDir)...).CombinedOutput()
+	if err != nil {
+		return "", fmt.Errorf("git clone: %w\n%s", err, out)
+	}
+	return tempDir, nil
+}
+
+// teardownSandbox verifies the sandbox is clean and pushes new commits to the
+// canonical bare repo. If the push is rejected because another task pushed
+// concurrently, it fetches and rebases then retries once.
+//
+// The working copy (projectDir) is NOT updated automatically — it is the
+// developer's workspace and is pulled manually. This avoids permission errors
+// from mixed-owner .git/objects directories.
+func teardownSandbox(projectDir, sandboxDir, startHEAD string, logger *slog.Logger, execRecord *storage.Execution) error {
+	// Automatically commit uncommitted changes.
+	out, err := exec.Command("git", "-C", sandboxDir, "status", "--porcelain").Output()
+	if err != nil {
+		return fmt.Errorf("git status: %w", err)
+	}
+	if len(strings.TrimSpace(string(out))) > 0 {
+		logger.Info("autocommitting uncommitted changes", "sandbox", sandboxDir)
+
+		// Run build before autocommitting.
+		if _, err := os.Stat(filepath.Join(sandboxDir, "Makefile")); err == nil {
+			logger.Info("running 'make build' before autocommit", "sandbox", sandboxDir)
+			if buildOut, buildErr := exec.Command("make", "-C", sandboxDir, "build").CombinedOutput(); buildErr != nil {
+				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
+			}
+		} else if _, err := os.Stat(filepath.Join(sandboxDir, "gradlew")); err == nil {
+			logger.Info("running './gradlew build' before autocommit", "sandbox", sandboxDir)
+			cmd := exec.Command("./gradlew", "build")
+			cmd.Dir = sandboxDir
+			if buildOut, buildErr := cmd.CombinedOutput(); buildErr != nil {
+				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
+			}
+		} else if _, err := os.Stat(filepath.Join(sandboxDir, "go.mod")); err == nil {
+			logger.Info("running 'go build ./...' before autocommit", "sandbox", sandboxDir)
+			cmd := exec.Command("go", "build", "./...")
+			cmd.Dir = sandboxDir
+			if buildOut, buildErr := cmd.CombinedOutput(); buildErr != nil {
+				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
+			}
+		}
+
+		cmds := [][]string{
+			gitSafe("-C", sandboxDir, "add", "-A"),
+			gitSafe("-C", sandboxDir, "commit", "-m", "chore: autocommit uncommitted changes"),
+		}
+		for _, args := range cmds {
+			if out, err := exec.Command("git", args...).CombinedOutput(); err != nil {
+				return fmt.Errorf("autocommit failed (%v): %w\n%s", args, err, out)
+			}
+		}
+	}
+
+	// Capture commits before pushing/deleting.
+	// Use startHEAD..HEAD to find all commits made during this execution.
+	logRange := "origin/HEAD..HEAD"
+	if startHEAD != "" && startHEAD != "HEAD" {
+		logRange = startHEAD + "..HEAD"
+	}
+
+	logCmd := exec.Command("git", gitSafe("-C", sandboxDir, "log", logRange, "--pretty=format:%H|%s")...)
+	logOut, logErr := logCmd.CombinedOutput()
+	if logErr == nil {
+		lines := strings.Split(strings.TrimSpace(string(logOut)), "\n")
+		logger.Debug("captured commits", "count", len(lines), "range", logRange)
+		for _, line := range lines {
+			if line == "" {
+				continue
+			}
+			parts := strings.SplitN(line, "|", 2)
+			if len(parts) == 2 {
+				execRecord.Commits = append(execRecord.Commits, task.GitCommit{
+					Hash:    parts[0],
+					Message: parts[1],
+				})
+			}
+		}
+	} else {
+		logger.Warn("failed to capture commits", "err", logErr, "range", logRange, "output", string(logOut))
+	}
+
+	// Check whether there are any new commits to push.
+	ahead, err := exec.Command("git", gitSafe("-C", sandboxDir, "rev-list", "--count", logRange)...).Output()
+	if err != nil {
+		logger.Warn("could not determine commits ahead of origin; proceeding", "err", err, "range", logRange)
+	}
+	if strings.TrimSpace(string(ahead)) == "0" {
+		os.RemoveAll(sandboxDir)
+		return nil
+	}
+
+	// Push from sandbox → bare repo (sandbox's origin is the bare repo).
+	if out, err := exec.Command("git", "-C", sandboxDir, "push", "origin", "HEAD").CombinedOutput(); err != nil {
+		// If rejected due to concurrent push, fetch+rebase and retry once.
+		if strings.Contains(string(out), "fetch first") || strings.Contains(string(out), "non-fast-forward") {
+			logger.Info("push rejected (concurrent task); rebasing and retrying", "sandbox", sandboxDir)
+			if out2, err2 := exec.Command("git", "-C", sandboxDir, "pull", "--rebase", "origin", "master").CombinedOutput(); err2 != nil {
+				return fmt.Errorf("git rebase before retry push: %w\n%s", err2, out2)
+			}
+			// Re-capture commits after rebase (hashes might have changed)
+			execRecord.Commits = nil
+			logOut, logErr = exec.Command("git", "-C", sandboxDir, "log", logRange, "--pretty=format:%H|%s").Output()
+			if logErr == nil {
+				lines := strings.Split(strings.TrimSpace(string(logOut)), "\n")
+				for _, line := range lines {
+					parts := strings.SplitN(line, "|", 2)
+					if len(parts) == 2 {
+						execRecord.Commits = append(execRecord.Commits, task.GitCommit{
+							Hash:    parts[0],
+							Message: parts[1],
+						})
+					}
+				}
+			}
+
+			if out3, err3 := exec.Command("git", "-C", sandboxDir, "push", "origin", "HEAD").CombinedOutput(); err3 != nil {
+				return fmt.Errorf("git push to origin (after rebase): %w\n%s", err3, out3)
+			}
+		} else {
+			return fmt.Errorf("git push to origin: %w\n%s", err, out)
+		}
+	}
+
+	logger.Info("sandbox pushed to bare repo", "sandbox", sandboxDir)
+	os.RemoveAll(sandboxDir)
+	return nil
+}
diff --git a/internal/executor/sandbox_test.go b/internal/executor/sandbox_test.go
new file mode 100644
index 0000000..4893263
--- /dev/null
+++ b/internal/executor/sandbox_test.go
@@ -0,0 +1,366 @@
+package executor
+
+import (
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/thepeterstone/claudomator/internal/storage"
+)
+
+func TestSandboxCloneSource_PrefersLocalRemote(t *testing.T) {
+	dir := t.TempDir()
+	initGitRepo(t, dir)
+	// Add a "local" remote pointing to a bare repo.
+	bare := t.TempDir()
+	exec.Command("git", "init", "--bare", bare).Run()
+	exec.Command("git", "-C", dir, "remote", "add", "local", bare).Run()
+	exec.Command("git", "-C", dir, "remote", "add", "origin", "https://example.com/repo").Run()
+
+	got := sandboxCloneSource(dir)
+	if got != bare {
+		t.Errorf("expected bare repo path %q, got %q", bare, got)
+	}
+}
+
+func TestSandboxCloneSource_FallsBackToOrigin(t *testing.T) {
+	dir := t.TempDir()
+	initGitRepo(t, dir)
+	// sandboxCloneSource intentionally filters to local-FS remotes (so
+	// `git clone <src>` doesn't go over the network). Use a local path
+	// for origin to verify the fallback semantics.
+	originURL := t.TempDir()
+	exec.Command("git", "-C", dir, "remote", "add", "origin", originURL).Run()
+
+	got := sandboxCloneSource(dir)
+	if got != originURL {
+		t.Errorf("expected origin URL %q, got %q", originURL, got)
+	}
+}
+
+func TestSandboxCloneSource_FallsBackToProjectDir(t *testing.T) {
+	dir := t.TempDir()
+	initGitRepo(t, dir)
+	// No remotes configured.
+	got := sandboxCloneSource(dir)
+	if got != dir {
+		t.Errorf("expected projectDir %q (no remotes), got %q", dir, got)
+	}
+}
+
+func TestSetupSandbox_ClonesGitRepo(t *testing.T) {
+	src := t.TempDir()
+	initGitRepo(t, src)
+
+	sandbox, err := setupSandbox(src, slog.Default())
+	if err != nil {
+		t.Fatalf("setupSandbox: %v", err)
+	}
+	t.Cleanup(func() { os.RemoveAll(sandbox) })
+
+	// Force sandbox to master if it cloned as main
+	exec.Command("git", gitSafe("-C", sandbox, "checkout", "master")...).Run()
+
+	// Debug sandbox
+	logOut, _ := exec.Command("git", "-C", sandbox, "log", "-1").CombinedOutput()
+	fmt.Printf("DEBUG: sandbox log: %s\n", string(logOut))
+
+	// Verify sandbox is a git repo with at least one commit.
+	out, err := exec.Command("git", "-C", sandbox, "log", "--oneline").Output()
+	if err != nil {
+		t.Fatalf("git log in sandbox: %v", err)
+	}
+	if len(strings.TrimSpace(string(out))) == 0 {
+		t.Error("expected at least one commit in sandbox, got empty log")
+	}
+}
+
+func TestSetupSandbox_InitialisesNonGitDir(t *testing.T) {
+	// A plain directory (not a git repo) should be initialised then cloned.
+	src := t.TempDir()
+
+	sandbox, err := setupSandbox(src, slog.Default())
+	if err != nil {
+		t.Fatalf("setupSandbox on plain dir: %v", err)
+	}
+	t.Cleanup(func() { os.RemoveAll(sandbox) })
+
+	if _, err := os.Stat(filepath.Join(sandbox, ".git")); err != nil {
+		t.Errorf("sandbox should be a git repo: %v", err)
+	}
+}
+
+func TestTeardownSandbox_AutocommitsChanges(t *testing.T) {
+	// Create a bare repo as origin so push succeeds.
+	bare := t.TempDir()
+	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
+		t.Fatalf("git init bare: %v\n%s", err, out)
+	}
+
+	// Create a sandbox directly.
+	sandbox := t.TempDir()
+	initGitRepo(t, sandbox)
+	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
+		t.Fatalf("git remote add: %v\n%s", err, out)
+	}
+	// Initial push to establish origin/main
+	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "push", "origin", "main").CombinedOutput(); err != nil {
+		t.Fatalf("git push initial: %v\n%s", err, out)
+	}
+
+	// Capture startHEAD
+	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
+	if err != nil {
+		t.Fatalf("rev-parse HEAD: %v", err)
+	}
+	startHEAD := strings.TrimSpace(string(headOut))
+
+	// Leave an uncommitted file in the sandbox.
+	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("autocommit me"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug}))
+	execRecord := &storage.Execution{}
+
+	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
+	if err != nil {
+		t.Fatalf("expected autocommit to succeed, got error: %v", err)
+	}
+
+	// Sandbox should be removed after successful autocommit and push.
+	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
+		t.Error("sandbox should have been removed after successful autocommit and push")
+	}
+
+	// Verify the commit exists in the bare repo.
+	out, err := exec.Command("git", "-C", bare, "log", "-1", "--pretty=%B").Output()
+	if err != nil {
+		t.Fatalf("git log in bare repo: %v", err)
+	}
+	if !strings.Contains(string(out), "chore: autocommit uncommitted changes") {
+		t.Errorf("expected autocommit message in log, got: %q", string(out))
+	}
+
+	// Verify the commit was captured in execRecord.
+	if len(execRecord.Commits) == 0 {
+		t.Error("expected at least one commit in execRecord")
+	} else if !strings.Contains(execRecord.Commits[0].Message, "chore: autocommit uncommitted changes") {
+		t.Errorf("unexpected commit message: %q", execRecord.Commits[0].Message)
+	}
+}
+
+func TestTeardownSandbox_BuildFailure_BlocksAutocommit(t *testing.T) {
+	bare := t.TempDir()
+	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
+		t.Fatalf("git init bare: %v\n%s", err, out)
+	}
+
+	sandbox := t.TempDir()
+	initGitRepo(t, sandbox)
+	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
+		t.Fatalf("git remote add: %v\n%s", err, out)
+	}
+
+	// Capture startHEAD
+	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
+	if err != nil {
+		t.Fatalf("rev-parse HEAD: %v", err)
+	}
+	startHEAD := strings.TrimSpace(string(headOut))
+
+	// Leave an uncommitted file.
+	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("dirty"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Add a failing Makefile.
+	makefile := "build:\n\t@echo 'build failed'\n\texit 1\n"
+	if err := os.WriteFile(filepath.Join(sandbox, "Makefile"), []byte(makefile), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	execRecord := &storage.Execution{}
+
+	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
+	if err == nil {
+		t.Error("expected teardown to fail due to build failure, but it succeeded")
+	} else if !strings.Contains(err.Error(), "build failed before autocommit") {
+		t.Errorf("expected build failure error message, got: %v", err)
+	}
+
+	// Sandbox should NOT be removed if teardown failed.
+	if _, statErr := os.Stat(sandbox); os.IsNotExist(statErr) {
+		t.Error("sandbox should have been preserved after build failure")
+	}
+
+	// Verify no new commit in bare repo.
+	out, err := exec.Command("git", "-C", bare, "log", "HEAD").CombinedOutput()
+	if strings.Contains(string(out), "chore: autocommit uncommitted changes") {
+		t.Error("autocommit should not have been pushed after build failure")
+	}
+}
+
+func TestTeardownSandbox_BuildSuccess_ProceedsToAutocommit(t *testing.T) {
+	bare := t.TempDir()
+	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
+		t.Fatalf("git init bare: %v\n%s", err, out)
+	}
+
+	sandbox := t.TempDir()
+	initGitRepo(t, sandbox)
+	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
+		t.Fatalf("git remote add: %v\n%s", err, out)
+	}
+
+	// Capture startHEAD
+	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
+	if err != nil {
+		t.Fatalf("rev-parse HEAD: %v", err)
+	}
+	startHEAD := strings.TrimSpace(string(headOut))
+
+	// Leave an uncommitted file.
+	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("dirty"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Add a successful Makefile.
+	makefile := "build:\n\t@echo 'build succeeded'\n"
+	if err := os.WriteFile(filepath.Join(sandbox, "Makefile"), []byte(makefile), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	execRecord := &storage.Execution{}
+
+	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
+	if err != nil {
+		t.Fatalf("expected teardown to succeed after build success, got error: %v", err)
+	}
+
+	// Sandbox should be removed after success.
+	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
+		t.Error("sandbox should have been removed after successful build and autocommit")
+	}
+
+	// Verify new commit in bare repo.
+	out, err := exec.Command("git", "-C", bare, "log", "-1", "--pretty=%B").Output()
+	if err != nil {
+		t.Fatalf("git log in bare repo: %v", err)
+	}
+	if !strings.Contains(string(out), "chore: autocommit uncommitted changes") {
+		t.Errorf("expected autocommit message in log, got: %q", string(out))
+	}
+}
+
+func TestTeardownSandbox_CapturesExplicitCommits(t *testing.T) {
+	bare := t.TempDir()
+	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
+		t.Fatalf("git init bare: %v\n%s", err, out)
+	}
+
+	sandbox := t.TempDir()
+	initGitRepo(t, sandbox)
+	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
+		t.Fatalf("git remote add: %v\n%s", err, out)
+	}
+	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "push", "origin", "main").CombinedOutput(); err != nil {
+		t.Fatalf("git push initial: %v\n%s", err, out)
+	}
+
+	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
+	if err != nil {
+		t.Fatalf("rev-parse HEAD: %v", err)
+	}
+	startHEAD := strings.TrimSpace(string(headOut))
+
+	// Simulate Claude explicitly committing changes.
+	if err := os.WriteFile(filepath.Join(sandbox, "work.txt"), []byte("done"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	for _, args := range [][]string{
+		{"-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "add", "-A"},
+		{"-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "commit", "-m", "feat: implement the feature"},
+	} {
+		if out, err := exec.Command("git", args...).CombinedOutput(); err != nil {
+			t.Fatalf("git %v: %v\n%s", args, err, out)
+		}
+	}
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	execRecord := &storage.Execution{}
+
+	if err := teardownSandbox("", sandbox, startHEAD, logger, execRecord); err != nil {
+		t.Fatalf("teardownSandbox: %v", err)
+	}
+
+	if len(execRecord.Commits) == 0 {
+		t.Fatal("expected commits to be captured in execRecord")
+	}
+	if !strings.Contains(execRecord.Commits[0].Message, "feat: implement the feature") {
+		t.Errorf("unexpected commit message: %q", execRecord.Commits[0].Message)
+	}
+	if execRecord.Commits[0].Hash == "" {
+		t.Error("commit hash should not be empty")
+	}
+}
+
+func TestTeardownSandbox_CleanSandboxWithNoNewCommits_RemovesSandbox(t *testing.T) {
+	src := t.TempDir()
+	initGitRepo(t, src)
+	sandbox, err := setupSandbox(src, slog.Default())
+	if err != nil {
+		t.Fatalf("setupSandbox: %v", err)
+	}
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	execRecord := &storage.Execution{}
+
+	headOut, _ := exec.Command("git", "-C", sandbox, "rev-parse", "HEAD").Output()
+	startHEAD := strings.TrimSpace(string(headOut))
+
+	// Sandbox has no new commits beyond origin; teardown should succeed and remove it.
+	if err := teardownSandbox(src, sandbox, startHEAD, logger, execRecord); err != nil {
+		t.Fatalf("teardownSandbox: %v", err)
+	}
+	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
+		t.Error("sandbox should have been removed after clean teardown")
+		os.RemoveAll(sandbox)
+	}
+}
+func TestTailFile_MissingFile_ReturnsEmpty(t *testing.T) {
+	got := tailFile("/nonexistent/path/file.log", 10)
+	if got != "" {
+		t.Errorf("want empty string for missing file, got %q", got)
+	}
+}
+
+func initGitRepo(t *testing.T, dir string) {
+	t.Helper()
+	cmds := [][]string{
+		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "init", "-b", "main"},
+		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "config", "user.email", "test@test"},
+		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "config", "user.name", "test"},
+	}
+	for _, args := range cmds {
+		if out, err := exec.Command(args[0], args[1:]...).CombinedOutput(); err != nil {
+			t.Fatalf("%v: %v\n%s", args, err, out)
+		}
+	}
+	if err := os.WriteFile(filepath.Join(dir, "init.txt"), []byte("init"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "add", ".").CombinedOutput(); err != nil {
+		t.Fatalf("git add: %v\n%s", err, out)
+	}
+	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "commit", "-m", "init").CombinedOutput(); err != nil {
+		t.Fatalf("git commit: %v\n%s", err, out)
+	}
+}
-- 
cgit v1.2.3


From c0fabf5a2f4ca371403571b82e29c5073bed24fb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 25 May 2026 18:59:06 +0000
Subject: refactor(executor): delete the dead GeminiRunner stub and its sandbox
 helpers (Phase 4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The production "gemini" agent type is served by ContainerRunner (Docker), not by
the standalone subprocess GeminiRunner, which was never wired into serve.go and
returned canned/simulated output — the dangerous landmine called out in
CLAUDE.md's design debt. Removing it (gemini.go + tests).

The subprocess sandbox helpers (setupSandbox/teardownSandbox/sandboxCloneSource
in sandbox.go), preserved in Phase 2 only because GeminiRunner used them, are now
orphaned — ContainerRunner has its own git/workspace handling — so they go too.

No production behavior change: nothing instantiated GeminiRunner. Build green;
executor tests unchanged except the pre-existing git commit-signing failures.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/executor/gemini.go       | 346 -----------------------------
 internal/executor/gemini_test.go  | 447 --------------------------------------
 internal/executor/sandbox.go      | 187 ----------------
 internal/executor/sandbox_test.go | 366 -------------------------------
 4 files changed, 1346 deletions(-)
 delete mode 100644 internal/executor/gemini.go
 delete mode 100644 internal/executor/gemini_test.go
 delete mode 100644 internal/executor/sandbox.go
 delete mode 100644 internal/executor/sandbox_test.go

(limited to 'internal/executor')

diff --git a/internal/executor/gemini.go b/internal/executor/gemini.go
deleted file mode 100644
index d229361..0000000
--- a/internal/executor/gemini.go
+++ /dev/null
@@ -1,346 +0,0 @@
-package executor
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"log/slog"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-	"sync"
-	"syscall"
-
-	"github.com/thepeterstone/claudomator/internal/storage"
-	"github.com/thepeterstone/claudomator/internal/task"
-)
-
-// GeminiRunner spawns the `gemini` CLI in non-interactive mode.
-type GeminiRunner struct {
-	BinaryPath string // defaults to "gemini"
-	Logger     *slog.Logger
-	LogDir     string // base directory for execution logs
-	APIURL     string // base URL of the Claudomator API, passed to subprocesses
-}
-
-// ExecLogDir returns the log directory for the given execution ID.
-func (r *GeminiRunner) ExecLogDir(execID string) string {
-	if r.LogDir == "" {
-		return ""
-	}
-	return filepath.Join(r.LogDir, execID)
-}
-
-func (r *GeminiRunner) binaryPath() string {
-	if r.BinaryPath != "" {
-		return r.BinaryPath
-	}
-	return "gemini"
-}
-
-// Run executes the gemini CLI inside a sandboxed clone of project_dir.
-// When project_dir is set, claudomator first clones it into a temp sandbox
-// (preferring a `local` bare remote, then `origin`, then the working tree)
-// and runs the agent there. On success the sandbox is autocommitted and
-// pushed back to origin/master, then removed. On failure the sandbox is
-// preserved and its path is included in the returned error so the user can
-// inspect partial work. If the agent writes a question file before exiting,
-// Run returns *BlockedError with SandboxDir populated so a resume execution
-// can pick up in the same directory.
-func (r *GeminiRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, ch AgentChannel) error {
-	projectDir := t.Agent.ProjectDir
-
-	if projectDir != "" {
-		if _, err := os.Stat(projectDir); err != nil {
-			return fmt.Errorf("project_dir %q: %w", projectDir, err)
-		}
-	}
-
-	logDir := r.ExecLogDir(e.ID)
-	if logDir == "" {
-		logDir = e.ID
-	}
-	if err := os.MkdirAll(logDir, 0700); err != nil {
-		return fmt.Errorf("creating log dir: %w", err)
-	}
-
-	if e.StdoutPath == "" {
-		e.StdoutPath = filepath.Join(logDir, "stdout.log")
-		e.StderrPath = filepath.Join(logDir, "stderr.log")
-		e.ArtifactDir = logDir
-	}
-
-	if e.SessionID == "" {
-		if e.ResumeSessionID != "" {
-			e.SessionID = e.ResumeSessionID
-		} else {
-			e.SessionID = e.ID
-		}
-	}
-
-	// Sandbox setup: for new executions with a project_dir, clone into a sandbox.
-	// Resume executions reuse the preserved sandbox so any partial work survives.
-	// If the preserved sandbox is missing (e.g. /tmp was purged), clone fresh.
-	var sandboxDir string
-	var startHEAD string
-	effectiveWorkingDir := projectDir
-	if e.ResumeSessionID != "" {
-		if e.SandboxDir != "" {
-			if _, statErr := os.Stat(e.SandboxDir); statErr == nil {
-				effectiveWorkingDir = e.SandboxDir
-			} else {
-				r.Logger.Warn("preserved sandbox missing, cloning fresh", "sandbox", e.SandboxDir, "project_dir", projectDir)
-				e.SandboxDir = ""
-				if projectDir != "" {
-					var err error
-					sandboxDir, err = setupSandbox(projectDir, r.Logger)
-					if err != nil {
-						return fmt.Errorf("setting up sandbox: %w", err)
-					}
-					effectiveWorkingDir = sandboxDir
-					r.Logger.Info("fresh sandbox created for resume", "sandbox", sandboxDir, "project_dir", projectDir)
-				}
-			}
-		}
-	} else if projectDir != "" {
-		var err error
-		sandboxDir, err = setupSandbox(projectDir, r.Logger)
-		if err != nil {
-			return fmt.Errorf("setting up sandbox: %w", err)
-		}
-		effectiveWorkingDir = sandboxDir
-		r.Logger.Info("sandbox created", "sandbox", sandboxDir, "project_dir", projectDir)
-	}
-
-	if effectiveWorkingDir != "" {
-		headOut, _ := exec.Command("git", gitSafe("-C", effectiveWorkingDir, "rev-parse", "HEAD")...).Output()
-		startHEAD = strings.TrimSpace(string(headOut))
-	}
-
-	questionFile := filepath.Join(logDir, "question.json")
-	args := r.buildArgs(t, e, questionFile)
-
-	if err := r.execOnce(ctx, args, effectiveWorkingDir, projectDir, e); err != nil {
-		if sandboxDir != "" {
-			return fmt.Errorf("%w (sandbox preserved at %s)", err, sandboxDir)
-		}
-		return err
-	}
-
-	// Check whether the agent left a question before exiting.
-	data, readErr := os.ReadFile(questionFile)
-	if readErr == nil {
-		os.Remove(questionFile)
-		questionJSON := strings.TrimSpace(string(data))
-		if isCompletionReport(questionJSON) {
-			r.Logger.Info("treating question file as completion report", "taskID", e.TaskID)
-			_ = ch.ReportSummary(ctx, extractQuestionText(questionJSON))
-		} else {
-			// Preserve sandbox on BLOCKED so a resume can pick up in the same dir.
-			return &BlockedError{QuestionJSON: questionJSON, SessionID: e.SessionID, SandboxDir: sandboxDir}
-		}
-	}
-
-	// Read agent summary if written.
-	summaryFile := filepath.Join(logDir, "summary.txt")
-	if summaryData, readErr := os.ReadFile(summaryFile); readErr == nil {
-		os.Remove(summaryFile)
-		_ = ch.ReportSummary(ctx, strings.TrimSpace(string(summaryData)))
-	}
-
-	// Merge sandbox back to project_dir and clean up.
-	if sandboxDir != "" {
-		if mergeErr := teardownSandbox(projectDir, sandboxDir, startHEAD, r.Logger, e); mergeErr != nil {
-			return fmt.Errorf("sandbox teardown: %w (sandbox preserved at %s)", mergeErr, sandboxDir)
-		}
-	}
-	return nil
-}
-
-func (r *GeminiRunner) execOnce(ctx context.Context, args []string, workingDir, projectDir string, e *storage.Execution) error {
-	cmd := exec.CommandContext(ctx, r.binaryPath(), args...)
-	cmd.Env = append(os.Environ(),
-		"CLAUDOMATOR_API_URL="+r.APIURL,
-		"CLAUDOMATOR_TASK_ID="+e.TaskID,
-		"CLAUDOMATOR_PROJECT_DIR="+projectDir,
-		"CLAUDOMATOR_QUESTION_FILE="+filepath.Join(e.ArtifactDir, "question.json"),
-		"CLAUDOMATOR_SUMMARY_FILE="+filepath.Join(e.ArtifactDir, "summary.txt"),
-	)
-	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
-	if workingDir != "" {
-		cmd.Dir = workingDir
-	}
-
-	stdoutFile, err := os.Create(e.StdoutPath)
-	if err != nil {
-		return fmt.Errorf("creating stdout log: %w", err)
-	}
-	defer stdoutFile.Close()
-
-	stderrFile, err := os.Create(e.StderrPath)
-	if err != nil {
-		return fmt.Errorf("creating stderr log: %w", err)
-	}
-	defer stderrFile.Close()
-
-	stdoutR, stdoutW, err := os.Pipe()
-	if err != nil {
-		return fmt.Errorf("creating stdout pipe: %w", err)
-	}
-	cmd.Stdout = stdoutW
-	cmd.Stderr = stderrFile
-
-	if err := cmd.Start(); err != nil {
-		stdoutW.Close()
-		stdoutR.Close()
-		return fmt.Errorf("starting gemini: %w", err)
-	}
-	stdoutW.Close()
-
-	killDone := make(chan struct{})
-	go func() {
-		select {
-		case <-ctx.Done():
-			syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
-		case <-killDone:
-		}
-	}()
-
-	var streamCost float64
-	var streamErr error
-	var wg sync.WaitGroup
-	wg.Add(1)
-	go func() {
-		defer wg.Done()
-		streamCost, streamErr = parseGeminiStream(stdoutR, stdoutFile, r.Logger)
-		stdoutR.Close()
-	}()
-
-	waitErr := cmd.Wait()
-	close(killDone)
-	wg.Wait()
-
-	if streamCost > 0 {
-		e.CostUSD = streamCost
-	}
-
-	if waitErr != nil {
-		if exitErr, ok := waitErr.(*exec.ExitError); ok {
-			e.ExitCode = exitErr.ExitCode()
-		}
-		if streamErr != nil {
-			return streamErr
-		}
-		if tail := tailFile(e.StderrPath, 20); tail != "" {
-			return fmt.Errorf("gemini exited with error: %w\nstderr:\n%s", waitErr, tail)
-		}
-		return fmt.Errorf("gemini exited with error: %w", waitErr)
-	}
-
-	if streamErr != nil {
-		return streamErr
-	}
-	return nil
-}
-
-// parseGeminiStream reads streaming JSON from the gemini CLI, strips markdown
-// code fences if the output is wrapped in them, writes the inner stream-json
-// to w, and returns (costUSD, error). If a `result` event has `is_error: true`,
-// an error wrapping the result message is returned.
-func parseGeminiStream(r io.Reader, w io.Writer, logger *slog.Logger) (float64, error) {
-	fullOutput, err := io.ReadAll(r)
-	if err != nil {
-		return 0, fmt.Errorf("reading full gemini output: %w", err)
-	}
-	logger.Debug("parseGeminiStream: raw output received", "output", string(fullOutput))
-
-	inner := stripGeminiFences(string(fullOutput), logger)
-	if _, writeErr := w.Write([]byte(inner)); writeErr != nil {
-		return 0, fmt.Errorf("writing gemini output: %w", writeErr)
-	}
-
-	// Walk lines looking for a result event so we can surface errors and cost.
-	var (
-		cost    float64
-		errMsg  string
-		isError bool
-	)
-	for _, raw := range strings.Split(inner, "\n") {
-		line := strings.TrimSpace(raw)
-		if line == "" {
-			continue
-		}
-		var evt struct {
-			Type    string  `json:"type"`
-			IsError bool    `json:"is_error"`
-			Result  string  `json:"result"`
-			Cost    float64 `json:"total_cost_usd"`
-		}
-		if err := json.Unmarshal([]byte(line), &evt); err != nil {
-			continue
-		}
-		if evt.Type == "result" {
-			if evt.Cost > 0 {
-				cost = evt.Cost
-			}
-			if evt.IsError {
-				isError = true
-				errMsg = evt.Result
-			}
-		}
-	}
-	if isError {
-		return cost, fmt.Errorf("gemini reported error: %s", errMsg)
-	}
-	return cost, nil
-}
-
-// stripGeminiFences removes a surrounding ```json ... ``` markdown block if
-// present, returning the trimmed inner content. If no markdown fence is
-// found, the input is returned verbatim (no whitespace trimming) so callers
-// that expect byte-exact pass-through behavior get it.
-func stripGeminiFences(raw string, logger *slog.Logger) string {
-	trimmed := strings.TrimSpace(raw)
-	if start := strings.Index(trimmed, "```json"); start != -1 {
-		if end := strings.LastIndex(trimmed, "```"); end > start {
-			return strings.TrimSpace(trimmed[start+len("```json") : end])
-		}
-		logger.Warn("malformed gemini markdown block (missing closing fence); using raw output", "len", len(trimmed))
-		return trimmed
-	}
-	return raw
-}
-
-func (r *GeminiRunner) buildArgs(t *task.Task, e *storage.Execution, questionFile string) []string {
-	// Gemini CLI uses a different command structure: gemini "instructions" [flags]
-	
-	instructions := t.Agent.Instructions
-	if !t.Agent.SkipPlanning {
-		instructions = withPlanningPreamble(instructions)
-	}
-
-	args := []string{
-		"-p", instructions,
-		"--output-format", "stream-json",
-		"--yolo", // auto-approve all tools (equivalent to Claude's bypassPermissions)
-	}
-
-	// Note: Gemini CLI flags might differ from Claude CLI.
-	// Assuming common flags for now, but these may need adjustment.
-	if t.Agent.Model != "" {
-		args = append(args, "--model", t.Agent.Model)
-	}
-	
-	// Gemini CLI doesn't use --session-id for the first run in the same way,
-	// or it might use it differently. For now we assume compatibility.
-	if e.SessionID != "" {
-		// If it's a resume, it might use different flags.
-		if e.ResumeSessionID != "" {
-			// This is a placeholder for Gemini's resume logic
-		}
-	}
-
-	return args
-}
diff --git a/internal/executor/gemini_test.go b/internal/executor/gemini_test.go
deleted file mode 100644
index a906f2c..0000000
--- a/internal/executor/gemini_test.go
+++ /dev/null
@@ -1,447 +0,0 @@
-package executor
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"io"
-	"log/slog"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/thepeterstone/claudomator/internal/storage"
-	"github.com/thepeterstone/claudomator/internal/task"
-)
-
-func TestGeminiRunner_BuildArgs_BasicTask(t *testing.T) {
-	r := &GeminiRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			Instructions: "fix the bug",
-			Model:        "gemini-2.5-flash-lite",
-			SkipPlanning: true,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	// Gemini CLI: instructions passed via -p for non-interactive mode
-	if len(args) < 2 || args[0] != "-p" || args[1] != "fix the bug" {
-		t.Errorf("expected -p <instructions> as first args, got: %v", args)
-	}
-
-	argMap := make(map[string]bool)
-	for _, a := range args {
-		argMap[a] = true
-	}
-	for _, want := range []string{"--output-format", "stream-json", "--model", "gemini-2.5-flash-lite"} {
-		if !argMap[want] {
-			t.Errorf("missing arg %q in %v", want, args)
-		}
-	}
-}
-
-func TestGeminiRunner_BuildArgs_PreamblePrepended(t *testing.T) {
-	r := &GeminiRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			Instructions: "fix the bug",
-			SkipPlanning: false,
-		},
-	}
-
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-
-	if len(args) < 2 || args[0] != "-p" {
-		t.Fatalf("expected -p <instructions> as first args, got: %v", args)
-	}
-	if !strings.HasPrefix(args[1], planningPreamble) {
-		t.Errorf("instructions should start with planning preamble")
-	}
-	if !strings.HasSuffix(args[1], "fix the bug") {
-		t.Errorf("instructions should end with original instructions")
-	}
-}
-
-func TestGeminiRunner_BuildArgs_IncludesYolo(t *testing.T) {
-	r := &GeminiRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			Instructions: "write a doc",
-			SkipPlanning: true,
-		},
-	}
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-	argMap := make(map[string]bool)
-	for _, a := range args {
-		argMap[a] = true
-	}
-	if !argMap["--yolo"] {
-		t.Errorf("expected --yolo in gemini args (enables all tools); got: %v", args)
-	}
-}
-
-func TestGeminiRunner_BuildArgs_IncludesPromptFlag(t *testing.T) {
-	r := &GeminiRunner{}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			Instructions: "do the thing",
-			SkipPlanning: true,
-		},
-	}
-	args := r.buildArgs(tk, &storage.Execution{ID: "test-exec"}, "/tmp/q.json")
-	// Instructions must be passed via -p/--prompt for non-interactive headless mode,
-	// not as a bare positional (which starts interactive mode).
-	found := false
-	for i, a := range args {
-		if (a == "-p" || a == "--prompt") && i+1 < len(args) && args[i+1] == "do the thing" {
-			found = true
-			break
-		}
-	}
-	if !found {
-		t.Errorf("expected instructions passed via -p/--prompt flag; got: %v", args)
-	}
-}
-
-func TestGeminiRunner_Run_InaccessibleProjectDir_ReturnsError(t *testing.T) {
-	r := &GeminiRunner{
-		BinaryPath: "true", // would succeed if it ran
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     t.TempDir(),
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			ProjectDir:   "/nonexistent/path/does/not/exist",
-			SkipPlanning: true,
-		},
-	}
-	exec := &storage.Execution{ID: "test-exec"}
-
-	err := r.Run(context.Background(), tk, exec, newStoreChannel(nil, tk.ID))
-
-	if err == nil {
-		t.Fatal("expected error for inaccessible project_dir, got nil")
-	}
-	if !strings.Contains(err.Error(), "project_dir") {
-		t.Errorf("expected 'project_dir' in error, got: %v", err)
-	}
-}
-
-func TestGeminiRunner_BinaryPath_Default(t *testing.T) {
-	r := &GeminiRunner{}
-	if r.binaryPath() != "gemini" {
-		t.Errorf("want 'gemini', got %q", r.binaryPath())
-	}
-}
-
-func TestGeminiRunner_BinaryPath_Custom(t *testing.T) {
-	r := &GeminiRunner{BinaryPath: "/usr/local/bin/gemini"}
-	if r.binaryPath() != "/usr/local/bin/gemini" {
-		t.Errorf("want custom path, got %q", r.binaryPath())
-	}
-}
-
-
-func TestParseGeminiStream_ParsesStructuredOutput(t *testing.T) {
-	// Simulate a stream-json input with various message types, including a result with error and cost.
-	input := streamLine(`{"type":"content_block_start","content_block":{"text":"Hello,"}}`) +
-		streamLine(`{"type":"content_block_delta","content_block":{"text":" World!"}}`) +
-		streamLine(`{"type":"content_block_end"}`) +
-		streamLine(`{"type":"result","subtype":"error_during_execution","is_error":true,"result":"something went wrong","total_cost_usd":0.123}`)
-
-	reader := strings.NewReader(input)
-	var writer bytes.Buffer // To capture what's written to the output log
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-
-	cost, err := parseGeminiStream(reader, &writer, logger)
-
-	if err == nil {
-		t.Errorf("expected an error, got nil")
-	}
-	if !strings.Contains(err.Error(), "something went wrong") {
-		t.Errorf("expected error message to contain 'something went wrong', got: %v", err)
-	}
-
-	if cost != 0.123 {
-		t.Errorf("expected cost 0.123, got %f", cost)
-	}
-
-	// Verify that the writer received the content (even if parseGeminiStream isn't fully parsing it yet)
-	expectedWriterContent := input
-	if writer.String() != expectedWriterContent {
-		t.Errorf("writer content mismatch:\nwant:\n%s\ngot:\n%s", expectedWriterContent, writer.String())
-	}
-}
-
-// TestGeminiRunner_Run_ProjectDir_RunsInSandbox verifies that when project_dir
-// is set, the gemini subprocess runs inside a sandbox clone — not in
-// project_dir itself.
-func TestGeminiRunner_Run_ProjectDir_RunsInSandbox(t *testing.T) {
-	projectDir := t.TempDir()
-	initGitRepo(t, projectDir)
-
-	logDir := t.TempDir()
-	cwdFile := filepath.Join(logDir, "gemini-cwd.txt")
-
-	// Fake gemini binary that records its $PWD then exits 0.
-	scriptPath := filepath.Join(t.TempDir(), "fake-gemini.sh")
-	script := "#!/bin/sh\nprintf '%s' \"$PWD\" > " + cwdFile + "\n"
-	if err := os.WriteFile(scriptPath, []byte(script), 0755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-
-	r := &GeminiRunner{
-		BinaryPath: scriptPath,
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			Instructions: "do work",
-			ProjectDir:   projectDir,
-			SkipPlanning: true,
-		},
-	}
-	e := &storage.Execution{ID: "sandbox-exec", TaskID: "task-1"}
-
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
-		t.Fatalf("Run: %v", err)
-	}
-
-	got, err := os.ReadFile(cwdFile)
-	if err != nil {
-		t.Fatalf("cwd file not written: %v", err)
-	}
-	cwd := string(got)
-	if cwd == projectDir {
-		t.Errorf("ran directly in project_dir; expected sandbox clone (cwd=%q)", cwd)
-	}
-	// Sandbox should be removed after successful teardown (no edits → nothing to push).
-	// We can't assert the exact dir, but it should not be projectDir.
-}
-
-// TestGeminiRunner_Run_BlockedError_IncludesSandboxDir verifies that when the
-// agent writes a question file before exiting, the BlockedError carries the
-// sandbox path so resume runs in the same dir.
-func TestGeminiRunner_Run_BlockedError_IncludesSandboxDir(t *testing.T) {
-	src := t.TempDir()
-	initGitRepo(t, src)
-	logDir := t.TempDir()
-
-	scriptPath := filepath.Join(t.TempDir(), "fake-gemini.sh")
-	if err := os.WriteFile(scriptPath, []byte(`#!/bin/sh
-if [ -n "$CLAUDOMATOR_QUESTION_FILE" ]; then
-  printf '{"text":"Should I continue?"}' > "$CLAUDOMATOR_QUESTION_FILE"
-fi
-`), 0755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-
-	r := &GeminiRunner{
-		BinaryPath: scriptPath,
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			Instructions: "do something",
-			ProjectDir:   src,
-			SkipPlanning: true,
-		},
-	}
-	e := &storage.Execution{ID: "blocked-gemini-exec", TaskID: "task-1"}
-
-	err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
-
-	var blocked *BlockedError
-	if !errors.As(err, &blocked) {
-		t.Fatalf("expected BlockedError, got: %v", err)
-	}
-	if blocked.SandboxDir == "" {
-		t.Error("BlockedError.SandboxDir should be set when gemini task runs in a sandbox")
-	}
-	if _, statErr := os.Stat(blocked.SandboxDir); os.IsNotExist(statErr) {
-		t.Error("sandbox directory should be preserved when blocked")
-	} else {
-		os.RemoveAll(blocked.SandboxDir)
-	}
-}
-
-// TestGeminiRunner_Run_ExecError_PreservesSandbox verifies that when gemini
-// exits non-zero, the sandbox path is included in the wrapped error so the
-// user can inspect partial work.
-func TestGeminiRunner_Run_ExecError_PreservesSandbox(t *testing.T) {
-	src := t.TempDir()
-	initGitRepo(t, src)
-	logDir := t.TempDir()
-
-	// "false" exits 1, no output.
-	r := &GeminiRunner{
-		BinaryPath: "false",
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			Instructions: "do something",
-			ProjectDir:   src,
-			SkipPlanning: true,
-		},
-	}
-	e := &storage.Execution{ID: "err-gemini-exec", TaskID: "task-1"}
-
-	err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID))
-	if err == nil {
-		t.Fatal("expected error from failing gemini exit")
-	}
-	if !strings.Contains(err.Error(), "sandbox preserved at ") {
-		t.Errorf("expected error to include sandbox path; got: %v", err)
-	}
-	// Extract path and verify it exists.
-	idx := strings.Index(err.Error(), "sandbox preserved at ")
-	rest := err.Error()[idx+len("sandbox preserved at "):]
-	rest = strings.TrimSuffix(rest, ")")
-	rest = strings.TrimSpace(rest)
-	if _, statErr := os.Stat(rest); os.IsNotExist(statErr) {
-		t.Errorf("sandbox path from error should exist on disk: %q", rest)
-	} else {
-		os.RemoveAll(rest)
-	}
-}
-
-// TestGeminiRunner_Run_ResumeUsesStoredSandboxDir verifies that a resume
-// execution runs in the preserved SandboxDir rather than cloning fresh.
-func TestGeminiRunner_Run_ResumeUsesStoredSandboxDir(t *testing.T) {
-	logDir := t.TempDir()
-	sandboxDir := t.TempDir()
-	initGitRepo(t, sandboxDir)
-	cwdFile := filepath.Join(logDir, "cwd.txt")
-
-	scriptPath := filepath.Join(t.TempDir(), "fake-gemini.sh")
-	script := "#!/bin/sh\nprintf '%s' \"$PWD\" > " + cwdFile + "\n"
-	if err := os.WriteFile(scriptPath, []byte(script), 0755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-
-	r := &GeminiRunner{
-		BinaryPath: scriptPath,
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			SkipPlanning: true,
-		},
-	}
-	e := &storage.Execution{
-		ID:              "resume-gemini-1",
-		TaskID:          "task-resume",
-		ResumeSessionID: "session-abc",
-		SandboxDir:      sandboxDir,
-	}
-
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
-		t.Fatalf("Run with preserved sandbox: %v", err)
-	}
-
-	got, err := os.ReadFile(cwdFile)
-	if err != nil {
-		t.Fatalf("cwd file not written: %v", err)
-	}
-	if string(got) != sandboxDir {
-		t.Errorf("resume should run in preserved sandbox; got cwd=%q want %q", got, sandboxDir)
-	}
-}
-
-// TestGeminiRunner_Run_StaleSandboxDir_ClonesAfresh verifies that a resume
-// pointing at a missing sandbox falls back to cloning a fresh sandbox from
-// project_dir rather than failing outright.
-func TestGeminiRunner_Run_StaleSandboxDir_ClonesAfresh(t *testing.T) {
-	logDir := t.TempDir()
-	projectDir := t.TempDir()
-	initGitRepo(t, projectDir)
-
-	cwdFile := filepath.Join(logDir, "cwd.txt")
-	scriptPath := filepath.Join(t.TempDir(), "fake-gemini.sh")
-	script := "#!/bin/sh\nprintf '%s' \"$PWD\" > " + cwdFile + "\n"
-	if err := os.WriteFile(scriptPath, []byte(script), 0755); err != nil {
-		t.Fatalf("write script: %v", err)
-	}
-
-	r := &GeminiRunner{
-		BinaryPath: scriptPath,
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			ProjectDir:   projectDir,
-			SkipPlanning: true,
-		},
-	}
-	staleSandbox := filepath.Join(t.TempDir(), "gone")
-	e := &storage.Execution{
-		ID:              "resume-gemini-2",
-		TaskID:          "task-stale",
-		ResumeSessionID: "session-xyz",
-		SandboxDir:      staleSandbox,
-	}
-
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
-		t.Fatalf("Run with stale sandbox: %v", err)
-	}
-
-	got, err := os.ReadFile(cwdFile)
-	if err != nil {
-		t.Fatalf("cwd file not written: %v", err)
-	}
-	cwd := string(got)
-	if cwd == staleSandbox {
-		t.Error("ran in stale (nonexistent) sandbox dir")
-	}
-	if cwd == projectDir {
-		t.Error("ran directly in project_dir; expected a fresh sandbox clone")
-	}
-}
-
-// TestGeminiRunner_Run_NoProjectDir_SkipsSandbox verifies that a task with no
-// project_dir doesn't trigger sandbox setup (matches LocalRunner/non-coding
-// task semantics).
-func TestGeminiRunner_Run_NoProjectDir_SkipsSandbox(t *testing.T) {
-	logDir := t.TempDir()
-
-	r := &GeminiRunner{
-		BinaryPath: "true", // exits 0, no output
-		Logger:     slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir:     logDir,
-	}
-	tk := &task.Task{
-		Agent: task.AgentConfig{
-			Type:         "gemini",
-			Instructions: "summarize: 2+2",
-			SkipPlanning: true,
-			// No ProjectDir
-		},
-	}
-	e := &storage.Execution{ID: "no-pd-gemini", TaskID: "task-nopd"}
-
-	if err := r.Run(context.Background(), tk, e, newStoreChannel(nil, tk.ID)); err != nil {
-		t.Fatalf("Run without project_dir: %v", err)
-	}
-	if e.SandboxDir != "" {
-		t.Errorf("SandboxDir should be empty for tasks without project_dir, got %q", e.SandboxDir)
-	}
-}
diff --git a/internal/executor/sandbox.go b/internal/executor/sandbox.go
deleted file mode 100644
index a9248d1..0000000
--- a/internal/executor/sandbox.go
+++ /dev/null
@@ -1,187 +0,0 @@
-package executor
-
-import (
-	"fmt"
-	"log/slog"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-
-	"github.com/thepeterstone/claudomator/internal/storage"
-	"github.com/thepeterstone/claudomator/internal/task"
-)
-
-// sandboxCloneSource returns the URL to clone the sandbox from. It prefers a
-// remote named "local" (a local bare repo that accepts pushes cleanly), then
-// falls back to "origin", then to the working copy path itself.
-func sandboxCloneSource(projectDir string) string {
-	for _, remote := range []string{"local", "origin"} {
-		out, err := exec.Command("git", gitSafe("-C", projectDir, "remote", "get-url", remote)...).Output()
-		if err == nil {
-			u := strings.TrimSpace(string(out))
-			if u != "" && (strings.HasPrefix(u, "/") || strings.HasPrefix(u, "file://")) {
-				return u
-			}
-		}
-	}
-	return projectDir
-}
-
-// setupSandbox prepares a temporary git clone of projectDir.
-// If projectDir is not a git repo it is initialised with an initial commit first.
-func setupSandbox(projectDir string, logger *slog.Logger) (string, error) {
-	// Ensure projectDir is a git repo; initialise if not.
-	if err := exec.Command("git", gitSafe("-C", projectDir, "rev-parse", "--git-dir")...).Run(); err != nil {
-		cmds := [][]string{
-			gitSafe("-C", projectDir, "init"),
-			gitSafe("-C", projectDir, "add", "-A"),
-			gitSafe("-C", projectDir, "commit", "--allow-empty", "-m", "chore: initial commit"),
-		}
-		for _, args := range cmds {
-			if out, err := exec.Command("git", args...).CombinedOutput(); err != nil { //nolint:gosec
-				return "", fmt.Errorf("git init %s: %w\n%s", projectDir, err, out)
-			}
-		}
-	}
-
-	src := sandboxCloneSource(projectDir)
-
-	tempDir, err := os.MkdirTemp("", "claudomator-sandbox-*")
-	if err != nil {
-		return "", fmt.Errorf("creating sandbox dir: %w", err)
-	}
-	// git clone requires the target to not exist; remove the placeholder first.
-	if err := os.Remove(tempDir); err != nil {
-		return "", fmt.Errorf("removing temp dir placeholder: %w", err)
-	}
-	out, err := exec.Command("git", gitSafe("clone", "--no-hardlinks", src, tempDir)...).CombinedOutput()
-	if err != nil {
-		return "", fmt.Errorf("git clone: %w\n%s", err, out)
-	}
-	return tempDir, nil
-}
-
-// teardownSandbox verifies the sandbox is clean and pushes new commits to the
-// canonical bare repo. If the push is rejected because another task pushed
-// concurrently, it fetches and rebases then retries once.
-//
-// The working copy (projectDir) is NOT updated automatically — it is the
-// developer's workspace and is pulled manually. This avoids permission errors
-// from mixed-owner .git/objects directories.
-func teardownSandbox(projectDir, sandboxDir, startHEAD string, logger *slog.Logger, execRecord *storage.Execution) error {
-	// Automatically commit uncommitted changes.
-	out, err := exec.Command("git", "-C", sandboxDir, "status", "--porcelain").Output()
-	if err != nil {
-		return fmt.Errorf("git status: %w", err)
-	}
-	if len(strings.TrimSpace(string(out))) > 0 {
-		logger.Info("autocommitting uncommitted changes", "sandbox", sandboxDir)
-
-		// Run build before autocommitting.
-		if _, err := os.Stat(filepath.Join(sandboxDir, "Makefile")); err == nil {
-			logger.Info("running 'make build' before autocommit", "sandbox", sandboxDir)
-			if buildOut, buildErr := exec.Command("make", "-C", sandboxDir, "build").CombinedOutput(); buildErr != nil {
-				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
-			}
-		} else if _, err := os.Stat(filepath.Join(sandboxDir, "gradlew")); err == nil {
-			logger.Info("running './gradlew build' before autocommit", "sandbox", sandboxDir)
-			cmd := exec.Command("./gradlew", "build")
-			cmd.Dir = sandboxDir
-			if buildOut, buildErr := cmd.CombinedOutput(); buildErr != nil {
-				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
-			}
-		} else if _, err := os.Stat(filepath.Join(sandboxDir, "go.mod")); err == nil {
-			logger.Info("running 'go build ./...' before autocommit", "sandbox", sandboxDir)
-			cmd := exec.Command("go", "build", "./...")
-			cmd.Dir = sandboxDir
-			if buildOut, buildErr := cmd.CombinedOutput(); buildErr != nil {
-				return fmt.Errorf("build failed before autocommit: %w\n%s", buildErr, buildOut)
-			}
-		}
-
-		cmds := [][]string{
-			gitSafe("-C", sandboxDir, "add", "-A"),
-			gitSafe("-C", sandboxDir, "commit", "-m", "chore: autocommit uncommitted changes"),
-		}
-		for _, args := range cmds {
-			if out, err := exec.Command("git", args...).CombinedOutput(); err != nil {
-				return fmt.Errorf("autocommit failed (%v): %w\n%s", args, err, out)
-			}
-		}
-	}
-
-	// Capture commits before pushing/deleting.
-	// Use startHEAD..HEAD to find all commits made during this execution.
-	logRange := "origin/HEAD..HEAD"
-	if startHEAD != "" && startHEAD != "HEAD" {
-		logRange = startHEAD + "..HEAD"
-	}
-
-	logCmd := exec.Command("git", gitSafe("-C", sandboxDir, "log", logRange, "--pretty=format:%H|%s")...)
-	logOut, logErr := logCmd.CombinedOutput()
-	if logErr == nil {
-		lines := strings.Split(strings.TrimSpace(string(logOut)), "\n")
-		logger.Debug("captured commits", "count", len(lines), "range", logRange)
-		for _, line := range lines {
-			if line == "" {
-				continue
-			}
-			parts := strings.SplitN(line, "|", 2)
-			if len(parts) == 2 {
-				execRecord.Commits = append(execRecord.Commits, task.GitCommit{
-					Hash:    parts[0],
-					Message: parts[1],
-				})
-			}
-		}
-	} else {
-		logger.Warn("failed to capture commits", "err", logErr, "range", logRange, "output", string(logOut))
-	}
-
-	// Check whether there are any new commits to push.
-	ahead, err := exec.Command("git", gitSafe("-C", sandboxDir, "rev-list", "--count", logRange)...).Output()
-	if err != nil {
-		logger.Warn("could not determine commits ahead of origin; proceeding", "err", err, "range", logRange)
-	}
-	if strings.TrimSpace(string(ahead)) == "0" {
-		os.RemoveAll(sandboxDir)
-		return nil
-	}
-
-	// Push from sandbox → bare repo (sandbox's origin is the bare repo).
-	if out, err := exec.Command("git", "-C", sandboxDir, "push", "origin", "HEAD").CombinedOutput(); err != nil {
-		// If rejected due to concurrent push, fetch+rebase and retry once.
-		if strings.Contains(string(out), "fetch first") || strings.Contains(string(out), "non-fast-forward") {
-			logger.Info("push rejected (concurrent task); rebasing and retrying", "sandbox", sandboxDir)
-			if out2, err2 := exec.Command("git", "-C", sandboxDir, "pull", "--rebase", "origin", "master").CombinedOutput(); err2 != nil {
-				return fmt.Errorf("git rebase before retry push: %w\n%s", err2, out2)
-			}
-			// Re-capture commits after rebase (hashes might have changed)
-			execRecord.Commits = nil
-			logOut, logErr = exec.Command("git", "-C", sandboxDir, "log", logRange, "--pretty=format:%H|%s").Output()
-			if logErr == nil {
-				lines := strings.Split(strings.TrimSpace(string(logOut)), "\n")
-				for _, line := range lines {
-					parts := strings.SplitN(line, "|", 2)
-					if len(parts) == 2 {
-						execRecord.Commits = append(execRecord.Commits, task.GitCommit{
-							Hash:    parts[0],
-							Message: parts[1],
-						})
-					}
-				}
-			}
-
-			if out3, err3 := exec.Command("git", "-C", sandboxDir, "push", "origin", "HEAD").CombinedOutput(); err3 != nil {
-				return fmt.Errorf("git push to origin (after rebase): %w\n%s", err3, out3)
-			}
-		} else {
-			return fmt.Errorf("git push to origin: %w\n%s", err, out)
-		}
-	}
-
-	logger.Info("sandbox pushed to bare repo", "sandbox", sandboxDir)
-	os.RemoveAll(sandboxDir)
-	return nil
-}
diff --git a/internal/executor/sandbox_test.go b/internal/executor/sandbox_test.go
deleted file mode 100644
index 4893263..0000000
--- a/internal/executor/sandbox_test.go
+++ /dev/null
@@ -1,366 +0,0 @@
-package executor
-
-import (
-	"fmt"
-	"io"
-	"log/slog"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/thepeterstone/claudomator/internal/storage"
-)
-
-func TestSandboxCloneSource_PrefersLocalRemote(t *testing.T) {
-	dir := t.TempDir()
-	initGitRepo(t, dir)
-	// Add a "local" remote pointing to a bare repo.
-	bare := t.TempDir()
-	exec.Command("git", "init", "--bare", bare).Run()
-	exec.Command("git", "-C", dir, "remote", "add", "local", bare).Run()
-	exec.Command("git", "-C", dir, "remote", "add", "origin", "https://example.com/repo").Run()
-
-	got := sandboxCloneSource(dir)
-	if got != bare {
-		t.Errorf("expected bare repo path %q, got %q", bare, got)
-	}
-}
-
-func TestSandboxCloneSource_FallsBackToOrigin(t *testing.T) {
-	dir := t.TempDir()
-	initGitRepo(t, dir)
-	// sandboxCloneSource intentionally filters to local-FS remotes (so
-	// `git clone <src>` doesn't go over the network). Use a local path
-	// for origin to verify the fallback semantics.
-	originURL := t.TempDir()
-	exec.Command("git", "-C", dir, "remote", "add", "origin", originURL).Run()
-
-	got := sandboxCloneSource(dir)
-	if got != originURL {
-		t.Errorf("expected origin URL %q, got %q", originURL, got)
-	}
-}
-
-func TestSandboxCloneSource_FallsBackToProjectDir(t *testing.T) {
-	dir := t.TempDir()
-	initGitRepo(t, dir)
-	// No remotes configured.
-	got := sandboxCloneSource(dir)
-	if got != dir {
-		t.Errorf("expected projectDir %q (no remotes), got %q", dir, got)
-	}
-}
-
-func TestSetupSandbox_ClonesGitRepo(t *testing.T) {
-	src := t.TempDir()
-	initGitRepo(t, src)
-
-	sandbox, err := setupSandbox(src, slog.Default())
-	if err != nil {
-		t.Fatalf("setupSandbox: %v", err)
-	}
-	t.Cleanup(func() { os.RemoveAll(sandbox) })
-
-	// Force sandbox to master if it cloned as main
-	exec.Command("git", gitSafe("-C", sandbox, "checkout", "master")...).Run()
-
-	// Debug sandbox
-	logOut, _ := exec.Command("git", "-C", sandbox, "log", "-1").CombinedOutput()
-	fmt.Printf("DEBUG: sandbox log: %s\n", string(logOut))
-
-	// Verify sandbox is a git repo with at least one commit.
-	out, err := exec.Command("git", "-C", sandbox, "log", "--oneline").Output()
-	if err != nil {
-		t.Fatalf("git log in sandbox: %v", err)
-	}
-	if len(strings.TrimSpace(string(out))) == 0 {
-		t.Error("expected at least one commit in sandbox, got empty log")
-	}
-}
-
-func TestSetupSandbox_InitialisesNonGitDir(t *testing.T) {
-	// A plain directory (not a git repo) should be initialised then cloned.
-	src := t.TempDir()
-
-	sandbox, err := setupSandbox(src, slog.Default())
-	if err != nil {
-		t.Fatalf("setupSandbox on plain dir: %v", err)
-	}
-	t.Cleanup(func() { os.RemoveAll(sandbox) })
-
-	if _, err := os.Stat(filepath.Join(sandbox, ".git")); err != nil {
-		t.Errorf("sandbox should be a git repo: %v", err)
-	}
-}
-
-func TestTeardownSandbox_AutocommitsChanges(t *testing.T) {
-	// Create a bare repo as origin so push succeeds.
-	bare := t.TempDir()
-	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git init bare: %v\n%s", err, out)
-	}
-
-	// Create a sandbox directly.
-	sandbox := t.TempDir()
-	initGitRepo(t, sandbox)
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git remote add: %v\n%s", err, out)
-	}
-	// Initial push to establish origin/main
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "push", "origin", "main").CombinedOutput(); err != nil {
-		t.Fatalf("git push initial: %v\n%s", err, out)
-	}
-
-	// Capture startHEAD
-	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
-	if err != nil {
-		t.Fatalf("rev-parse HEAD: %v", err)
-	}
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Leave an uncommitted file in the sandbox.
-	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("autocommit me"), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug}))
-	execRecord := &storage.Execution{}
-
-	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
-	if err != nil {
-		t.Fatalf("expected autocommit to succeed, got error: %v", err)
-	}
-
-	// Sandbox should be removed after successful autocommit and push.
-	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
-		t.Error("sandbox should have been removed after successful autocommit and push")
-	}
-
-	// Verify the commit exists in the bare repo.
-	out, err := exec.Command("git", "-C", bare, "log", "-1", "--pretty=%B").Output()
-	if err != nil {
-		t.Fatalf("git log in bare repo: %v", err)
-	}
-	if !strings.Contains(string(out), "chore: autocommit uncommitted changes") {
-		t.Errorf("expected autocommit message in log, got: %q", string(out))
-	}
-
-	// Verify the commit was captured in execRecord.
-	if len(execRecord.Commits) == 0 {
-		t.Error("expected at least one commit in execRecord")
-	} else if !strings.Contains(execRecord.Commits[0].Message, "chore: autocommit uncommitted changes") {
-		t.Errorf("unexpected commit message: %q", execRecord.Commits[0].Message)
-	}
-}
-
-func TestTeardownSandbox_BuildFailure_BlocksAutocommit(t *testing.T) {
-	bare := t.TempDir()
-	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git init bare: %v\n%s", err, out)
-	}
-
-	sandbox := t.TempDir()
-	initGitRepo(t, sandbox)
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git remote add: %v\n%s", err, out)
-	}
-
-	// Capture startHEAD
-	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
-	if err != nil {
-		t.Fatalf("rev-parse HEAD: %v", err)
-	}
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Leave an uncommitted file.
-	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("dirty"), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	// Add a failing Makefile.
-	makefile := "build:\n\t@echo 'build failed'\n\texit 1\n"
-	if err := os.WriteFile(filepath.Join(sandbox, "Makefile"), []byte(makefile), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	execRecord := &storage.Execution{}
-
-	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
-	if err == nil {
-		t.Error("expected teardown to fail due to build failure, but it succeeded")
-	} else if !strings.Contains(err.Error(), "build failed before autocommit") {
-		t.Errorf("expected build failure error message, got: %v", err)
-	}
-
-	// Sandbox should NOT be removed if teardown failed.
-	if _, statErr := os.Stat(sandbox); os.IsNotExist(statErr) {
-		t.Error("sandbox should have been preserved after build failure")
-	}
-
-	// Verify no new commit in bare repo.
-	out, err := exec.Command("git", "-C", bare, "log", "HEAD").CombinedOutput()
-	if strings.Contains(string(out), "chore: autocommit uncommitted changes") {
-		t.Error("autocommit should not have been pushed after build failure")
-	}
-}
-
-func TestTeardownSandbox_BuildSuccess_ProceedsToAutocommit(t *testing.T) {
-	bare := t.TempDir()
-	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git init bare: %v\n%s", err, out)
-	}
-
-	sandbox := t.TempDir()
-	initGitRepo(t, sandbox)
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git remote add: %v\n%s", err, out)
-	}
-
-	// Capture startHEAD
-	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
-	if err != nil {
-		t.Fatalf("rev-parse HEAD: %v", err)
-	}
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Leave an uncommitted file.
-	if err := os.WriteFile(filepath.Join(sandbox, "dirty.txt"), []byte("dirty"), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	// Add a successful Makefile.
-	makefile := "build:\n\t@echo 'build succeeded'\n"
-	if err := os.WriteFile(filepath.Join(sandbox, "Makefile"), []byte(makefile), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	execRecord := &storage.Execution{}
-
-	err = teardownSandbox("", sandbox, startHEAD, logger, execRecord)
-	if err != nil {
-		t.Fatalf("expected teardown to succeed after build success, got error: %v", err)
-	}
-
-	// Sandbox should be removed after success.
-	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
-		t.Error("sandbox should have been removed after successful build and autocommit")
-	}
-
-	// Verify new commit in bare repo.
-	out, err := exec.Command("git", "-C", bare, "log", "-1", "--pretty=%B").Output()
-	if err != nil {
-		t.Fatalf("git log in bare repo: %v", err)
-	}
-	if !strings.Contains(string(out), "chore: autocommit uncommitted changes") {
-		t.Errorf("expected autocommit message in log, got: %q", string(out))
-	}
-}
-
-func TestTeardownSandbox_CapturesExplicitCommits(t *testing.T) {
-	bare := t.TempDir()
-	if out, err := exec.Command("git", "init", "--bare", "-b", "main", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git init bare: %v\n%s", err, out)
-	}
-
-	sandbox := t.TempDir()
-	initGitRepo(t, sandbox)
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "remote", "add", "origin", bare).CombinedOutput(); err != nil {
-		t.Fatalf("git remote add: %v\n%s", err, out)
-	}
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "push", "origin", "main").CombinedOutput(); err != nil {
-		t.Fatalf("git push initial: %v\n%s", err, out)
-	}
-
-	headOut, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "rev-parse", "HEAD").Output()
-	if err != nil {
-		t.Fatalf("rev-parse HEAD: %v", err)
-	}
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Simulate Claude explicitly committing changes.
-	if err := os.WriteFile(filepath.Join(sandbox, "work.txt"), []byte("done"), 0644); err != nil {
-		t.Fatal(err)
-	}
-	for _, args := range [][]string{
-		{"-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "add", "-A"},
-		{"-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", sandbox, "commit", "-m", "feat: implement the feature"},
-	} {
-		if out, err := exec.Command("git", args...).CombinedOutput(); err != nil {
-			t.Fatalf("git %v: %v\n%s", args, err, out)
-		}
-	}
-
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	execRecord := &storage.Execution{}
-
-	if err := teardownSandbox("", sandbox, startHEAD, logger, execRecord); err != nil {
-		t.Fatalf("teardownSandbox: %v", err)
-	}
-
-	if len(execRecord.Commits) == 0 {
-		t.Fatal("expected commits to be captured in execRecord")
-	}
-	if !strings.Contains(execRecord.Commits[0].Message, "feat: implement the feature") {
-		t.Errorf("unexpected commit message: %q", execRecord.Commits[0].Message)
-	}
-	if execRecord.Commits[0].Hash == "" {
-		t.Error("commit hash should not be empty")
-	}
-}
-
-func TestTeardownSandbox_CleanSandboxWithNoNewCommits_RemovesSandbox(t *testing.T) {
-	src := t.TempDir()
-	initGitRepo(t, src)
-	sandbox, err := setupSandbox(src, slog.Default())
-	if err != nil {
-		t.Fatalf("setupSandbox: %v", err)
-	}
-
-	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	execRecord := &storage.Execution{}
-
-	headOut, _ := exec.Command("git", "-C", sandbox, "rev-parse", "HEAD").Output()
-	startHEAD := strings.TrimSpace(string(headOut))
-
-	// Sandbox has no new commits beyond origin; teardown should succeed and remove it.
-	if err := teardownSandbox(src, sandbox, startHEAD, logger, execRecord); err != nil {
-		t.Fatalf("teardownSandbox: %v", err)
-	}
-	if _, statErr := os.Stat(sandbox); !os.IsNotExist(statErr) {
-		t.Error("sandbox should have been removed after clean teardown")
-		os.RemoveAll(sandbox)
-	}
-}
-func TestTailFile_MissingFile_ReturnsEmpty(t *testing.T) {
-	got := tailFile("/nonexistent/path/file.log", 10)
-	if got != "" {
-		t.Errorf("want empty string for missing file, got %q", got)
-	}
-}
-
-func initGitRepo(t *testing.T, dir string) {
-	t.Helper()
-	cmds := [][]string{
-		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "init", "-b", "main"},
-		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "config", "user.email", "test@test"},
-		{"git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "config", "user.name", "test"},
-	}
-	for _, args := range cmds {
-		if out, err := exec.Command(args[0], args[1:]...).CombinedOutput(); err != nil {
-			t.Fatalf("%v: %v\n%s", args, err, out)
-		}
-	}
-	if err := os.WriteFile(filepath.Join(dir, "init.txt"), []byte("init"), 0644); err != nil {
-		t.Fatal(err)
-	}
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "add", ".").CombinedOutput(); err != nil {
-		t.Fatalf("git add: %v\n%s", err, out)
-	}
-	if out, err := exec.Command("git", "-c", "safe.directory=*", "-c", "commit.gpgsign=false", "-C", dir, "commit", "-m", "init").CombinedOutput(); err != nil {
-		t.Fatalf("git commit: %v\n%s", err, out)
-	}
-}
-- 
cgit v1.2.3


From 65cd7ea65d9c6fe0fad39bb2c5cac70d61153444 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 25 May 2026 19:02:19 +0000
Subject: feat(executor): wire the agent MCP back-channel for gemini containers
 (Phase 4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ContainerRunner previously skipped the MCP back-channel for gemini agents, so
they ran tool-less. It now mints a per-task token for gemini too and registers
the agent MCP server in the gemini CLI's user settings
(agentHome/.gemini/settings.json → $HOME/.gemini in-container) using the
gemini-cli mcpServers/httpUrl schema with a bearer header. With MCP enabled,
gemini also receives the planning preamble that points at the ask_user/
report_summary/spawn_subtask/record_progress tools.

Config generation is unit-tested (TestWriteGeminiMCPSettings) and the write is
in the run setup path. CAVEAT: whether the gemini CLI actually invokes these
tools in non-interactive (-p) mode — and how it handles tool auto-approval —
is NOT verified against a live gemini binary in this environment; this lands
the plumbing for a follow-up spike. No regression risk for gemini runs: a
config issue degrades to the prior tool-less behavior.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/executor/container.go      | 42 ++++++++++++++++++++++++++++++++++---
 internal/executor/container_test.go | 30 ++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 3 deletions(-)

(limited to 'internal/executor')

diff --git a/internal/executor/container.go b/internal/executor/container.go
index 78c3ed7..4f8fa06 100644
--- a/internal/executor/container.go
+++ b/internal/executor/container.go
@@ -306,16 +306,22 @@ func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *sto
 	}
 
 	// Per-task MCP back-channel: mint a scoped token bound to this run's channel
-	// and write an mcp-config pointing the agent at the host agent MCP server.
+	// and point the agent at the host agent MCP server. Claude reads an
+	// --mcp-config file; the gemini CLI auto-discovers servers from its
+	// ~/.gemini/settings.json (agentHome is the container's $HOME).
 	mcpEnabled := false
-	if r.Registry != nil && t.Agent.Type != "gemini" {
+	if r.Registry != nil {
 		token, mintErr := r.Registry.Mint(ch)
 		if mintErr != nil {
 			return fmt.Errorf("minting agent mcp token: %w", mintErr)
 		}
 		defer r.Registry.Revoke(token)
 		mcpURL := strings.TrimRight(strings.ReplaceAll(r.APIURL, "localhost", "host.docker.internal"), "/") + "/mcp"
-		if err := writeMCPConfig(workspace, mcpURL, token); err != nil {
+		if t.Agent.Type == "gemini" {
+			if err := writeGeminiMCPSettings(agentHome, mcpURL, token); err != nil {
+				return fmt.Errorf("writing gemini mcp settings: %w", err)
+			}
+		} else if err := writeMCPConfig(workspace, mcpURL, token); err != nil {
 			return fmt.Errorf("writing mcp config: %w", err)
 		}
 		mcpEnabled = true
@@ -534,6 +540,36 @@ func writeMCPConfig(workspace, mcpURL, token string) error {
 	return os.WriteFile(filepath.Join(workspace, ".claudomator-mcp.json"), data, 0600)
 }
 
+// writeGeminiMCPSettings registers the per-task agent MCP server in the gemini
+// CLI's user settings (agentHome/.gemini/settings.json, which is $HOME/.gemini
+// in-container). The gemini CLI discovers MCP servers from this file rather than
+// a command-line flag; httpUrl selects the streamable-HTTP transport and headers
+// carry the bearer token.
+//
+// NOTE: the on-disk schema follows the gemini-cli mcpServers format, but whether
+// the CLI actually invokes these tools in non-interactive (-p) mode has not been
+// verified against a live gemini binary — confirm with a spike before relying on
+// gemini tool-use in production.
+func writeGeminiMCPSettings(agentHome, mcpURL, token string) error {
+	cfg := map[string]any{
+		"mcpServers": map[string]any{
+			"claudomator": map[string]any{
+				"httpUrl": mcpURL,
+				"headers": map[string]string{"Authorization": "Bearer " + token},
+			},
+		},
+	}
+	data, err := json.Marshal(cfg)
+	if err != nil {
+		return err
+	}
+	dir := filepath.Join(agentHome, ".gemini")
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return err
+	}
+	return os.WriteFile(filepath.Join(dir, "settings.json"), data, 0600)
+}
+
 func (r *ContainerRunner) buildInnerCmd(t *task.Task, e *storage.Execution, isResume, mcpEnabled bool) []string {
 	// Claude CLI uses -p for prompt text. To pass a file, we use a shell to cat it.
 	// We use a shell variable to capture the expansion to avoid quoting issues with instructions contents.
diff --git a/internal/executor/container_test.go b/internal/executor/container_test.go
index 3d0887c..521e1cb 100644
--- a/internal/executor/container_test.go
+++ b/internal/executor/container_test.go
@@ -107,6 +107,36 @@ func TestWriteMCPConfig(t *testing.T) {
 	}
 }
 
+func TestWriteGeminiMCPSettings(t *testing.T) {
+	agentHome := t.TempDir()
+	if err := writeGeminiMCPSettings(agentHome, "http://host.docker.internal:8484/mcp", "tok-xyz"); err != nil {
+		t.Fatalf("writeGeminiMCPSettings: %v", err)
+	}
+	data, err := os.ReadFile(filepath.Join(agentHome, ".gemini", "settings.json"))
+	if err != nil {
+		t.Fatalf("read settings: %v", err)
+	}
+	var parsed struct {
+		MCPServers map[string]struct {
+			HTTPURL string            `json:"httpUrl"`
+			Headers map[string]string `json:"headers"`
+		} `json:"mcpServers"`
+	}
+	if err := json.Unmarshal(data, &parsed); err != nil {
+		t.Fatalf("settings is not valid JSON: %v", err)
+	}
+	srv, ok := parsed.MCPServers["claudomator"]
+	if !ok {
+		t.Fatal("expected claudomator server entry")
+	}
+	if srv.HTTPURL != "http://host.docker.internal:8484/mcp" {
+		t.Errorf("unexpected httpUrl: %q", srv.HTTPURL)
+	}
+	if srv.Headers["Authorization"] != "Bearer tok-xyz" {
+		t.Errorf("expected bearer header, got %q", srv.Headers["Authorization"])
+	}
+}
+
 func TestContainerRunner_BuildInnerCmd(t *testing.T) {
 	runner := &ContainerRunner{}
 	
-- 
cgit v1.2.3


From 301e7a66387f99ab76754d08bca42f4a9930d3b1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 26 May 2026 07:11:59 +0000
Subject: feat(executor,llm): LocalRunner agent-channel via OpenAI tool-use
 (Phase 5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

LocalRunner previously ignored the AgentChannel and produced a single
fire-and-forget completion. It now declares the four agent back-channel tools
(ask_user/report_summary/spawn_subtask/record_progress) as OpenAI
function-calling definitions and runs a tool-use loop: each turn feeds tool
results back as message history (re-feed) until the model stops calling tools,
bounded by maxLocalToolTurns. ask_user converts a buffered question into a
*BlockedError so the task blocks like the container runners.

Adds tool-use support to the llm client (Tool/ToolCall/ToolFunction types,
Tools on ChatRequest, ToolCalls on ChatResponse + wire request/response). The
loop uses non-streaming Chat (tool_calls don't stream cleanly); assistant text
is still written to stdout.log in the Claude stream-json envelope so summary/
changestats parsing is unchanged.

Fully tested against a mock OpenAI endpoint + storeChannel: spawn/summary/
progress dispatch, ask_user blocking, token accumulation, and the llm tools
round-trip. NOTE: local resume re-feeds conversation state (Decision #8) — not
yet wired, so a blocked local task resumes fresh for now.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/executor/local.go      | 114 +++++++++++++++++-------
 internal/executor/local_test.go | 193 ++++++++++++++++++++++++++++------------
 internal/executor/localtools.go | 135 ++++++++++++++++++++++++++++
 internal/llm/client.go          |  37 ++++++++
 internal/llm/client_test.go     |  40 +++++++++
 5 files changed, 429 insertions(+), 90 deletions(-)
 create mode 100644 internal/executor/localtools.go

(limited to 'internal/executor')

diff --git a/internal/executor/local.go b/internal/executor/local.go
index e3c9c2c..3f20fe7 100644
--- a/internal/executor/local.go
+++ b/internal/executor/local.go
@@ -37,10 +37,17 @@ func (r *LocalRunner) ExecLogDir(execID string) string {
 	return filepath.Join(r.LogDir, execID)
 }
 
-// Run streams a chat completion to stdout.log. The response is wrapped in
-// stream-json envelopes line-by-line so downstream parsers (summary,
-// changestats) read it the same way they read Claude output.
-func (r *LocalRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, _ AgentChannel) error {
+// maxLocalToolTurns bounds the tool-use loop so a misbehaving model cannot spin
+// forever calling tools without finishing.
+const maxLocalToolTurns = 12
+
+// Run drives a chat completion against the local endpoint with the agent
+// back-channel tools (ask_user/report_summary/spawn_subtask/record_progress)
+// declared. It loops, feeding tool results back as message history, until the
+// model stops calling tools. Assistant text is written to stdout.log in the
+// same stream-json envelope Claude uses so downstream parsers keep working.
+// If the model calls ask_user, the run stops and returns a *BlockedError.
+func (r *LocalRunner) Run(ctx context.Context, t *task.Task, e *storage.Execution, ch AgentChannel) error {
 	if r.Client == nil {
 		return fmt.Errorf("local runner: no LLM client configured")
 	}
@@ -70,56 +77,95 @@ func (r *LocalRunner) Run(ctx context.Context, t *task.Task, e *storage.Executio
 	if sys := strings.TrimSpace(t.Agent.SystemPromptAppend); sys != "" {
 		messages = append(messages, llm.Message{Role: "system", Content: sys})
 	}
-	messages = append(messages, llm.Message{Role: "user", Content: t.Agent.Instructions})
+	// The agent tools are real here, so guide the model toward them with the
+	// same planning preamble the container runners use (unless skip_planning).
+	messages = append(messages, llm.Message{Role: "user", Content: buildAgentInstructions(t, true)})
 
 	temperature := t.Agent.Temperature
 	if temperature == nil && r.DefaultTemperature > 0 {
 		v := r.DefaultTemperature
 		temperature = &v
 	}
-
-	req := llm.ChatRequest{
-		Model:       t.Agent.Model,
-		Messages:    messages,
-		Temperature: temperature,
-		MaxTokens:   t.Agent.MaxTokens,
-	}
+	tools := agentToolDefs()
 
 	start := time.Now()
-	resp, err := r.Client.ChatStream(ctx, req, func(delta string) {
-		if delta == "" {
-			return
+	var totalIn, totalOut int
+	var lastModel, lastFinish string
+	blocked := false
+
+	for turn := 0; turn < maxLocalToolTurns; turn++ {
+		resp, chatErr := r.Client.Chat(ctx, llm.ChatRequest{
+			Model:       t.Agent.Model,
+			Messages:    messages,
+			Temperature: temperature,
+			MaxTokens:   t.Agent.MaxTokens,
+			Tools:       tools,
+		})
+		if chatErr != nil {
+			writeResultLine(stdout, "error", chatErr.Error(), totalIn, totalOut)
+			return fmt.Errorf("local runner: chat: %w", chatErr)
+		}
+		totalIn += resp.PromptTokens
+		totalOut += resp.OutputTokens
+		lastModel, lastFinish = resp.Model, resp.FinishReason
+
+		if resp.Content != "" {
+			writeAssistantTextLine(stdout, resp.Content)
 		}
-		writeAssistantTextLine(stdout, delta)
-	})
-	if err != nil {
-		writeResultLine(stdout, "error", err.Error(), 0, 0)
-		return fmt.Errorf("local runner: chat: %w", err)
-	}
-	elapsed := time.Since(start)
 
-	// Write one consolidated assistant envelope containing the full response.
-	// extractSummary and ParseChangestatFromOutput operate per-line, so a
-	// single envelope with the full text is what they expect to find.
-	if resp.Content != "" {
-		writeAssistantTextLine(stdout, resp.Content)
+		if len(resp.ToolCalls) == 0 {
+			break
+		}
+
+		// Re-feed: record the assistant's tool-call turn, then each tool result.
+		messages = append(messages, llm.Message{Role: "assistant", Content: resp.Content, ToolCalls: resp.ToolCalls})
+		for _, tc := range resp.ToolCalls {
+			result, didBlock, toolErr := dispatchAgentTool(ctx, ch, tc.Function.Name, tc.Function.Arguments)
+			if toolErr != nil {
+				writeResultLine(stdout, "error", toolErr.Error(), totalIn, totalOut)
+				return fmt.Errorf("local runner: tool %s: %w", tc.Function.Name, toolErr)
+			}
+			if didBlock {
+				blocked = true
+				break
+			}
+			messages = append(messages, llm.Message{
+				Role:       "tool",
+				ToolCallID: tc.ID,
+				Name:       tc.Function.Name,
+				Content:    result,
+			})
+		}
+		if blocked {
+			break
+		}
 	}
-	writeResultLine(stdout, "success", "", resp.PromptTokens, resp.OutputTokens)
+	elapsed := time.Since(start)
 
 	e.CostUSD = 0
-	e.TokensIn = int64(resp.PromptTokens)
-	e.TokensOut = int64(resp.OutputTokens)
+	e.TokensIn = int64(totalIn)
+	e.TokensOut = int64(totalOut)
 
 	if r.Logger != nil {
 		r.Logger.Info("local runner completed",
 			"taskID", t.ID,
-			"model", resp.Model,
-			"tokens_in", resp.PromptTokens,
-			"tokens_out", resp.OutputTokens,
-			"finish_reason", resp.FinishReason,
+			"model", lastModel,
+			"tokens_in", totalIn,
+			"tokens_out", totalOut,
+			"finish_reason", lastFinish,
+			"blocked", blocked,
 			"elapsed_ms", elapsed.Milliseconds(),
 		)
 	}
+
+	// If the model asked the user, stop and block. Local resume re-feeds the
+	// conversation (per-runner sovereign state) — not yet wired, so the session
+	// ID is empty and resume starts fresh for now.
+	if q, isBlocked := channelPendingQuestion(ch); isBlocked {
+		return &BlockedError{QuestionJSON: q}
+	}
+
+	writeResultLine(stdout, "success", "", totalIn, totalOut)
 	return nil
 }
 
diff --git a/internal/executor/local_test.go b/internal/executor/local_test.go
index ffe87f9..2ae8380 100644
--- a/internal/executor/local_test.go
+++ b/internal/executor/local_test.go
@@ -3,7 +3,7 @@ package executor
 import (
 	"context"
 	"encoding/json"
-	"fmt"
+	"errors"
 	"io"
 	"log/slog"
 	"net/http"
@@ -11,6 +11,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"testing"
 
 	"github.com/google/uuid"
@@ -19,60 +20,77 @@ import (
 	"github.com/thepeterstone/claudomator/internal/task"
 )
 
-// fakeOpenAIServer returns an httptest.Server that replies with a streaming
-// chat completion containing the supplied content (split into chunks) plus a
-// usage record.
-func fakeOpenAIServer(t *testing.T, chunks []string, promptTok, outTok int) *httptest.Server {
+// fakeTurn is one canned chat-completion response the fake server returns.
+type fakeTurn struct {
+	content   string
+	toolCalls []llm.ToolCall
+	promptTok int
+	outTok    int
+}
+
+// fakeChatServer replies to /chat/completions with the supplied turns in order,
+// one per request (non-streaming JSON), so a tool-use loop can be driven
+// deterministically. Requests beyond the list repeat the final turn.
+func fakeChatServer(t *testing.T, turns []fakeTurn) *httptest.Server {
 	t.Helper()
-	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "text/event-stream")
-		flusher, _ := w.(http.Flusher)
-		for _, c := range chunks {
-			payload := map[string]any{
-				"model":   "fake",
-				"choices": []map[string]any{{"delta": map[string]string{"content": c}}},
-			}
-			b, _ := json.Marshal(payload)
-			fmt.Fprintf(w, "data: %s\n\n", b)
-			if flusher != nil {
-				flusher.Flush()
-			}
+	var mu sync.Mutex
+	idx := 0
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		mu.Lock()
+		turn := turns[idx]
+		if idx < len(turns)-1 {
+			idx++
+		}
+		mu.Unlock()
+
+		msg := map[string]any{"role": "assistant", "content": turn.content}
+		if len(turn.toolCalls) > 0 {
+			msg["tool_calls"] = turn.toolCalls
 		}
-		final := map[string]any{
+		resp := map[string]any{
 			"model":   "fake",
-			"choices": []map[string]any{{"delta": map[string]string{}, "finish_reason": "stop"}},
-			"usage":   map[string]int{"prompt_tokens": promptTok, "completion_tokens": outTok},
+			"choices": []map[string]any{{"message": msg, "finish_reason": "stop"}},
+			"usage":   map[string]int{"prompt_tokens": turn.promptTok, "completion_tokens": turn.outTok},
 		}
-		fb, _ := json.Marshal(final)
-		fmt.Fprintf(w, "data: %s\n\ndata: [DONE]\n\n", fb)
+		_ = json.NewEncoder(w).Encode(resp)
 	}))
 }
 
-func TestLocalRunner_Run_WritesStreamJSON(t *testing.T) {
-	srv := fakeOpenAIServer(t,
-		[]string{"## Summary\n", "All ", "good."},
-		11, 22,
-	)
-	defer srv.Close()
+func toolCall(id, name, args string) llm.ToolCall {
+	return llm.ToolCall{ID: id, Type: "function", Function: llm.ToolCallFunction{Name: name, Arguments: args}}
+}
 
-	logRoot := t.TempDir()
-	r := &LocalRunner{
+func newLocalRunner(t *testing.T, srv *httptest.Server) *LocalRunner {
+	t.Helper()
+	return &LocalRunner{
 		Client: &llm.Client{Endpoint: srv.URL + "/v1", Model: "fake"},
 		Logger: slog.New(slog.NewTextHandler(io.Discard, nil)),
-		LogDir: logRoot,
+		LogDir: t.TempDir(),
 	}
-	tt := &task.Task{
+}
+
+func localTask() *task.Task {
+	return &task.Task{
 		ID:   "task-1",
 		Name: "test",
 		Agent: task.AgentConfig{
 			Type:         "local",
 			Model:        "fake",
 			Instructions: "Do a thing.",
+			SkipPlanning: true, // keep the preamble out of these assertions
 		},
 	}
+}
+
+func TestLocalRunner_Run_WritesStreamJSON(t *testing.T) {
+	srv := fakeChatServer(t, []fakeTurn{{content: "## Summary\nAll good.", promptTok: 11, outTok: 22}})
+	defer srv.Close()
+
+	r := newLocalRunner(t, srv)
+	tt := localTask()
 	exec := &storage.Execution{ID: uuid.New().String(), TaskID: tt.ID}
 
-	if err := r.Run(context.Background(), tt, exec, newStoreChannel(nil, tt.ID)); err != nil {
+	if err := r.Run(context.Background(), tt, exec, newStoreChannel(&fakeChannelStore{}, tt.ID)); err != nil {
 		t.Fatalf("Run: %v", err)
 	}
 
@@ -83,40 +101,103 @@ func TestLocalRunner_Run_WritesStreamJSON(t *testing.T) {
 		t.Errorf("tokens: want 11/22 got %d/%d", exec.TokensIn, exec.TokensOut)
 	}
 
-	// Verify stdout.log contains stream-json envelopes that extractSummary can parse.
 	stdoutPath := filepath.Join(r.ExecLogDir(exec.ID), "stdout.log")
 	data, err := os.ReadFile(stdoutPath)
 	if err != nil {
 		t.Fatalf("read stdout: %v", err)
 	}
 	lines := strings.Split(strings.TrimSpace(string(data)), "\n")
-	if len(lines) < 4 {
-		t.Fatalf("expected at least 4 lines (3 deltas + 1 result), got %d:\n%s", len(lines), data)
-	}
-	for i, line := range lines[:3] {
-		var env struct {
-			Type    string `json:"type"`
-			Message struct {
-				Content []struct {
-					Type string `json:"type"`
-					Text string `json:"text"`
-				}
-			}
-		}
-		if err := json.Unmarshal([]byte(line), &env); err != nil {
-			t.Fatalf("line %d not JSON: %v: %s", i, err, line)
-		}
-		if env.Type != "assistant" {
-			t.Errorf("line %d: want type=assistant, got %q", i, env.Type)
-		}
+	// One assistant envelope + one result line.
+	if len(lines) != 2 {
+		t.Fatalf("expected 2 lines (assistant + result), got %d:\n%s", len(lines), data)
+	}
+	var env struct {
+		Type string `json:"type"`
+	}
+	if err := json.Unmarshal([]byte(lines[0]), &env); err != nil || env.Type != "assistant" {
+		t.Fatalf("line 0 should be an assistant envelope: %v: %s", err, lines[0])
 	}
 
-	summary := extractSummary(stdoutPath)
-	if !strings.Contains(summary, "All good.") {
+	if summary := extractSummary(stdoutPath); !strings.Contains(summary, "All good.") {
 		t.Errorf("extractSummary should find 'All good.', got %q", summary)
 	}
 }
 
+func TestLocalRunner_Run_ToolLoop_ReportSummaryAndSpawn(t *testing.T) {
+	// Turn 1: model spawns a subtask. Turn 2: reports summary. Turn 3: finishes.
+	srv := fakeChatServer(t, []fakeTurn{
+		{toolCalls: []llm.ToolCall{toolCall("c1", "spawn_subtask", `{"name":"sub A","instructions":"do sub"}`)}, promptTok: 5, outTok: 3},
+		{toolCalls: []llm.ToolCall{toolCall("c2", "report_summary", `{"summary":"all done"}`)}, promptTok: 4, outTok: 2},
+		{content: "finished", promptTok: 2, outTok: 1},
+	})
+	defer srv.Close()
+
+	r := newLocalRunner(t, srv)
+	tt := localTask()
+	store := &fakeChannelStore{}
+	ch := newStoreChannel(store, tt.ID)
+	exec := &storage.Execution{ID: uuid.New().String(), TaskID: tt.ID}
+
+	if err := r.Run(context.Background(), tt, exec, ch); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+
+	if len(store.createdTasks) != 1 || store.createdTasks[0].Name != "sub A" {
+		t.Errorf("expected one spawned subtask 'sub A', got %+v", store.createdTasks)
+	}
+	if store.createdTasks[0].ParentTaskID != tt.ID {
+		t.Errorf("subtask parent: want %q, got %q", tt.ID, store.createdTasks[0].ParentTaskID)
+	}
+	if sum, ok := ch.ReportedSummary(); !ok || sum != "all done" {
+		t.Errorf("expected reported summary 'all done', got %q (set=%v)", sum, ok)
+	}
+	// Tokens accumulate across all three turns.
+	if exec.TokensIn != 11 || exec.TokensOut != 6 {
+		t.Errorf("tokens should accumulate: want 11/6, got %d/%d", exec.TokensIn, exec.TokensOut)
+	}
+}
+
+func TestLocalRunner_Run_RecordProgress(t *testing.T) {
+	srv := fakeChatServer(t, []fakeTurn{
+		{toolCalls: []llm.ToolCall{toolCall("c1", "record_progress", `{"message":"halfway there"}`)}},
+		{content: "done"},
+	})
+	defer srv.Close()
+
+	store := &fakeChannelStore{}
+	tt := localTask()
+	exec := &storage.Execution{ID: uuid.New().String(), TaskID: tt.ID}
+	if err := newLocalRunner(t, srv).Run(context.Background(), tt, exec, newStoreChannel(store, tt.ID)); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if len(store.createdEvents) != 1 {
+		t.Fatalf("expected 1 progress event, got %d", len(store.createdEvents))
+	}
+	if !strings.Contains(string(store.createdEvents[0].Payload), "halfway there") {
+		t.Errorf("progress event payload: %s", store.createdEvents[0].Payload)
+	}
+}
+
+func TestLocalRunner_Run_AskUser_Blocks(t *testing.T) {
+	srv := fakeChatServer(t, []fakeTurn{
+		{toolCalls: []llm.ToolCall{toolCall("c1", "ask_user", `{"question":"which branch?"}`)}},
+		{content: "should not be reached"},
+	})
+	defer srv.Close()
+
+	tt := localTask()
+	exec := &storage.Execution{ID: uuid.New().String(), TaskID: tt.ID}
+	err := newLocalRunner(t, srv).Run(context.Background(), tt, exec, newStoreChannel(&fakeChannelStore{}, tt.ID))
+
+	var be *BlockedError
+	if !errors.As(err, &be) {
+		t.Fatalf("expected *BlockedError, got %v", err)
+	}
+	if !strings.Contains(be.QuestionJSON, "which branch?") {
+		t.Errorf("BlockedError question: %q", be.QuestionJSON)
+	}
+}
+
 func TestLocalRunner_Run_NoClient_Errors(t *testing.T) {
 	r := &LocalRunner{LogDir: t.TempDir()}
 	tt := &task.Task{ID: "x", Agent: task.AgentConfig{Instructions: "hi"}}
diff --git a/internal/executor/localtools.go b/internal/executor/localtools.go
new file mode 100644
index 0000000..48b862f
--- /dev/null
+++ b/internal/executor/localtools.go
@@ -0,0 +1,135 @@
+package executor
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	"github.com/thepeterstone/claudomator/internal/llm"
+)
+
+// agentToolDefs returns the four agent back-channel tools as OpenAI
+// function-calling definitions, for runners that talk to an OpenAI-compatible
+// endpoint (LocalRunner). They mirror the MCP tools the container runners expose.
+func agentToolDefs() []llm.Tool {
+	strProp := func(desc string) map[string]any {
+		return map[string]any{"type": "string", "description": desc}
+	}
+	return []llm.Tool{
+		{Type: "function", Function: llm.ToolFunction{
+			Name:        "ask_user",
+			Description: "Ask the user a question when you genuinely need a decision to proceed. The task pauses until the user answers; do not call other tools after this.",
+			Parameters: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"question": strProp("the question to ask, phrased as a real question"),
+					"options":  map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "optional suggested answer choices"},
+				},
+				"required": []string{"question"},
+			},
+		}},
+		{Type: "function", Function: llm.ToolFunction{
+			Name:        "report_summary",
+			Description: "Record a concise 2-5 sentence summary of what you accomplished. Call this before finishing.",
+			Parameters: map[string]any{
+				"type":       "object",
+				"properties": map[string]any{"summary": strProp("the summary text")},
+				"required":   []string{"summary"},
+			},
+		}},
+		{Type: "function", Function: llm.ToolFunction{
+			Name:        "spawn_subtask",
+			Description: "Create a child task to be executed separately. Use this to break large work into focused pieces.",
+			Parameters: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"name":           strProp("short descriptive name for the subtask"),
+					"instructions":   strProp("complete instructions for the subtask agent"),
+					"model":          strProp("optional model override"),
+					"max_budget_usd": map[string]any{"type": "number", "description": "optional budget cap in USD"},
+				},
+				"required": []string{"name", "instructions"},
+			},
+		}},
+		{Type: "function", Function: llm.ToolFunction{
+			Name:        "record_progress",
+			Description: "Record a short progress note that appears in the task timeline.",
+			Parameters: map[string]any{
+				"type":       "object",
+				"properties": map[string]any{"message": strProp("a short progress note")},
+				"required":   []string{"message"},
+			},
+		}},
+	}
+}
+
+// dispatchAgentTool invokes one model-requested tool against the AgentChannel.
+// It returns the text to feed back to the model as the tool result, and a
+// blocked flag set when ask_user could not be answered in-session (the run must
+// stop and the task block).
+func dispatchAgentTool(ctx context.Context, ch AgentChannel, name, argsJSON string) (result string, blocked bool, err error) {
+	switch name {
+	case "ask_user":
+		var a struct {
+			Question string   `json:"question"`
+			Options  []string `json:"options"`
+		}
+		_ = json.Unmarshal([]byte(argsJSON), &a)
+		q := map[string]any{"text": a.Question}
+		if len(a.Options) > 0 {
+			q["options"] = a.Options
+		}
+		payload, _ := json.Marshal(q)
+		ans, askErr := ch.AskUser(ctx, string(payload))
+		if errors.Is(askErr, ErrAgentBlocked) {
+			return "", true, nil
+		}
+		if askErr != nil {
+			return "", false, askErr
+		}
+		return ans, false, nil
+
+	case "report_summary":
+		var a struct {
+			Summary string `json:"summary"`
+		}
+		_ = json.Unmarshal([]byte(argsJSON), &a)
+		if rsErr := ch.ReportSummary(ctx, a.Summary); rsErr != nil {
+			return "", false, rsErr
+		}
+		return "Summary recorded.", false, nil
+
+	case "spawn_subtask":
+		var a struct {
+			Name         string  `json:"name"`
+			Instructions string  `json:"instructions"`
+			Model        string  `json:"model"`
+			MaxBudgetUSD float64 `json:"max_budget_usd"`
+		}
+		_ = json.Unmarshal([]byte(argsJSON), &a)
+		id, ssErr := ch.SpawnSubtask(ctx, SubtaskSpec{
+			Name:         a.Name,
+			Instructions: a.Instructions,
+			Model:        a.Model,
+			MaxBudgetUSD: a.MaxBudgetUSD,
+		})
+		if ssErr != nil {
+			return "", false, ssErr
+		}
+		return "Created subtask " + id, false, nil
+
+	case "record_progress":
+		var a struct {
+			Message string `json:"message"`
+		}
+		_ = json.Unmarshal([]byte(argsJSON), &a)
+		if rpErr := ch.RecordProgress(ctx, a.Message); rpErr != nil {
+			return "", false, rpErr
+		}
+		return "Noted.", false, nil
+
+	default:
+		return "", false, fmt.Errorf("unknown tool %q", name)
+	}
+}
diff --git a/internal/llm/client.go b/internal/llm/client.go
index 613ebe5..e3a6102 100644
--- a/internal/llm/client.go
+++ b/internal/llm/client.go
@@ -34,6 +34,38 @@ type Client struct {
 type Message struct {
 	Role    string `json:"role"`
 	Content string `json:"content"`
+	// ToolCalls is set on assistant messages that request tool invocations.
+	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
+	// ToolCallID links a role:"tool" result message to the call it answers.
+	ToolCallID string `json:"tool_call_id,omitempty"`
+	// Name carries the tool name on role:"tool" result messages.
+	Name string `json:"name,omitempty"`
+}
+
+// Tool declares a function the model may call (OpenAI function-calling format).
+type Tool struct {
+	Type     string       `json:"type"` // always "function"
+	Function ToolFunction `json:"function"`
+}
+
+// ToolFunction describes a callable function and its JSON-schema parameters.
+type ToolFunction struct {
+	Name        string         `json:"name"`
+	Description string         `json:"description"`
+	Parameters  map[string]any `json:"parameters,omitempty"`
+}
+
+// ToolCall is a function invocation the model emitted in its response.
+type ToolCall struct {
+	ID       string           `json:"id"`
+	Type     string           `json:"type"` // "function"
+	Function ToolCallFunction `json:"function"`
+}
+
+// ToolCallFunction holds the called function's name and raw JSON arguments.
+type ToolCallFunction struct {
+	Name      string `json:"name"`
+	Arguments string `json:"arguments"`
 }
 
 // ChatRequest captures the parameters of a single Chat or ChatStream call.
@@ -45,6 +77,7 @@ type ChatRequest struct {
 	Temperature  *float64
 	MaxTokens    int
 	ResponseJSON bool
+	Tools        []Tool
 }
 
 // ChatResponse is the aggregated result of a chat completion.
@@ -54,6 +87,7 @@ type ChatResponse struct {
 	OutputTokens int
 	Model        string
 	FinishReason string
+	ToolCalls    []ToolCall
 }
 
 // Chat performs a non-streaming chat completion. Rate-limit errors (HTTP 429,
@@ -87,6 +121,7 @@ func (c *Client) Chat(ctx context.Context, req ChatRequest) (*ChatResponse, erro
 			OutputTokens: oai.Usage.CompletionTokens,
 			Model:        oai.Model,
 			FinishReason: oai.Choices[0].FinishReason,
+			ToolCalls:    oai.Choices[0].Message.ToolCalls,
 		}
 		return nil
 	})
@@ -133,6 +168,7 @@ func (c *Client) buildRequestBody(req ChatRequest, stream bool) ([]byte, error)
 		Model:    model,
 		Messages: req.Messages,
 		Stream:   stream,
+		Tools:    req.Tools,
 	}
 	if req.Temperature != nil {
 		payload.Temperature = req.Temperature
@@ -301,6 +337,7 @@ type openAIRequest struct {
 	Stream         bool            `json:"stream,omitempty"`
 	StreamOptions  *streamOptions  `json:"stream_options,omitempty"`
 	ResponseFormat *responseFormat `json:"response_format,omitempty"`
+	Tools          []Tool          `json:"tools,omitempty"`
 }
 
 type streamOptions struct {
diff --git a/internal/llm/client_test.go b/internal/llm/client_test.go
index 8257836..7533a8a 100644
--- a/internal/llm/client_test.go
+++ b/internal/llm/client_test.go
@@ -157,3 +157,43 @@ func TestErrFromStatus_RateLimitMarker(t *testing.T) {
 		t.Errorf("error should embed retry-after, got: %v", err)
 	}
 }
+
+func TestChat_ToolsRoundTrip(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var body openAIRequest
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Fatalf("decode body: %v", err)
+		}
+		if len(body.Tools) != 1 || body.Tools[0].Function.Name != "do_thing" {
+			t.Errorf("tools not forwarded in request: %+v", body.Tools)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprintln(w, `{
+			"model": "m",
+			"choices": [{"message": {"role": "assistant", "content": "",
+				"tool_calls": [{"id": "call_1", "type": "function",
+					"function": {"name": "do_thing", "arguments": "{\"x\":1}"}}]},
+				"finish_reason": "tool_calls"}],
+			"usage": {"prompt_tokens": 3, "completion_tokens": 4}
+		}`)
+	}))
+	defer srv.Close()
+
+	c := &Client{Endpoint: srv.URL + "/v1", Model: "m"}
+	resp, err := c.Chat(context.Background(), ChatRequest{
+		Messages: []Message{{Role: "user", Content: "go"}},
+		Tools: []Tool{{Type: "function", Function: ToolFunction{
+			Name: "do_thing", Description: "d", Parameters: map[string]any{"type": "object"},
+		}}},
+	})
+	if err != nil {
+		t.Fatalf("Chat: %v", err)
+	}
+	if len(resp.ToolCalls) != 1 {
+		t.Fatalf("expected 1 tool call, got %d", len(resp.ToolCalls))
+	}
+	tc := resp.ToolCalls[0]
+	if tc.ID != "call_1" || tc.Function.Name != "do_thing" || tc.Function.Arguments != `{"x":1}` {
+		t.Errorf("unexpected tool call parsed: %+v", tc)
+	}
+}
-- 
cgit v1.2.3


From 561915c5182c3fb39cd6a8b6613c489b35b7c1bf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 26 May 2026 09:28:57 +0000
Subject: fix(executor): set IS_SANDBOX=1 so claude honors bypassPermissions
 under root
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The spike found that `claude --permission-mode bypassPermissions` (emitted by
buildInnerCmd) is rejected when the process runs as root, and buildDockerArgs
maps the container --user to the host uid — which is 0 when claudomator runs as
root, breaking all claude tool execution in production.

The container is an isolated sandbox, exactly the case the claude CLI gates
behind IS_SANDBOX=1; setting it in the container env makes bypassPermissions
work regardless of the host uid. Verified empirically against claude 2.1.150
(rejected as root without it; succeeds with it). Harmless for gemini containers.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/executor/container.go      | 4 ++++
 internal/executor/container_test.go | 1 +
 2 files changed, 5 insertions(+)

(limited to 'internal/executor')

diff --git a/internal/executor/container.go b/internal/executor/container.go
index 4f8fa06..f78715d 100644
--- a/internal/executor/container.go
+++ b/internal/executor/container.go
@@ -496,6 +496,10 @@ func (r *ContainerRunner) buildDockerArgs(workspace, claudeHome, taskID string)
 		"-w", "/workspace",
 		"--env-file", hostEnvFile,
 		"-e", "HOME=/home/agent",
+		// The container is an isolated sandbox; IS_SANDBOX=1 lets the claude CLI
+		// honor --permission-mode bypassPermissions even when the agent runs as
+		// root (buildDockerArgs maps --user to the host uid, which may be 0).
+		"-e", "IS_SANDBOX=1",
 		"-e", "CLAUDOMATOR_API_URL=" + apiURL,
 		"-e", "CLAUDOMATOR_TASK_ID=" + taskID,
 		"-e", "CLAUDOMATOR_DROP_DIR=" + r.DropsDir,
diff --git a/internal/executor/container_test.go b/internal/executor/container_test.go
index 521e1cb..5c3fd2e 100644
--- a/internal/executor/container_test.go
+++ b/internal/executor/container_test.go
@@ -37,6 +37,7 @@ func TestContainerRunner_BuildDockerArgs(t *testing.T) {
 		"-w", "/workspace",
 		"--env-file", "/tmp/ws/.claudomator-env",
 		"-e", "HOME=/home/agent",
+		"-e", "IS_SANDBOX=1",
 		"-e", "CLAUDOMATOR_API_URL=http://host.docker.internal:8484",
 		"-e", "CLAUDOMATOR_TASK_ID=task-123",
 		"-e", "CLAUDOMATOR_DROP_DIR=/data/drops",
-- 
cgit v1.2.3


From 39f74dbbc7adca0e2058112408bb99694deefcaf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 26 May 2026 20:27:36 +0000
Subject: feat(budget,storage,config): per-provider spend accounting substrate
 (Phase 6)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the budget accountant foundation:
- storage: a per-execution `agent` column (additive migration, populated by the
  dispatcher) and SpendByProviderSince(since), summing cost_usd per provider in
  a window. Accurate attribution survives a task running on different providers
  across retries.
- internal/budget: Accountant over a SpendSource + Limits, exposing Headroom
  (remaining/fraction per provider), Allow (would estCost breach the cap), and
  All (one query, sorted). Unconfigured/local providers are unlimited.
- config: a [budget] section (window + provider_5h_usd map). No default cap —
  gating is opt-in by configuring limits.

Fully unit-tested; dispatcher gating and the API/UI surface follow.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/budget/budget.go      | 122 +++++++++++++++++++++++++++++++++++++++++
 internal/budget/budget_test.go | 112 +++++++++++++++++++++++++++++++++++++
 internal/config/config.go      |  11 ++++
 internal/executor/executor.go  |   1 +
 internal/storage/db.go         |  50 +++++++++++++----
 internal/storage/db_test.go    |  38 +++++++++++++
 6 files changed, 324 insertions(+), 10 deletions(-)
 create mode 100644 internal/budget/budget.go
 create mode 100644 internal/budget/budget_test.go

(limited to 'internal/executor')

diff --git a/internal/budget/budget.go b/internal/budget/budget.go
new file mode 100644
index 0000000..60ce9d2
--- /dev/null
+++ b/internal/budget/budget.go
@@ -0,0 +1,122 @@
+// Package budget tracks agent spend against rolling per-provider windows so the
+// dispatcher can refuse (or reroute) paid work that would breach a cap. Local
+// runners are free and simply carry no configured limit.
+package budget
+
+import (
+	"sort"
+	"time"
+)
+
+// DefaultWindow is the rolling spend window when none is configured.
+const DefaultWindow = 5 * time.Hour
+
+// Limits configures per-provider spend caps within a rolling window.
+type Limits struct {
+	// Window is the rolling lookback; DefaultWindow when zero.
+	Window time.Duration
+	// PerProvider maps a provider (claude/gemini/…) to its USD cap within the
+	// window. A missing or non-positive entry means "unlimited" (e.g. local).
+	PerProvider map[string]float64
+}
+
+// SpendSource supplies total spend per provider since a given time.
+type SpendSource interface {
+	SpendByProviderSince(since time.Time) (map[string]float64, error)
+}
+
+// Headroom describes remaining budget for one provider in the current window.
+type Headroom struct {
+	Provider  string  `json:"provider"`
+	Limited   bool    `json:"limited"`
+	Limit     float64 `json:"limit_usd"`
+	Spent     float64 `json:"spent_usd"`
+	Remaining float64 `json:"remaining_usd"`
+	// Fraction is the share of the cap still available, 0..1 (0 when unlimited).
+	Fraction float64 `json:"fraction_remaining"`
+}
+
+// Accountant answers spend questions against a SpendSource and Limits.
+type Accountant struct {
+	src SpendSource
+	lim Limits
+	now func() time.Time
+}
+
+// New builds an Accountant. A zero Window defaults to DefaultWindow.
+func New(src SpendSource, lim Limits) *Accountant {
+	if lim.Window <= 0 {
+		lim.Window = DefaultWindow
+	}
+	return &Accountant{src: src, lim: lim, now: time.Now}
+}
+
+func (a *Accountant) since() time.Time { return a.now().Add(-a.lim.Window) }
+
+func (a *Accountant) headroomFrom(provider string, spends map[string]float64) Headroom {
+	limit := a.lim.PerProvider[provider]
+	if limit <= 0 {
+		return Headroom{Provider: provider, Limited: false}
+	}
+	spent := spends[provider]
+	remaining := limit - spent
+	if remaining < 0 {
+		remaining = 0
+	}
+	return Headroom{
+		Provider:  provider,
+		Limited:   true,
+		Limit:     limit,
+		Spent:     spent,
+		Remaining: remaining,
+		Fraction:  remaining / limit,
+	}
+}
+
+// Headroom returns the remaining budget for one provider in the current window.
+func (a *Accountant) Headroom(provider string) (Headroom, error) {
+	if a.lim.PerProvider[provider] <= 0 {
+		return Headroom{Provider: provider, Limited: false}, nil
+	}
+	spends, err := a.src.SpendByProviderSince(a.since())
+	if err != nil {
+		return Headroom{}, err
+	}
+	return a.headroomFrom(provider, spends), nil
+}
+
+// Allow reports whether starting a task on provider that may cost up to estCost
+// is permitted without breaching the window cap. Unlimited providers always
+// pass. estCost is typically the task's max_budget_usd (0 = unknown).
+func (a *Accountant) Allow(provider string, estCost float64) (bool, error) {
+	h, err := a.Headroom(provider)
+	if err != nil {
+		return false, err
+	}
+	if !h.Limited {
+		return true, nil
+	}
+	return h.Spent+estCost <= h.Limit, nil
+}
+
+// All returns headroom for every configured provider, sorted by name, in a
+// single spend query.
+func (a *Accountant) All() ([]Headroom, error) {
+	if len(a.lim.PerProvider) == 0 {
+		return []Headroom{}, nil
+	}
+	spends, err := a.src.SpendByProviderSince(a.since())
+	if err != nil {
+		return nil, err
+	}
+	providers := make([]string, 0, len(a.lim.PerProvider))
+	for p := range a.lim.PerProvider {
+		providers = append(providers, p)
+	}
+	sort.Strings(providers)
+	out := make([]Headroom, 0, len(providers))
+	for _, p := range providers {
+		out = append(out, a.headroomFrom(p, spends))
+	}
+	return out, nil
+}
diff --git a/internal/budget/budget_test.go b/internal/budget/budget_test.go
new file mode 100644
index 0000000..c257c91
--- /dev/null
+++ b/internal/budget/budget_test.go
@@ -0,0 +1,112 @@
+package budget
+
+import (
+	"testing"
+	"time"
+)
+
+type fakeSpend struct {
+	spends map[string]float64
+	since  time.Time
+}
+
+func (f *fakeSpend) SpendByProviderSince(since time.Time) (map[string]float64, error) {
+	f.since = since
+	return f.spends, nil
+}
+
+func newAcct(spends map[string]float64, lim Limits) (*Accountant, *fakeSpend) {
+	src := &fakeSpend{spends: spends}
+	a := New(src, lim)
+	a.now = func() time.Time { return time.Date(2026, 5, 26, 12, 0, 0, 0, time.UTC) }
+	return a, src
+}
+
+func TestNew_DefaultsWindow(t *testing.T) {
+	a, _ := newAcct(nil, Limits{})
+	if a.lim.Window != DefaultWindow {
+		t.Errorf("want default window %v, got %v", DefaultWindow, a.lim.Window)
+	}
+}
+
+func TestHeadroom_UnlimitedWhenNoLimit(t *testing.T) {
+	a, _ := newAcct(map[string]float64{"local": 999}, Limits{PerProvider: map[string]float64{"claude": 10}})
+	h, err := a.Headroom("local")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if h.Limited {
+		t.Errorf("local should be unlimited, got %+v", h)
+	}
+}
+
+func TestHeadroom_ComputesRemainingAndFraction(t *testing.T) {
+	a, src := newAcct(map[string]float64{"claude": 4}, Limits{Window: 5 * time.Hour, PerProvider: map[string]float64{"claude": 10}})
+	h, err := a.Headroom("claude")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !h.Limited || h.Limit != 10 || h.Spent != 4 || h.Remaining != 6 {
+		t.Errorf("unexpected headroom: %+v", h)
+	}
+	if h.Fraction != 0.6 {
+		t.Errorf("fraction: want 0.6, got %v", h.Fraction)
+	}
+	// Window lookback is now-5h.
+	want := time.Date(2026, 5, 26, 7, 0, 0, 0, time.UTC)
+	if !src.since.Equal(want) {
+		t.Errorf("since: want %v, got %v", want, src.since)
+	}
+}
+
+func TestHeadroom_ClampsNegativeRemaining(t *testing.T) {
+	a, _ := newAcct(map[string]float64{"claude": 15}, Limits{PerProvider: map[string]float64{"claude": 10}})
+	h, _ := a.Headroom("claude")
+	if h.Remaining != 0 {
+		t.Errorf("remaining should clamp to 0, got %v", h.Remaining)
+	}
+}
+
+func TestAllow(t *testing.T) {
+	a, _ := newAcct(map[string]float64{"claude": 8}, Limits{PerProvider: map[string]float64{"claude": 10}})
+
+	if ok, _ := a.Allow("claude", 1.5); !ok {
+		t.Error("8 + 1.5 <= 10 should be allowed")
+	}
+	if ok, _ := a.Allow("claude", 3); ok {
+		t.Error("8 + 3 > 10 should be denied")
+	}
+	if ok, _ := a.Allow("local", 1000); !ok {
+		t.Error("unlimited provider should always allow")
+	}
+}
+
+func TestAll_SortedAndSingleQuery(t *testing.T) {
+	a, src := newAcct(map[string]float64{"claude": 2, "gemini": 1},
+		Limits{PerProvider: map[string]float64{"gemini": 5, "claude": 10}})
+	calls := 0
+	orig := src.spends
+	a2 := New(&countingSpend{spends: orig, calls: &calls}, a.lim)
+	a2.now = a.now
+
+	hs, err := a2.All()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(hs) != 2 || hs[0].Provider != "claude" || hs[1].Provider != "gemini" {
+		t.Errorf("want [claude gemini] sorted, got %+v", hs)
+	}
+	if calls != 1 {
+		t.Errorf("All should issue exactly one spend query, got %d", calls)
+	}
+}
+
+type countingSpend struct {
+	spends map[string]float64
+	calls  *int
+}
+
+func (c *countingSpend) SpendByProviderSince(time.Time) (map[string]float64, error) {
+	*c.calls++
+	return c.spends, nil
+}
diff --git a/internal/config/config.go b/internal/config/config.go
index 94f3ec7..58de95c 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -69,6 +69,17 @@ type Config struct {
 	VAPIDEmail       string        `toml:"vapid_email"`
 	ClaudeConfigDir  string        `toml:"claude_config_dir"`
 	LocalModel       LocalModel    `toml:"local_model"`
+	Budget           BudgetConfig  `toml:"budget"`
+}
+
+// BudgetConfig configures rolling per-provider spend caps. With no providers
+// set, budget gating is disabled (nothing is blocked) — there is intentionally
+// no default cap; the user must opt in by configuring limits.
+type BudgetConfig struct {
+	// Window is the rolling lookback duration (e.g. "5h"); defaults to 5h.
+	Window string `toml:"window"`
+	// Provider5hUSD maps a provider (claude/gemini) to its USD cap within Window.
+	Provider5hUSD map[string]float64 `toml:"provider_5h_usd"`
 }
 
 func Default() (*Config, error) {
diff --git a/internal/executor/executor.go b/internal/executor/executor.go
index 6d6c528..4333f51 100644
--- a/internal/executor/executor.go
+++ b/internal/executor/executor.go
@@ -1025,6 +1025,7 @@ func (p *Pool) execute(ctx context.Context, t *task.Task) {
 		TaskID:    t.ID,
 		StartTime: time.Now().UTC(),
 		Status:    "RUNNING",
+		Agent:     agentType,
 	}
 
 	// Pre-populate log paths so they're available in the DB immediately —
diff --git a/internal/storage/db.go b/internal/storage/db.go
index adb7c02..e03a902 100644
--- a/internal/storage/db.go
+++ b/internal/storage/db.go
@@ -140,6 +140,7 @@ func (s *DB) migrate() error {
 		`ALTER TABLE tasks ADD COLUMN checker_report TEXT NOT NULL DEFAULT ''`,
 		`ALTER TABLE executions ADD COLUMN tokens_in INTEGER`,
 		`ALTER TABLE executions ADD COLUMN tokens_out INTEGER`,
+		`ALTER TABLE executions ADD COLUMN agent TEXT`,
 		`CREATE TABLE IF NOT EXISTS events (
 			id TEXT PRIMARY KEY,
 			task_id TEXT NOT NULL,
@@ -536,6 +537,7 @@ type Execution struct {
 	ErrorMsg    string
 	SessionID  string // claude --session-id; persisted for resume
 	SandboxDir string // preserved sandbox path when task is BLOCKED; resume must run here
+	Agent      string // provider that ran this execution (claude/gemini/local); for budget accounting
 
 	Changestats *task.Changestats // stored as JSON; nil if not yet recorded
 	Commits     []task.GitCommit // stored as JSON; empty if no commits
@@ -584,10 +586,10 @@ func (s *DB) CreateExecutionAndSetRunning(e *Execution) error {
 		commitsJSON = string(b)
 	}
 	if _, err := tx.Exec(`
-		INSERT INTO executions (id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json)
-		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)`,
+		INSERT INTO executions (id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, agent)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)`,
 		e.ID, e.TaskID, e.StartTime.UTC(), e.EndTime.UTC(), e.ExitCode, e.Status,
-		e.StdoutPath, e.StderrPath, e.ArtifactDir, e.CostUSD, e.ErrorMsg, e.SessionID, e.SandboxDir, commitsJSON,
+		e.StdoutPath, e.StderrPath, e.ArtifactDir, e.CostUSD, e.ErrorMsg, e.SessionID, e.SandboxDir, commitsJSON, e.Agent,
 	); err != nil {
 		return err
 	}
@@ -601,6 +603,32 @@ func (s *DB) CreateExecutionAndSetRunning(e *Execution) error {
 	return tx.Commit()
 }
 
+// SpendByProviderSince returns total cost_usd per provider (executions.agent)
+// for executions started at or after `since`. Executions with no recorded agent
+// are grouped under the empty string and can be ignored by callers.
+func (s *DB) SpendByProviderSince(since time.Time) (map[string]float64, error) {
+	rows, err := s.db.Query(`
+		SELECT COALESCE(agent, ''), COALESCE(SUM(cost_usd), 0)
+		FROM executions
+		WHERE start_time >= ?
+		GROUP BY agent`, since.UTC())
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	out := make(map[string]float64)
+	for rows.Next() {
+		var agent string
+		var cost float64
+		if err := rows.Scan(&agent, &cost); err != nil {
+			return nil, err
+		}
+		out[agent] = cost
+	}
+	return out, rows.Err()
+}
+
 // CreateExecution inserts an execution record.
 func (s *DB) CreateExecution(e *Execution) error {
 	var changestatsJSON *string
@@ -621,23 +649,23 @@ func (s *DB) CreateExecution(e *Execution) error {
 		commitsJSON = string(b)
 	}
 	_, err := s.db.Exec(`
-		INSERT INTO executions (id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, tokens_in, tokens_out)
-		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		INSERT INTO executions (id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, tokens_in, tokens_out, agent)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 		e.ID, e.TaskID, e.StartTime.UTC(), e.EndTime.UTC(), e.ExitCode, e.Status,
-		e.StdoutPath, e.StderrPath, e.ArtifactDir, e.CostUSD, e.ErrorMsg, e.SessionID, e.SandboxDir, changestatsJSON, commitsJSON, e.TokensIn, e.TokensOut,
+		e.StdoutPath, e.StderrPath, e.ArtifactDir, e.CostUSD, e.ErrorMsg, e.SessionID, e.SandboxDir, changestatsJSON, commitsJSON, e.TokensIn, e.TokensOut, e.Agent,
 	)
 	return err
 }
 
 // GetExecution retrieves an execution by ID.
 func (s *DB) GetExecution(id string) (*Execution, error) {
-	row := s.db.QueryRow(`SELECT id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, tokens_in, tokens_out FROM executions WHERE id = ?`, id)
+	row := s.db.QueryRow(`SELECT id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, tokens_in, tokens_out, agent FROM executions WHERE id = ?`, id)
 	return scanExecution(row)
 }
 
 // ListExecutions returns executions for a task.
 func (s *DB) ListExecutions(taskID string) ([]*Execution, error) {
-	rows, err := s.db.Query(`SELECT id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, tokens_in, tokens_out FROM executions WHERE task_id = ? ORDER BY start_time DESC`, taskID)
+	rows, err := s.db.Query(`SELECT id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, tokens_in, tokens_out, agent FROM executions WHERE task_id = ? ORDER BY start_time DESC`, taskID)
 	if err != nil {
 		return nil, err
 	}
@@ -656,7 +684,7 @@ func (s *DB) ListExecutions(taskID string) ([]*Execution, error) {
 
 // GetLatestExecution returns the most recent execution for a task.
 func (s *DB) GetLatestExecution(taskID string) (*Execution, error) {
-	row := s.db.QueryRow(`SELECT id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, tokens_in, tokens_out FROM executions WHERE task_id = ? ORDER BY start_time DESC LIMIT 1`, taskID)
+	row := s.db.QueryRow(`SELECT id, task_id, start_time, end_time, exit_code, status, stdout_path, stderr_path, artifact_dir, cost_usd, error_msg, session_id, sandbox_dir, changestats_json, commits_json, tokens_in, tokens_out, agent FROM executions WHERE task_id = ? ORDER BY start_time DESC LIMIT 1`, taskID)
 	return scanExecution(row)
 }
 
@@ -1137,8 +1165,9 @@ func scanExecution(row scanner) (*Execution, error) {
 	var commitsJSON sql.NullString
 	var tokensIn sql.NullInt64
 	var tokensOut sql.NullInt64
+	var agent sql.NullString
 	err := row.Scan(&e.ID, &e.TaskID, &e.StartTime, &e.EndTime, &e.ExitCode, &e.Status,
-		&e.StdoutPath, &e.StderrPath, &e.ArtifactDir, &e.CostUSD, &e.ErrorMsg, &sessionID, &sandboxDir, &changestatsJSON, &commitsJSON, &tokensIn, &tokensOut)
+		&e.StdoutPath, &e.StderrPath, &e.ArtifactDir, &e.CostUSD, &e.ErrorMsg, &sessionID, &sandboxDir, &changestatsJSON, &commitsJSON, &tokensIn, &tokensOut, &agent)
 	if err != nil {
 		return nil, err
 	}
@@ -1146,6 +1175,7 @@ func scanExecution(row scanner) (*Execution, error) {
 	e.SandboxDir = sandboxDir.String
 	e.TokensIn = tokensIn.Int64
 	e.TokensOut = tokensOut.Int64
+	e.Agent = agent.String
 	if changestatsJSON.Valid && changestatsJSON.String != "" {
 		var cs task.Changestats
 		if err := json.Unmarshal([]byte(changestatsJSON.String), &cs); err != nil {
diff --git a/internal/storage/db_test.go b/internal/storage/db_test.go
index 0e67e02..4d744a4 100644
--- a/internal/storage/db_test.go
+++ b/internal/storage/db_test.go
@@ -309,6 +309,44 @@ func TestListTasks_WithLimit(t *testing.T) {
 	}
 }
 
+func TestSpendByProviderSince(t *testing.T) {
+	db := testDB(t)
+	now := time.Now().UTC()
+
+	tk := &task.Task{
+		ID: "spend-task", Name: "S", Agent: task.AgentConfig{Type: "claude", Instructions: "x"},
+		Priority: task.PriorityNormal, Retry: task.RetryConfig{MaxAttempts: 1, Backoff: "linear"},
+		Tags: []string{}, DependsOn: []string{}, State: task.StatePending, CreatedAt: now, UpdatedAt: now,
+	}
+	if err := db.CreateTask(tk); err != nil {
+		t.Fatal(err)
+	}
+
+	// Two recent claude execs, one recent gemini, one old claude (outside window).
+	execs := []*Execution{
+		{ID: "s1", TaskID: "spend-task", StartTime: now.Add(-1 * time.Hour), Status: "COMPLETED", CostUSD: 1.5, Agent: "claude"},
+		{ID: "s2", TaskID: "spend-task", StartTime: now.Add(-2 * time.Hour), Status: "COMPLETED", CostUSD: 2.0, Agent: "claude"},
+		{ID: "s3", TaskID: "spend-task", StartTime: now.Add(-30 * time.Minute), Status: "COMPLETED", CostUSD: 0.75, Agent: "gemini"},
+		{ID: "s4", TaskID: "spend-task", StartTime: now.Add(-10 * time.Hour), Status: "COMPLETED", CostUSD: 99, Agent: "claude"},
+	}
+	for _, e := range execs {
+		if err := db.CreateExecution(e); err != nil {
+			t.Fatalf("create exec %s: %v", e.ID, err)
+		}
+	}
+
+	spends, err := db.SpendByProviderSince(now.Add(-5 * time.Hour))
+	if err != nil {
+		t.Fatalf("SpendByProviderSince: %v", err)
+	}
+	if got := spends["claude"]; got != 3.5 {
+		t.Errorf("claude spend: want 3.5 (old $99 excluded), got %v", got)
+	}
+	if got := spends["gemini"]; got != 0.75 {
+		t.Errorf("gemini spend: want 0.75, got %v", got)
+	}
+}
+
 func TestCreateExecution_AndGet(t *testing.T) {
 	db := testDB(t)
 	now := time.Now().UTC().Truncate(time.Second)
-- 
cgit v1.2.3


From 32715355fe2eed321df4f7083dfe580d35f8a62a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 26 May 2026 20:31:24 +0000
Subject: feat(executor): budget-gate the dispatcher — reroute to local or
 block (Phase 6)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The pool now consults a BudgetGate before taking an agent slot. If running on
the chosen paid provider could breach its rolling window (estimated by the
task's max_budget_usd), it reroutes to the free local runner when one is
registered; otherwise it stops before running and marks the task
BUDGET_EXCEEDED. serve.go builds a budget.Accountant from [budget] config and
wires it into the pool (only when limits are configured).

Allows the QUEUED → BUDGET_EXCEEDED transition, since the gate blocks a queued
task before it ever reaches RUNNING. Covered by pool tests for both the block
and reroute paths against a fake gate.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/cli/serve.go              | 18 ++++++++++++
 internal/executor/executor.go      | 46 ++++++++++++++++++++++++++++++
 internal/executor/executor_test.go | 57 ++++++++++++++++++++++++++++++++++++++
 internal/task/task.go              |  2 +-
 4 files changed, 122 insertions(+), 1 deletion(-)

(limited to 'internal/executor')

diff --git a/internal/cli/serve.go b/internal/cli/serve.go
index e545763..55fdaf5 100644
--- a/internal/cli/serve.go
+++ b/internal/cli/serve.go
@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/thepeterstone/claudomator/internal/api"
+	"github.com/thepeterstone/claudomator/internal/budget"
 	"github.com/thepeterstone/claudomator/internal/executor"
 	"github.com/thepeterstone/claudomator/internal/notify"
 	"github.com/thepeterstone/claudomator/internal/storage"
@@ -144,6 +145,23 @@ func serve(addr string) error {
 		pool.LLM = localClient
 	}
 
+	// Budget accountant: gate paid providers against rolling per-provider caps.
+	// With no limits configured this is created but allows everything.
+	var accountant *budget.Accountant
+	if len(cfg.Budget.Provider5hUSD) > 0 {
+		window := budget.DefaultWindow
+		if cfg.Budget.Window != "" {
+			if d, derr := time.ParseDuration(cfg.Budget.Window); derr == nil {
+				window = d
+			} else {
+				logger.Warn("invalid budget.window; using default", "value", cfg.Budget.Window, "default", window)
+			}
+		}
+		accountant = budget.New(store, budget.Limits{Window: window, PerProvider: cfg.Budget.Provider5hUSD})
+		pool.Budget = accountant
+		logger.Info("budget gating enabled", "window", window, "limits", cfg.Budget.Provider5hUSD)
+	}
+
 	if err := store.SeedProjects(); err != nil {
 		logger.Error("failed to seed projects", "error", err)
 	}
diff --git a/internal/executor/executor.go b/internal/executor/executor.go
index 4333f51..8614481 100644
--- a/internal/executor/executor.go
+++ b/internal/executor/executor.go
@@ -93,6 +93,14 @@ type Pool struct {
 	dispatchDone        chan struct{}      // closed when the dispatch goroutine exits
 	Classifier          *Classifier
 	LLM                 *llm.Client
+	// Budget gates paid providers against a rolling window; nil disables gating.
+	Budget BudgetGate
+}
+
+// BudgetGate reports whether a task estimated at estCost may run on a provider
+// without breaching its rolling spend window. Satisfied by *budget.Accountant.
+type BudgetGate interface {
+	Allow(provider string, estCost float64) (bool, error)
 }
 
 // Result is emitted when a task execution completes.
@@ -937,6 +945,44 @@ func (p *Pool) execute(ctx context.Context, t *task.Task) {
 		agentType = "claude"
 	}
 
+	// Budget gating: if running on this provider could breach its rolling window
+	// (estimated by the task's max_budget_usd), reroute to the free local runner
+	// when one is registered, otherwise stop and mark the task BUDGET_EXCEEDED.
+	if p.Budget != nil {
+		if ok, berr := p.Budget.Allow(agentType, t.Agent.MaxBudgetUSD); berr != nil {
+			p.logger.Warn("budget check failed; proceeding", "error", berr, "taskID", t.ID)
+		} else if !ok {
+			if _, hasLocal := p.runners["local"]; hasLocal && agentType != "local" {
+				p.logger.Info("budget window would be breached; rerouting to local", "taskID", t.ID, "from", agentType)
+				t.Agent.Type = "local"
+				t.Agent.Model = ""
+				agentType = "local"
+				if uerr := p.store.UpdateTaskAgent(t.ID, t.Agent); uerr != nil {
+					p.logger.Error("failed to persist rerouted agent", "error", uerr, "taskID", t.ID)
+				}
+			} else {
+				now := time.Now().UTC()
+				exec := &storage.Execution{
+					ID:        uuid.New().String(),
+					TaskID:    t.ID,
+					StartTime: now,
+					EndTime:   now,
+					Status:    "BUDGET_EXCEEDED",
+					Agent:     agentType,
+					ErrorMsg:  fmt.Sprintf("rolling budget window cap reached for provider %q", agentType),
+				}
+				if createErr := p.store.CreateExecution(exec); createErr != nil {
+					p.logger.Error("failed to create execution record", "error", createErr)
+				}
+				if err := p.store.UpdateTaskState(t.ID, task.StateBudgetExceeded); err != nil {
+					p.logger.Error("failed to update task state", "taskID", t.ID, "state", task.StateBudgetExceeded, "error", err)
+				}
+				p.resultCh <- &Result{TaskID: t.ID, Execution: exec, Err: fmt.Errorf("budget cap reached for %s", agentType)}
+				return
+			}
+		}
+	}
+
 	// Check dependencies before taking the per-agent slot to avoid deadlock:
 	// if a dependent task holds the slot while waiting for its dependency to run,
 	// the dependency can never start (maxPerAgent=1).
diff --git a/internal/executor/executor_test.go b/internal/executor/executor_test.go
index d98efbf..b737e22 100644
--- a/internal/executor/executor_test.go
+++ b/internal/executor/executor_test.go
@@ -217,6 +217,63 @@ func TestPool_Submit_Subtask_GoesToCompleted(t *testing.T) {
 	}
 }
 
+type fakeGate struct{ deny map[string]bool }
+
+func (g fakeGate) Allow(provider string, _ float64) (bool, error) { return !g.deny[provider], nil }
+
+func TestPool_BudgetGate_BlocksWhenNoLocalFallback(t *testing.T) {
+	store := testStore(t)
+	runner := &mockRunner{}
+	pool := NewPool(2, map[string]Runner{"claude": runner}, store, slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})))
+	pool.Budget = fakeGate{deny: map[string]bool{"claude": true}}
+
+	tk := makeTask("bg-1")
+	store.CreateTask(tk)
+	if err := pool.Submit(context.Background(), tk); err != nil {
+		t.Fatalf("submit: %v", err)
+	}
+
+	result := <-pool.Results()
+	if result.Execution.Status != "BUDGET_EXCEEDED" {
+		t.Errorf("status: want BUDGET_EXCEEDED, got %q", result.Execution.Status)
+	}
+	if runner.callCount() != 0 {
+		t.Errorf("claude runner should not have run, got %d calls", runner.callCount())
+	}
+	got, _ := store.GetTask("bg-1")
+	if got.State != task.StateBudgetExceeded {
+		t.Errorf("task state: want BUDGET_EXCEEDED, got %v", got.State)
+	}
+}
+
+func TestPool_BudgetGate_ReroutesToLocal(t *testing.T) {
+	store := testStore(t)
+	claudeRunner := &mockRunner{}
+	localRunner := &mockRunner{}
+	pool := NewPool(2, map[string]Runner{"claude": claudeRunner, "local": localRunner}, store, slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})))
+	pool.Budget = fakeGate{deny: map[string]bool{"claude": true}} // local is allowed
+
+	tk := makeTask("bg-2")
+	store.CreateTask(tk)
+	if err := pool.Submit(context.Background(), tk); err != nil {
+		t.Fatalf("submit: %v", err)
+	}
+
+	result := <-pool.Results()
+	if result.Err != nil {
+		t.Errorf("expected success after reroute, got %v", result.Err)
+	}
+	if localRunner.callCount() != 1 {
+		t.Errorf("local runner should have run once, got %d", localRunner.callCount())
+	}
+	if claudeRunner.callCount() != 0 {
+		t.Errorf("claude runner should not have run, got %d", claudeRunner.callCount())
+	}
+	if result.Execution.Agent != "local" {
+		t.Errorf("execution agent: want local, got %q", result.Execution.Agent)
+	}
+}
+
 func TestPool_Submit_Failure(t *testing.T) {
 	store := testStore(t)
 	runner := &mockRunner{err: fmt.Errorf("boom"), exitCode: 1}
diff --git a/internal/task/task.go b/internal/task/task.go
index 935a238..eeac49e 100644
--- a/internal/task/task.go
+++ b/internal/task/task.go
@@ -138,7 +138,7 @@ type BatchFile struct {
 // BLOCKED may advance to READY when all subtasks complete, or back to QUEUED on user answer.
 var validTransitions = map[State]map[State]bool{
 	StatePending:        {StateQueued: true, StateCancelled: true},
-	StateQueued:         {StateRunning: true, StateCancelled: true, StateReady: true}, // READY: parent task completed via subtask delegation
+	StateQueued:         {StateRunning: true, StateCancelled: true, StateReady: true, StateBudgetExceeded: true}, // READY: subtask delegation; BUDGET_EXCEEDED: dispatcher budget gate blocks before running
 	StateRunning:        {StateReady: true, StateCompleted: true, StateFailed: true, StateTimedOut: true, StateCancelled: true, StateBudgetExceeded: true, StateBlocked: true},
 	StateReady:          {StateCompleted: true, StatePending: true},
 	StateFailed:         {StateQueued: true}, // retry
-- 
cgit v1.2.3


From 1deee869e5cd0895e45016192dd70c0ed6c68cf3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 27 May 2026 05:42:31 +0000
Subject: refactor(executor): retire the file-based question/summary fallback
 (Phase 8)

With the MCP agent channel validated (the spike confirmed real claude calls
ask_user/report_summary through it), the container runner no longer needs the
pre-MCP file fallback that read question.json/summary.txt after the agent
exited. Removes that block and the now-orphaned isCompletionReport/
extractQuestionText helpers and their test. The MCP path
(channelPendingQuestion) is now the sole question/summary transport.

https://claude.ai/code/session_01SESwn7kQ7oP62trWw6pc39
---
 internal/executor/container.go      | 28 -------------------------
 internal/executor/container_test.go | 42 -------------------------------------
 internal/executor/helpers.go        | 26 -----------------------
 3 files changed, 96 deletions(-)

(limited to 'internal/executor')

diff --git a/internal/executor/container.go b/internal/executor/container.go
index f78715d..3afce70 100644
--- a/internal/executor/container.go
+++ b/internal/executor/container.go
@@ -403,34 +403,6 @@ func (r *ContainerRunner) runContainer(ctx context.Context, t *task.Task, e *sto
 		return &BlockedError{QuestionJSON: q, SessionID: e.SessionID, SandboxDir: workspace}
 	}
 
-	// Check whether the agent left a question before exiting (file fallback for
-	// in-flight tasks started on the pre-MCP wire).
-	questionFile := filepath.Join(logDir, "question.json")
-	if data, readErr := os.ReadFile(questionFile); readErr == nil {
-		os.Remove(questionFile) // consumed
-		questionJSON := strings.TrimSpace(string(data))
-		if isCompletionReport(questionJSON) {
-			r.Logger.Info("treating question file as completion report", "taskID", e.TaskID)
-			_ = ch.ReportSummary(ctx, extractQuestionText(questionJSON))
-		} else {
-			if e.SessionID == "" {
-				r.Logger.Warn("missing session ID; resume will start fresh", "taskID", e.TaskID)
-			}
-			return &BlockedError{
-				QuestionJSON: questionJSON,
-				SessionID:    e.SessionID,
-				SandboxDir:   workspace,
-			}
-		}
-	}
-
-	// Read agent summary if written.
-	summaryFile := filepath.Join(logDir, "summary.txt")
-	if summaryData, readErr := os.ReadFile(summaryFile); readErr == nil {
-		os.Remove(summaryFile) // consumed
-		_ = ch.ReportSummary(ctx, strings.TrimSpace(string(summaryData)))
-	}
-
 	// 5. Post-execution: push changes if successful
 	if waitErr == nil && streamErr == nil {
 		// Check if there are any commits to push (HEAD ahead of origin/HEAD).
diff --git a/internal/executor/container_test.go b/internal/executor/container_test.go
index 5c3fd2e..26e67bc 100644
--- a/internal/executor/container_test.go
+++ b/internal/executor/container_test.go
@@ -269,48 +269,6 @@ func TestBlockedError_IncludesSandboxDir(t *testing.T) {
 	}
 }
 
-func TestIsCompletionReport(t *testing.T) {
-	tests := []struct {
-		name     string
-		json     string
-		expected bool
-	}{
-		{
-			name:     "real question with options",
-			json:     `{"text": "Should I proceed with implementation?", "options": ["Yes", "No"]}`,
-			expected: false,
-		},
-		{
-			name:     "real question no options",
-			json:     `{"text": "Which approach do you prefer?"}`,
-			expected: false,
-		},
-		{
-			name:     "completion report no options no question mark",
-			json:     `{"text": "All tests pass. Implementation complete. Summary written to CLAUDOMATOR_SUMMARY_FILE."}`,
-			expected: true,
-		},
-		{
-			name:     "completion report with empty options",
-			json:     `{"text": "Feature implemented and committed.", "options": []}`,
-			expected: true,
-		},
-		{
-			name:     "invalid json treated as not a report",
-			json:     `not json`,
-			expected: false,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := isCompletionReport(tt.json)
-			if got != tt.expected {
-				t.Errorf("isCompletionReport(%q) = %v, want %v", tt.json, got, tt.expected)
-			}
-		})
-	}
-}
-
 func TestTailFile_ReturnsLastNLines(t *testing.T) {
 	f, err := os.CreateTemp("", "tailfile-*")
 	if err != nil {
diff --git a/internal/executor/helpers.go b/internal/executor/helpers.go
index 76bf8b1..9517492 100644
--- a/internal/executor/helpers.go
+++ b/internal/executor/helpers.go
@@ -177,29 +177,3 @@ func gitSafe(args ...string) []string {
 		"-c", "tag.gpgsign=false",
 	}, args...)
 }
-
-// isCompletionReport returns true when a question-file JSON looks like a
-// completion report rather than a real user question. Heuristic: no options
-// (or empty options) and no "?" anywhere in the text.
-func isCompletionReport(questionJSON string) bool {
-	var q struct {
-		Text    string   `json:"text"`
-		Options []string `json:"options"`
-	}
-	if err := json.Unmarshal([]byte(questionJSON), &q); err != nil {
-		return false
-	}
-	return len(q.Options) == 0 && !strings.Contains(q.Text, "?")
-}
-
-// extractQuestionText returns the "text" field from a question-file JSON, or
-// the raw string if parsing fails.
-func extractQuestionText(questionJSON string) string {
-	var q struct {
-		Text string `json:"text"`
-	}
-	if err := json.Unmarshal([]byte(questionJSON), &q); err != nil {
-		return questionJSON
-	}
-	return strings.TrimSpace(q.Text)
-}
-- 
cgit v1.2.3