feat: add trace lifecycle manager — hawk bundles, enables, and controls trace

- sessioncapture/trace_manager.go: IsInstalled, Enable, Disable, AutoSetup, Status
- hawk brew formula will declare trace as dependency (auto-install)
- AutoSetup called on session start: enables trace if installed but not active
- Users can /trace-enable and /trace-disable from within hawk
- trace remains standalone (works with any agent independently)

Author: Patel230

sessioncapture/INSTALL.md

@@ -0,0 +1,61 @@
+# trace Integration with hawk
+
+## How it works
+
+When you install hawk via Homebrew, trace is automatically installed as a dependency:
+
+```ruby
+# In GrayCodeAI/homebrew-tap/Formula/hawk.rb
+class Hawk < Formula
+  depends_on "GrayCodeAI/tap/trace"  # ← bundled automatically
+end
+```
+
+## Automatic behavior
+
+1. **Install hawk** → trace is installed alongside it
+2. **Run hawk in a git repo** → trace auto-enables (installs git hooks)
+3. **Every commit** → trace captures the session silently
+4. **No config needed** — zero setup for the user
+
+## User controls (from within hawk)
+
+```
+/trace-enable      Enable session capture for this project
+/trace-disable     Disable session capture for this project
+/trace-status      Show current capture status
+```
+
+Or from CLI:
+
+```bash
+hawk config trace.enabled true    # enable
+hawk config trace.enabled false   # disable
+```
+
+## Architecture
+
+```
+brew install hawk
+  └── also installs: trace (as dependency)
+
+hawk starts session
+  └── sessioncapture.AutoSetup()
+        ├── trace installed? YES
+        ├── trace enabled? NO → runs "trace enable --agent hawk"
+        └── done (hooks installed, recording active)
+
+hawk makes commits
+  └── .git/hooks/post-commit (installed by trace)
+        └── trace captures session → stores on shadow branch
+
+User wants to disable:
+  └── /trace-disable → runs "trace disable" → hooks removed
+```
+
+## trace stays standalone
+
+- trace has its own repo, its own binary, its own release cycle
+- trace works with ANY agent (Claude Code, Cursor, Codex, hawk)
+- hawk just manages trace's lifecycle as a convenience
+- Users can also install/manage trace independently

sessioncapture/trace_manager.go

@@ -0,0 +1,113 @@
+// Package sessioncapture manages trace integration — auto-installing,
+// enabling, disabling, and checking status of trace for session recording.
+//
+// trace remains a standalone binary. hawk bundles it and manages its lifecycle.
+package sessioncapture
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+)
+
+// TraceManager handles trace lifecycle from within hawk.
+type TraceManager struct {
+	ProjectDir string
+}
+
+// NewTraceManager creates a manager for the given project directory.
+func NewTraceManager(projectDir string) *TraceManager {
+	return &TraceManager{ProjectDir: projectDir}
+}
+
+// IsInstalled checks if the trace binary is available in PATH.
+func (tm *TraceManager) IsInstalled() bool {
+	_, err := exec.LookPath("trace")
+	return err == nil
+}
+
+// IsEnabled checks if trace is enabled in the current project.
+func (tm *TraceManager) IsEnabled() bool {
+	// trace stores config in .trace/ at the repo root
+	settingsPath := filepath.Join(tm.ProjectDir, ".trace", "settings.json")
+	_, err := os.Stat(settingsPath)
+	return err == nil
+}
+
+// Enable activates trace in the current project with hawk as the agent.
+func (tm *TraceManager) Enable() error {
+	if !tm.IsInstalled() {
+		return fmt.Errorf("trace is not installed — run: brew install GrayCodeAI/tap/trace")
+	}
+
+	cmd := exec.Command("trace", "enable", "--agent", "hawk")
+	cmd.Dir = tm.ProjectDir
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("trace enable failed: %s\n%s", err, string(output))
+	}
+	return nil
+}
+
+// Disable deactivates trace in the current project (removes hooks).
+func (tm *TraceManager) Disable() error {
+	if !tm.IsInstalled() {
+		return nil // nothing to disable
+	}
+
+	cmd := exec.Command("trace", "disable")
+	cmd.Dir = tm.ProjectDir
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("trace disable failed: %s\n%s", err, string(output))
+	}
+	return nil
+}
+
+// Status returns the current trace status for this project.
+func (tm *TraceManager) Status() string {
+	if !tm.IsInstalled() {
+		return "not installed"
+	}
+	if !tm.IsEnabled() {
+		return "installed but not enabled"
+	}
+
+	cmd := exec.Command("trace", "status")
+	cmd.Dir = tm.ProjectDir
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return "enabled (status check failed)"
+	}
+	return strings.TrimSpace(string(output))
+}
+
+// AutoSetup is called when hawk starts a session. It:
+// 1. Checks if trace is installed (bundled with hawk via brew)
+// 2. If installed but not enabled → enables it automatically
+// 3. If not installed → skips silently (hawk works fine without it)
+func (tm *TraceManager) AutoSetup() error {
+	if !tm.IsInstalled() {
+		// trace not available — hawk works fine without it
+		return nil
+	}
+	if tm.IsEnabled() {
+		// already enabled — nothing to do
+		return nil
+	}
+	// Auto-enable trace for this project
+	return tm.Enable()
+}
+
+// FormatStatus returns a human-readable status line for hawk's UI.
+func (tm *TraceManager) FormatStatus() string {
+	if !tm.IsInstalled() {
+		return "Session capture: disabled (trace not installed)"
+	}
+	if !tm.IsEnabled() {
+		return "Session capture: disabled (run /trace-enable to activate)"
+	}
+	return "Session capture: active (trace recording sessions)"
+}

sessioncapture/trace_manager_test.go

@@ -0,0 +1,113 @@
+package sessioncapture
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestIsInstalled(t *testing.T) {
+	tm := NewTraceManager(".")
+	// Just verify it doesn't panic — result depends on environment
+	_ = tm.IsInstalled()
+}
+
+func TestIsEnabled_NotEnabled(t *testing.T) {
+	dir := t.TempDir()
+	tm := NewTraceManager(dir)
+	if tm.IsEnabled() {
+		t.Error("expected not enabled in empty dir")
+	}
+}
+
+func TestIsEnabled_Enabled(t *testing.T) {
+	dir := t.TempDir()
+	// Create .trace/settings.json to simulate enabled state
+	traceDir := filepath.Join(dir, ".trace")
+	os.MkdirAll(traceDir, 0o755)
+	os.WriteFile(filepath.Join(traceDir, "settings.json"), []byte(`{"enabled":true}`), 0o644)
+
+	tm := NewTraceManager(dir)
+	if !tm.IsEnabled() {
+		t.Error("expected enabled when .trace/settings.json exists")
+	}
+}
+
+func TestStatus_NotInstalled(t *testing.T) {
+	// Use a PATH that won't have trace
+	origPath := os.Getenv("PATH")
+	os.Setenv("PATH", "/nonexistent")
+	defer os.Setenv("PATH", origPath)
+
+	tm := NewTraceManager(".")
+	status := tm.Status()
+	if status != "not installed" {
+		t.Errorf("expected 'not installed', got %q", status)
+	}
+}
+
+func TestStatus_InstalledNotEnabled(t *testing.T) {
+	tm := NewTraceManager(t.TempDir())
+	if !tm.IsInstalled() {
+		t.Skip("trace not installed in this environment")
+	}
+	status := tm.Status()
+	if status == "not installed" {
+		t.Error("trace is installed but status says not installed")
+	}
+}
+
+func TestFormatStatus_NotInstalled(t *testing.T) {
+	origPath := os.Getenv("PATH")
+	os.Setenv("PATH", "/nonexistent")
+	defer os.Setenv("PATH", origPath)
+
+	tm := NewTraceManager(".")
+	result := tm.FormatStatus()
+	if result != "Session capture: disabled (trace not installed)" {
+		t.Errorf("unexpected format: %q", result)
+	}
+}
+
+func TestFormatStatus_Enabled(t *testing.T) {
+	dir := t.TempDir()
+	os.MkdirAll(filepath.Join(dir, ".trace"), 0o755)
+	os.WriteFile(filepath.Join(dir, ".trace", "settings.json"), []byte(`{}`), 0o644)
+
+	tm := NewTraceManager(dir)
+	if !tm.IsInstalled() {
+		t.Skip("trace not installed")
+	}
+	result := tm.FormatStatus()
+	if result != "Session capture: active (trace recording sessions)" {
+		t.Errorf("unexpected: %q", result)
+	}
+}
+
+func TestAutoSetup_NoTrace(t *testing.T) {
+	origPath := os.Getenv("PATH")
+	os.Setenv("PATH", "/nonexistent")
+	defer os.Setenv("PATH", origPath)
+
+	tm := NewTraceManager(t.TempDir())
+	err := tm.AutoSetup()
+	if err != nil {
+		t.Errorf("AutoSetup should silently skip when trace not installed, got: %v", err)
+	}
+}
+
+func TestAutoSetup_AlreadyEnabled(t *testing.T) {
+	dir := t.TempDir()
+	os.MkdirAll(filepath.Join(dir, ".trace"), 0o755)
+	os.WriteFile(filepath.Join(dir, ".trace", "settings.json"), []byte(`{}`), 0o644)
+
+	tm := NewTraceManager(dir)
+	if !tm.IsInstalled() {
+		t.Skip("trace not installed")
+	}
+	// Should be a no-op
+	err := tm.AutoSetup()
+	if err != nil {
+		t.Errorf("AutoSetup should skip when already enabled, got: %v", err)
+	}
+}