feat: add --debug flag to daemon start for request/response logging

Adds a --debug flag to `ratchet daemon start` that enables logging of
outgoing message arrays and response content to ~/.ratchet/debug.log.
Threads the Debug bool through EngineContext so handleChat can gate on
it without global state.

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

Author: intel352

cmd/ratchet/cmd_daemon.go

@@ -16,19 +16,23 @@ func handleDaemon(args []string) {
 	switch args[0] {
 	case "start":
 		bg := false
+		debug := false
 		for _, a := range args[1:] {
 			if a == "--background" || a == "-b" {
 				bg = true
 			}
+			if a == "--debug" {
+				debug = true
+			}
 		}
 		if bg {
-			if err := daemon.StartBackground(); err != nil {
+			if err := daemon.StartBackground(debug); err != nil {
 				fmt.Fprintf(os.Stderr, "error: %v\n", err)
 				os.Exit(1)
 			}
 			fmt.Println("daemon started in background")
 		} else {
-			if err := daemon.Start(context.Background()); err != nil {
+			if err := daemon.Start(context.Background(), debug); err != nil {
 				fmt.Fprintf(os.Stderr, "error: %v\n", err)
 				os.Exit(1)
 			}
@@ -42,7 +46,7 @@ func handleDaemon(args []string) {
 	case "restart":
 		// Stop the old daemon (ignore errors — it may not be running).
 		_ = daemon.Stop()
-		if err := daemon.StartBackground(); err != nil {
+		if err := daemon.StartBackground(false); err != nil {
 			fmt.Fprintf(os.Stderr, "error: %v\n", err)
 			os.Exit(1)
 		}

internal/client/client.go

@@ -41,7 +41,7 @@ func Connect() (*Client, error) {
 // EnsureDaemon starts the daemon if not running, then connects.
 func EnsureDaemon() (*Client, error) {
 	if !daemon.IsRunning() {
-		if err := daemon.StartBackground(); err != nil {
+		if err := daemon.StartBackground(false); err != nil {
 			return nil, fmt.Errorf("start daemon: %w", err)
 		}
 	}

internal/daemon/chat.go

@@ -5,6 +5,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"log"
+	"os"
+	"path/filepath"
 	"slices"
 	"strings"
 	"sync"
@@ -76,6 +78,22 @@ const compactSentinel = "\x00compact\x00"
 // The diff content follows immediately after the sentinel.
 const reviewSentinel = "\x00review\x00"
 
+// debugLog appends a log entry to ~/.ratchet/debug.log when debug mode is active.
+func debugLog(format string, args ...any) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return
+	}
+	logPath := filepath.Join(home, ".ratchet", "debug.log")
+	f, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0600)
+	if err != nil {
+		return
+	}
+	defer f.Close()
+	logger := log.New(f, "", log.LstdFlags)
+	logger.Printf(format, args...)
+}
+
 // broadcastStream wraps a send-message stream and fans out each event to the broadcaster.
 type broadcastStream struct {
 	pb.RatchetDaemon_SendMessageServer
@@ -152,6 +170,12 @@ func (s *Service) handleChat(ctx context.Context, sessionID, userMessage string,
 		Content: userMessage,
 	})
 
+	// Debug: log outgoing messages.
+	if s.engine.Debug {
+		msgJSON, _ := json.Marshal(messages)
+		debugLog("[chat] session=%s sending %d messages: %s", sessionID, len(messages), string(msgJSON))
+	}
+
 	// Stream from provider (save user message AFTER successful stream start,
 	// so failed requests don't pollute conversation history).
 	eventCh, err := prov.Stream(ctx, messages, nil) // tools will be added in later task
@@ -271,6 +295,11 @@ func (s *Service) handleChat(ctx context.Context, sessionID, userMessage string,
 		}
 	}
 
+	// Debug: log response content.
+	if s.engine.Debug {
+		debugLog("[chat] session=%s response (%d chars): %s", sessionID, len(fullResponse), fullResponse)
+	}
+
 	// Save assistant response
 	if err := s.saveMessage(ctx, sessionID, "assistant", fullResponse, "", ""); err != nil {
 		log.Printf("save assistant message: %v", err)

internal/daemon/daemon.go

@@ -22,7 +22,7 @@ var reloadSignal = syscall.SIGUSR1
 
 // Start runs the daemon in the foreground. It creates the Unix socket,
 // starts the gRPC server, and blocks until signal.
-func Start(ctx context.Context) error {
+func Start(ctx context.Context, debug bool) error {
 	if err := EnsureDataDir(); err != nil {
 		return err
 	}
@@ -55,6 +55,7 @@ func Start(ctx context.Context) error {
 	if err != nil {
 		return fmt.Errorf("create service: %w", err)
 	}
+	svc.engine.Debug = debug
 	pb.RegisterRatchetDaemonServer(srv, svc)
 
 	// Graceful shutdown on SIGINT/SIGTERM.
@@ -94,7 +95,7 @@ func Start(ctx context.Context) error {
 }
 
 // StartBackground forks the current process as a background daemon.
-func StartBackground() error {
+func StartBackground(debug bool) error {
 	if IsRunning() {
 		return nil // already running
 	}
@@ -104,7 +105,11 @@ func StartBackground() error {
 		return fmt.Errorf("get executable: %w", err)
 	}
 
-	cmd := exec.Command(exe, "daemon", "start")
+	args := []string{"daemon", "start"}
+	if debug {
+		args = append(args, "--debug")
+	}
+	cmd := exec.Command(exe, args...)
 	cmd.Stdout = nil
 	cmd.Stderr = nil
 	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}

internal/daemon/engine.go

@@ -32,6 +32,7 @@ type EngineContext struct {
 	ModelRouting     config.ModelRouting
 	Actors           *ActorManager
 	Hooks            *hooks.HookConfig
+	Debug            bool // enable request/response debug logging to ~/.ratchet/debug.log
 	// Plugin-contributed capabilities
 	PluginSkills   []skills.Skill
 	PluginAgents   []agent.AgentDefinition