forge: Add NL classification, hook retry with agent fix, and lefthook bypass

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: shahar-caura

Makefile

@@ -27,6 +27,7 @@ lint:
 	golangci-lint run ./...
 
 fmt:
+	gofumpt -w .
 	goimports -w .
 
 vet:

cmd/forge/cmd_nl.go

@@ -11,13 +11,16 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// nlClassifying guards against classify → execute → classify recursion.
+var nlClassifying bool
+
 func runNaturalLanguage(cmd *cobra.Command, logger *slog.Logger, args []string) error {
 	if len(args) == 0 {
 		return cmd.Help()
 	}
 
 	// Recursion guard: prevent classify → execute → classify loops.
-	if os.Getenv("FORGE_NL_CLASSIFIED") == "1" {
+	if nlClassifying {
 		return fmt.Errorf("unknown command %q", args[0])
 	}
 
@@ -47,8 +50,8 @@ func runNaturalLanguage(cmd *cobra.Command, logger *slog.Logger, args []string)
 
 	fmt.Fprintf(os.Stderr, "=> forge %s\n", strings.Join(result.Argv, " "))
 
-	os.Setenv("FORGE_NL_CLASSIFIED", "1")
-	defer os.Unsetenv("FORGE_NL_CLASSIFIED")
+	nlClassifying = true
+	defer func() { nlClassifying = false }()
 
 	cmd.Root().SetArgs(result.Argv)
 	return cmd.Root().Execute()

cmd/forge/cmd_nl_test.go

@@ -0,0 +1,67 @@
+package main
+
+import (
+	"io"
+	"log/slog"
+	"strings"
+	"testing"
+)
+
+func TestRunNaturalLanguage_EmptyArgs(t *testing.T) {
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	root := newRootCmd(logger)
+
+	// Empty args should print help, not error.
+	err := runNaturalLanguage(root, logger, []string{})
+	if err != nil {
+		t.Fatalf("expected no error for empty args, got: %v", err)
+	}
+}
+
+func TestRunNaturalLanguage_RecursionGuard(t *testing.T) {
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	root := newRootCmd(logger)
+
+	nlClassifying = true
+	defer func() { nlClassifying = false }()
+
+	err := runNaturalLanguage(root, logger, []string{"something"})
+	if err == nil {
+		t.Fatal("expected error from recursion guard")
+	}
+	if !strings.Contains(err.Error(), "unknown command") {
+		t.Fatalf("expected 'unknown command' error, got: %v", err)
+	}
+}
+
+func TestRunNaturalLanguage_NoClaude(t *testing.T) {
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	root := newRootCmd(logger)
+
+	// Override PATH so claude is not found.
+	t.Setenv("PATH", "")
+
+	err := runNaturalLanguage(root, logger, []string{"run", "the", "auth", "plan"})
+	if err == nil {
+		t.Fatal("expected error when claude CLI is not available")
+	}
+	if !strings.Contains(err.Error(), "install claude CLI") {
+		t.Fatalf("expected 'install claude CLI' hint, got: %v", err)
+	}
+}
+
+func TestRootCmd_UnknownArgsTriggersNL(t *testing.T) {
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	root := newRootCmd(logger)
+
+	// Without claude in PATH, unknown args should trigger NL which falls back to error.
+	t.Setenv("PATH", "")
+	root.SetArgs([]string{"do", "something", "cool"})
+	err := root.Execute()
+	if err == nil {
+		t.Fatal("expected error for unknown args without claude CLI")
+	}
+	if !strings.Contains(err.Error(), "install claude CLI") {
+		t.Fatalf("expected NL classification error, got: %v", err)
+	}
+}

cmd/forge/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"fmt"
 	"log/slog"
 	"os"
 
@@ -17,6 +18,7 @@ func main() {
 	logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
 
 	if err := newRootCmd(logger).Execute(); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
 		os.Exit(1)
 	}
 }
@@ -27,6 +29,13 @@ func newRootCmd(logger *slog.Logger) *cobra.Command {
 		Short:         "Execute a development plan end-to-end",
 		SilenceUsage:  true,
 		SilenceErrors: true,
+		Args:          cobra.ArbitraryArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) == 0 {
+				return cmd.Help()
+			}
+			return runNaturalLanguage(cmd, logger, args)
+		},
 	}
 
 	root.PersistentFlags().String("agent", "", "override agent provider (e.g. claude, codex, gemini)")

forge.yaml.example

@@ -13,6 +13,7 @@ tracker:
   base_url: ${JIRA_URL}     # e.g. https://yourco.atlassian.net
   email: ${JIRA_EMAIL}
   token: ${JIRA_TOKEN}
+  # board_id: "123"         # Optional: Jira board ID
 
 notifier:
   provider: slack
@@ -21,14 +22,20 @@ notifier:
 agent:
   provider: claude          # claude, ralph, codex, gemini
   timeout: 45m              # Max time for agent execution
+  # providers:              # Optional: multi-agent pool for batch runs (round-robin + fallback).
+  #   - claude              # When set, overrides provider for batch; provider is still used
+  #   - gemini              # for single runs (forge run) and as default if providers is empty.
+  # allowed_tools: ""       # Optional: comma-separated tool allowlist (auto-set for ralph)
 
 worktree:
   create_cmd: "./scripts/git-worktree-add.sh {{.Branch}} {{.Path}} {{.BaseBranch}}"
   remove_cmd: "git worktree remove --force {{.Path}}"
   cleanup: true             # Remove worktree after PR is opened
+  cleanup_on_merge: false   # Automatically remove worktree when PR is merged
 
 hooks:
   pre_commit: "make fmt && make vet"  # Run before pushing commits
+  max_hook_retries: 2                 # Agent retry attempts on hook failure (0 = fail fast)
 
 state:
   retention: 168h             # How long to keep completed run states (7 days)
@@ -43,6 +50,9 @@ cr:
   # comment_pattern: ""       # Regex to match CR bot comment (poll mode only)
   # fix_strategy: amend       # "amend" or "new-commit"
 
+server:
+  # port: 8080               # Dashboard HTTP server port
+
 editor:
   enabled: false              # Open editor automatically on forge edit
   command: code               # Editor command (forge edit)

internal/config/config.go

@@ -48,7 +48,8 @@ type ServerConfig struct {
 
 // HooksConfig holds lifecycle hook commands.
 type HooksConfig struct {
-	PreCommit string `yaml:"pre_commit"` // shell command to run before commit
+	PreCommit      string `yaml:"pre_commit"`       // shell command to run before commit
+	MaxHookRetries int    `yaml:"max_hook_retries"` // agent retry attempts on hook failure (default 2)
 }
 
 // CRConfig controls the code review feedback loop.
@@ -157,6 +158,10 @@ func Load(path string) (*Config, error) {
 		}
 	}
 
+	if cfg.Hooks.MaxHookRetries == 0 {
+		cfg.Hooks.MaxHookRetries = 2
+	}
+
 	if cfg.Editor.Command == "" {
 		cfg.Editor.Command = "code"
 	}

internal/intent/classify.go

@@ -1,6 +1,7 @@
 package intent
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
@@ -12,6 +13,9 @@ import (
 // CommandContext is the function used to create exec.Cmd. Override in tests.
 var CommandContext = exec.CommandContext
 
+// MinConfidence is the minimum confidence score required to accept a classification.
+const MinConfidence = 0.5
+
 // Classify interprets a natural language query as a forge command.
 func Classify(ctx context.Context, query string) (*Result, error) {
 	if _, err := exec.LookPath("claude"); err != nil {
@@ -21,19 +25,22 @@ func Classify(ctx context.Context, query string) (*Result, error) {
 	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
 	defer cancel()
 
-	dc := GatherContext()
+	dc := GatherContext(".")
 	prompt := BuildPrompt(query, dc)
 
 	cmd := CommandContext(ctx, "claude", "-p", prompt, "--output-format", "json", "--max-tokens", "256")
-	out, err := cmd.CombinedOutput()
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	err := cmd.Run()
 	if err != nil {
 		if ctx.Err() == context.DeadlineExceeded {
 			return nil, fmt.Errorf("%w: timed out after 30s", ErrClassificationFailed)
 		}
-		return nil, fmt.Errorf("%w: %s", ErrClassificationFailed, string(out))
+		return nil, fmt.Errorf("%w: %s", ErrClassificationFailed, stderr.String())
 	}
 
-	return parseResponse(string(out))
+	return parseResponse(stdout.String())
 }
 
 // parseResponse extracts a Result from the claude CLI JSON output.
@@ -55,6 +62,10 @@ func parseResponse(raw string) (*Result, error) {
 		return nil, fmt.Errorf("%w: empty argv", ErrClassificationFailed)
 	}
 
+	if r.Confidence < MinConfidence {
+		return nil, fmt.Errorf("%w: confidence %.2f below threshold %.2f: %s", ErrClassificationFailed, r.Confidence, MinConfidence, r.Reasoning)
+	}
+
 	return &r, nil
 }
 

internal/intent/classify_test.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"os"
 	"os/exec"
+	"strings"
 	"testing"
 )
 
@@ -60,9 +61,7 @@ func TestClassify_Success(t *testing.T) {
 
 func TestClassify_NoClaude(t *testing.T) {
 	// Override PATH so claude is not found.
-	orig := os.Getenv("PATH")
-	os.Setenv("PATH", "")
-	defer os.Setenv("PATH", orig)
+	t.Setenv("PATH", "")
 
 	_, err := Classify(context.Background(), "anything")
 	if !errors.Is(err, ErrNoClaude) {
@@ -131,6 +130,22 @@ func TestParseResponse_DirectJSON(t *testing.T) {
 	}
 }
 
+func TestClassify_LowConfidence(t *testing.T) {
+	envelope := `{"result":"{\"argv\":[\"run\",\"plans/auth.md\"],\"confidence\":0.2,\"reasoning\":\"not sure\"}"}`
+
+	orig := CommandContext
+	CommandContext = fakeCommandContext(envelope, false)
+	defer func() { CommandContext = orig }()
+
+	_, err := Classify(context.Background(), "maybe run something")
+	if !errors.Is(err, ErrClassificationFailed) {
+		t.Fatalf("expected ErrClassificationFailed, got: %v", err)
+	}
+	if err == nil || !strings.Contains(err.Error(), "confidence") {
+		t.Fatalf("expected confidence-related error, got: %v", err)
+	}
+}
+
 func TestStripCodeFences(t *testing.T) {
 	tests := []struct {
 		name string

internal/intent/context.go

@@ -15,18 +15,18 @@ type DynamicContext struct {
 }
 
 // GatherContext collects plan files and recent run IDs for prompt injection.
-func GatherContext() DynamicContext {
+func GatherContext(rootDir string) DynamicContext {
 	var dc DynamicContext
 
-	plans, _ := filepath.Glob("plans/*.md")
+	plans, _ := filepath.Glob(filepath.Join(rootDir, "plans", "*.md"))
 	for _, p := range plans {
 		dc.PlanFiles = append(dc.PlanFiles, filepath.Base(p))
 	}
 
 	runs, err := state.List()
 	if err == nil {
-		cap := min(10, len(runs))
-		for _, r := range runs[:cap] {
+		n := min(10, len(runs))
+		for _, r := range runs[:n] {
 			dc.RunIDs = append(dc.RunIDs, r.ID)
 		}
 	}

internal/intent/context_test.go

@@ -23,15 +23,10 @@ func TestGatherContext_WithPlanFiles(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	// Change to temp dir so glob finds plans/.
-	orig, _ := os.Getwd()
-	os.Chdir(dir)
-	defer os.Chdir(orig)
-
 	// Point state to empty dir so List() returns nothing.
 	state.SetRunsDir(filepath.Join(dir, "no-runs"))
 
-	dc := GatherContext()
+	dc := GatherContext(dir)
 	if len(dc.PlanFiles) != 2 {
 		t.Fatalf("expected 2 plan files, got %d", len(dc.PlanFiles))
 	}
@@ -42,13 +37,10 @@ func TestGatherContext_WithPlanFiles(t *testing.T) {
 
 func TestGatherContext_NoPlanFiles(t *testing.T) {
 	dir := t.TempDir()
-	orig, _ := os.Getwd()
-	os.Chdir(dir)
-	defer os.Chdir(orig)
 
 	state.SetRunsDir(filepath.Join(dir, "no-runs"))
 
-	dc := GatherContext()
+	dc := GatherContext(dir)
 	if len(dc.PlanFiles) != 0 {
 		t.Fatalf("expected 0 plan files, got %d", len(dc.PlanFiles))
 	}