feat: rename /bg to /research (read-only) + ralph auto-worktree

Two changes that cleanly separate read vs write background tasks:

/research (formerly /bg): Now restricted to read-only tools
(Read, Glob, Grep, WebSearch, WebFetch) via --allowedTools.
Safe for analysis/investigation without risk of modifying code.

/ralph: Now automatically creates a git worktree on first iteration
via --worktree flag. All file modifications happen in an isolated
branch, protecting the main codebase. Branch persists after
completion for user review and merge.

- ExecuteOptions.Worktree field added to executor
- researchAllowedTools enforced in both Phase 1 and Phase 2
- Ralph progress/result messages show branch info

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: GrapeInTheTree

internal/bot/commands.go

@@ -41,8 +41,8 @@ func (b *Bot) handleCommand(msg *tgbotapi.Message) {
 		b.cmdRetry()
 	case "project":
 		b.cmdProject(msg.CommandArguments())
-	case "bg":
-		b.cmdBg(msg)
+	case "research":
+		b.cmdResearch(msg)
 	case "ralph":
 		b.cmdRalph(msg)
 	case "plan":
@@ -68,12 +68,12 @@ func (b *Bot) cmdHelp() {
 		"/project search `<keyword>` — Find git repos to add\n" +
 		"/project rename `<old>` `<new>` — Rename project\n" +
 		"/project remove `<name>` — Remove project\n\n" +
-		"*Background:*\n" +
-		"/bg `<message>` — Run task in background\n" +
-		"/bg inject `<id>` — Inject result into session\n" +
-		"/bg status / cancel `<id>`\n\n" +
-		"*Ralph (Iterative Loop):*\n" +
-		"/ralph `<message>` — Auto-loop until done\n" +
+		"*Research (read-only):*\n" +
+		"/research `<message>` — Background analysis\n" +
+		"/research inject `<id>` — Inject result into session\n" +
+		"/research status / cancel `<id>`\n\n" +
+		"*Ralph (iterative loop + worktree):*\n" +
+		"/ralph `<message>` — Auto-loop in isolated branch\n" +
 		"/ralph `<msg>` --max `<N>` — Set max iterations\n" +
 		"/ralph status / cancel `<id>`\n\n" +
 		"*Plan Mode:*\n" +
@@ -506,7 +506,7 @@ func (b *Bot) cmdProjectSearch(keyword string) {
 	}
 }
 
-func (b *Bot) cmdBg(msg *tgbotapi.Message) {
+func (b *Bot) cmdResearch(msg *tgbotapi.Message) {
 	if b.worker == nil {
 		return
 	}
@@ -516,13 +516,13 @@ func (b *Bot) cmdBg(msg *tgbotapi.Message) {
 	// /bg → help
 	if args == "" {
 		b.sendMarkdown(
-			"🔄 *Background Tasks*\n\n" +
-				"`/bg <message>` — Run in current project\n" +
-				"`/bg <project> <message>` — Run in specific project\n" +
-				"`/bg status` — Show running tasks\n" +
-				"`/bg inject <id>` — Inject result into session\n" +
-				"`/bg cancel <id>` — Cancel a task\n\n" +
-				"Background tasks run independently.\n" +
+			"🔍 *Research (read-only)*\n\n" +
+				"`/research <message>` — Analyze in background\n" +
+				"`/research <project> <message>` — In specific project\n" +
+				"`/research status` — Show running tasks\n" +
+				"`/research inject <id>` — Inject result into session\n" +
+				"`/research cancel <id>` — Cancel a task\n\n" +
+				"Read-only analysis. No file modifications.\n" +
 				"Use inject to bring results into your conversation.")
 		return
 	}
@@ -537,7 +537,7 @@ func (b *Bot) cmdBg(msg *tgbotapi.Message) {
 	if strings.HasPrefix(args, "inject ") {
 		taskID := strings.TrimSpace(strings.TrimPrefix(args, "inject"))
 		if taskID == "" {
-			b.sendMessage("Usage: /bg inject <task_id>")
+			b.sendMessage("Usage: /research inject <task_id>")
 			return
 		}
 		resultText, projectName, err := b.worker.GetBackgroundResult(taskID)
@@ -570,19 +570,19 @@ func (b *Bot) cmdBg(msg *tgbotapi.Message) {
 	if strings.HasPrefix(args, "cancel ") {
 		taskID := strings.TrimSpace(strings.TrimPrefix(args, "cancel"))
 		if taskID == "" {
-			b.sendMessage("Usage: /bg cancel <task_id>")
+			b.sendMessage("Usage: /research cancel <task_id>")
 			return
 		}
 		if err := b.worker.CancelBackground(taskID); err != nil {
 			b.sendMessage("Failed: " + err.Error())
 		} else {
-			b.sendMessage(fmt.Sprintf("🛑 Cancelled background task: %s", taskID))
+			b.sendMessage(fmt.Sprintf("🛑 Cancelled research task: %s", taskID))
 		}
 		return
 	}
 
 	// /bg <project> <message> or /bg <message>
-	projectName, message := b.parseBgArgs(args)
+	projectName, message := b.parseResearchArgs(args)
 
 	taskID, err := b.worker.EnqueueBackground(context.Background(), projectName, message)
 	if err != nil {
@@ -591,16 +591,16 @@ func (b *Bot) cmdBg(msg *tgbotapi.Message) {
 	}
 
 	b.sendMessage(fmt.Sprintf(
-		"🔄 Background task started\n🆔 %s\n📂 Project: %s\n💬 %s\n\nUse /bg status to check progress.",
+		"🔍 Research started\n🆔 %s\n📂 Project: %s\n💬 %s\n\nUse /research status to check progress.",
 		taskID, projectName, worker.Truncate(message, 60)))
 }
 
-// parseBgArgs splits args into project name and message.
+// parseResearchArgs splits args into project name and message.
 // If the first word matches a registered project (and it's different from
 // the active project), it's used as the target project. Otherwise the
 // entire string is the message for the active project.
 // This avoids misrouting when the active project name happens to be the first word.
-func (b *Bot) parseBgArgs(args string) (projectName, message string) {
+func (b *Bot) parseResearchArgs(args string) (projectName, message string) {
 	active := b.worker.ActiveProject()
 	parts := strings.SplitN(args, " ", 2)
 	if len(parts) == 2 {

internal/claude/executor.go

@@ -87,6 +87,7 @@ func NewProjectExecutor(cliPath, workDir string, addDirs []string, timeout time.
 type ExecuteOptions struct {
 	SkipPermissions bool
 	AllowedTools    []string // if non-empty, restricts tool access via --allowedTools
+	Worktree        string   // if non-empty, passes --worktree <name> to CLI
 }
 
 func (e *Executor) Execute(ctx context.Context, userMessage string, skipPermissions bool) (*store.CLIResult, error) {
@@ -120,6 +121,9 @@ func (e *Executor) ExecuteWithOptions(ctx context.Context, userMessage string, o
 	if len(opts.AllowedTools) > 0 {
 		args = append(args, "--allowedTools", strings.Join(opts.AllowedTools, ","))
 	}
+	if opts.Worktree != "" {
+		args = append(args, "--worktree", opts.Worktree)
+	}
 	if e.systemPrompt != "" {
 		args = append(args, "--system-prompt", e.systemPrompt)
 	}

internal/worker/background.go

@@ -10,12 +10,16 @@ import (
 	"sync/atomic"
 	"time"
 
+	"github.com/GrapeInTheTree/pocket-claude/internal/claude"
 	"github.com/GrapeInTheTree/pocket-claude/internal/project"
 	"github.com/GrapeInTheTree/pocket-claude/internal/store"
 )
 
 const maxBackgroundSlots = 3
 
+// researchAllowedTools restricts /research tasks to read-only tools.
+var researchAllowedTools = []string{"Read", "Glob", "Grep", "WebSearch", "WebFetch"}
+
 // taskCounter provides unique IDs without millisecond collisions.
 var taskCounter atomic.Int64
 
@@ -147,8 +151,10 @@ func (bp *BackgroundPool) run(ctx context.Context, task *BackgroundTask) {
 	go bp.sendTypingFn(typingCtx)
 	defer stopTyping()
 
-	// Phase 1: Execute with default permissions
-	result, err := exec.Execute(ctx, task.Message, false)
+	// Phase 1: Execute with read-only tools (research mode)
+	result, err := exec.ExecuteWithOptions(ctx, task.Message, claude.ExecuteOptions{
+		AllowedTools: researchAllowedTools,
+	})
 	if err != nil {
 		if ctx.Err() != nil {
 			bp.setTaskState(task.ID, "cancelled", "")
@@ -188,7 +194,10 @@ func (bp *BackgroundPool) run(ctx context.Context, task *BackgroundTask) {
 		defer stopTyping2()
 
 		bp.logger.Info("Background task approved, re-executing", "id", task.ID)
-		result, err = exec.Execute(ctx, task.Message, true)
+		result, err = exec.ExecuteWithOptions(ctx, task.Message, claude.ExecuteOptions{
+			SkipPermissions: true,
+			AllowedTools:    researchAllowedTools,
+		})
 		if err != nil {
 			if ctx.Err() != nil {
 				bp.setTaskState(task.ID, "cancelled", "")

internal/worker/ralph.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/GrapeInTheTree/pocket-claude/internal/claude"
 	"github.com/GrapeInTheTree/pocket-claude/internal/store"
 )
 
@@ -110,8 +111,12 @@ func (bp *BackgroundPool) runRalph(ctx context.Context, task *BackgroundTask) {
 		typingCtx, stopTyping := context.WithCancel(ctx)
 		go bp.sendTypingFn(typingCtx)
 
-		// Execute
-		result, err := exec.Execute(ctx, prompt, false)
+		// Execute (first iteration creates worktree, subsequent use --resume)
+		opts := claude.ExecuteOptions{}
+		if iteration == 1 {
+			opts.Worktree = task.ID
+		}
+		result, err := exec.ExecuteWithOptions(ctx, prompt, opts)
 		stopTyping()
 
 		if err != nil {
@@ -142,7 +147,11 @@ func (bp *BackgroundPool) runRalph(ctx context.Context, task *BackgroundTask) {
 
 			typingCtx2, stopTyping2 := context.WithCancel(ctx)
 			go bp.sendTypingFn(typingCtx2)
-			result, err = exec.Execute(ctx, prompt, true)
+			approvedOpts := claude.ExecuteOptions{SkipPermissions: true}
+			if iteration == 1 {
+				approvedOpts.Worktree = task.ID
+			}
+			result, err = exec.ExecuteWithOptions(ctx, prompt, approvedOpts)
 			stopTyping2()
 			if err != nil {
 				if ctx.Err() != nil {
@@ -209,8 +218,8 @@ func (bp *BackgroundPool) runRalph(ctx context.Context, task *BackgroundTask) {
 
 		// Progress update (use local copies)
 		summary := Truncate(result.Result, 100)
-		bp.sendFn(fmt.Sprintf("🔁 Ralph [%s] Iteration %d/%d\n📂 %s | 💰 $%.4f\n\n%s",
-			task.ID, iterNum, task.MaxIterations, task.Project, totalCost, summary))
+		bp.sendFn(fmt.Sprintf("🔁 Ralph [%s] Iteration %d/%d\n📂 %s | 🌿 %s | 💰 $%.4f\n\n%s",
+			task.ID, iterNum, task.MaxIterations, task.Project, task.ID, totalCost, summary))
 	}
 
 	// Max iterations reached
@@ -256,7 +265,8 @@ func (bp *BackgroundPool) sendRalphResult(task *BackgroundTask, result *store.CL
 
 	var sb strings.Builder
 	sb.WriteString(fmt.Sprintf("✅ Ralph Done (%d/%d iterations)\n", currentIter, maxIter))
-	sb.WriteString(fmt.Sprintf("📂 %s | 💰 $%.4f | ⏱ %s\n", task.Project, totalCost, elapsedStr))
+	sb.WriteString(fmt.Sprintf("📂 %s | 🌿 %s\n", task.Project, task.ID))
+	sb.WriteString(fmt.Sprintf("💰 $%.4f | ⏱ %s\n", totalCost, elapsedStr))
 	sb.WriteString(fmt.Sprintf("🏁 %s\n\n", reason))
 	sb.WriteString(response)