feat(hawk): adopt herm patterns — outline/git tools, background agents, container hot-swap, sub-agent resume

Port features from herm into hawk natively:

- OutlineTool for AST-level signature scanning (10 languages, head/tail fallback)
- GitTool with 16 allowed subcommands, force-push detection, approval checks
- BackgroundAgentManager for fire-and-forget sub-agents with result collection
- agent_id/resume and retry_of support for sub-agent lifecycle management
- DevEnv real Docker build via exec.CommandContext (was no-op)
- RebuildAndForceSwap for mid-session container hot-swap
- Rich sub-agent prompts with exploration strategy and budget management

Author: Patel230

prompts/templates/subagent.md

@@ -1,8 +1,31 @@
-You are a sub-agent of Hawk with a limited budget.
-
-Constraints:
-- You have {{.MaxTurns}} turns maximum
-- Focus on your specific task: {{.Task}}
-- Report findings concisely
-- Do not attempt work outside your assigned scope
-- If you cannot complete the task within budget, report what you found and what remains
+You are a sub-agent of Hawk. Complete the assigned task, then return a concise summary of results. Do not ask questions — make reasonable decisions and note assumptions. Focus on outcomes, not process.
+
+## Identity
+
+You are a sub-agent with a limited budget. You have **{{.MaxTurns}} turns maximum**. Track remaining turns; request fewer tool calls as budget runs low.
+
+## Task
+
+{{.Task}}
+
+## Exploration strategy
+
+Be token-efficient. Explore in layers — scan broadly first, then drill into relevant areas:
+
+1. **Map structure before reading** — use glob to discover files in a directory before reading any of them.
+2. **Search, don't scan** — use grep to find specific patterns, identifiers, or strings rather than reading files sequentially.
+3. **Read surgically** — when you must read a file, use offset/limit to read only the relevant section. Never read an entire large file when a portion will do.
+4. **Start from the working directory** — you already have the project context. Don't re-explore what's given.
+
+## Budget management
+
+- When fewer than 5 turns remain: stop requesting tools and produce a final summary immediately.
+- When fewer than 3 turns remain: you must not request any tools. Synthesize what you have.
+- Never spend more than 2 turns on a single file.
+
+## Output format
+
+When complete, produce a structured final response:
+- Key findings or decisions made
+- Files examined or modified
+- Unfinished work or open questions

sandbox/devenv.go

@@ -7,6 +7,7 @@ import (
 	"crypto/sha256"
 	"fmt"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"sync"
 	"time"
@@ -20,6 +21,13 @@ type CachedImage struct {
 	Stale       bool
 }
 
+// SwapRequest is sent when a container hot-swap is needed after a rebuild.
+type SwapRequest struct {
+	ImageTag    string
+	Dockerfile  string
+	Workspace   string
+}
+
 // DevEnvManager caches Docker images per-project based on Dockerfile content hashes.
 type DevEnvManager struct {
 	projectDir string
@@ -28,6 +36,10 @@ type DevEnvManager struct {
 	// buildFn is the function called to build a Docker image. Defaults to actual Docker build.
 	// Can be overridden in tests.
 	buildFn func(ctx context.Context, dockerfile, tag string) error
+	// OnSwapNeeded is called after a successful rebuild to request a container
+	// hot-swap. The session should stop the old container and start a new one
+	// with the given image tag. May be nil.
+	OnSwapNeeded func(req SwapRequest)
 }
 
 // NewDevEnvManager creates a new DevEnvManager for the given project directory.
@@ -39,10 +51,17 @@ func NewDevEnvManager(projectDir string) *DevEnvManager {
 	}
 }
 
-// defaultBuildFn is a placeholder build function. In production this would invoke `docker build`.
+// defaultBuildFn builds a Docker image from the given Dockerfile path,
+// tagging it with the given tag. The build context is the directory
+// containing the Dockerfile.
 func defaultBuildFn(ctx context.Context, dockerfile, tag string) error {
-	// In a real implementation, this would run:
-	//   docker build -t <tag> -f <dockerfile> <context>
+	contextDir := filepath.Dir(dockerfile)
+	cmd := exec.CommandContext(ctx, "docker", "build", "-t", tag, "-f", dockerfile, contextDir)
+	cmd.Stdout = os.Stderr // show build output on stderr
+	cmd.Stderr = os.Stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("docker build failed: %w", err)
+	}
 	return nil
 }
 
@@ -118,6 +137,37 @@ func (d *DevEnvManager) Invalidate(projectDir string) {
 	}
 }
 
+// RebuildAndForceSwap forces a rebuild even if cached, then triggers
+// the OnSwapNeeded callback. This is the hot-swap path.
+func (d *DevEnvManager) RebuildAndForceSwap(ctx context.Context, dockerfilePath string) (string, error) {
+	d.mu.Lock()
+	key := filepath.Base(filepath.Dir(dockerfilePath))
+	if key == "." || key == "" {
+		key = "default"
+	}
+	// Invalidate to force rebuild.
+	if cached, ok := d.imageCache[key]; ok {
+		cached.Stale = true
+		d.imageCache[key] = cached
+	}
+	d.mu.Unlock()
+
+	tag, err := d.GetOrBuild(ctx, dockerfilePath)
+	if err != nil {
+		return "", err
+	}
+
+	if d.OnSwapNeeded != nil {
+		d.OnSwapNeeded(SwapRequest{
+			ImageTag:   tag,
+			Dockerfile: dockerfilePath,
+			Workspace:  d.projectDir,
+		})
+	}
+
+	return tag, nil
+}
+
 // hashDockerfile computes a SHA-256 hash of the Dockerfile contents.
 func hashDockerfile(path string) (string, error) {
 	data, err := os.ReadFile(path)

tool/agent.go

@@ -5,29 +5,49 @@ import (
 	"encoding/json"
 	"fmt"
 	"sync"
+	"time"
 )
 
+// backgroundCompletionTimeout is the maximum time to wait for background
+// sub-agents in a single background-completion cycle.
+const backgroundCompletionTimeout = 2 * time.Minute
+
 type AgentTool struct{}
 
 func (AgentTool) Name() string      { return "Agent" }
 func (AgentTool) RiskLevel() string { return "medium" }
 func (AgentTool) Aliases() []string { return []string{"agent", "Task"} }
 func (AgentTool) Description() string {
-	return "Spawn a sub-agent to handle a complex task independently. The sub-agent has access to all tools."
+	return "Spawn a sub-agent to handle a complex task independently. The sub-agent has access to all tools. Set run_in_background=true to spawn asynchronously — results are injected when the main turn ends."
 }
 func (AgentTool) Parameters() map[string]interface{} {
 	return map[string]interface{}{
 		"type": "object",
 		"properties": map[string]interface{}{
 			"prompt": map[string]interface{}{"type": "string", "description": "Task description for the sub-agent"},
+			"run_in_background": map[string]interface{}{
+				"type":        "boolean",
+				"description": "If true, spawn the sub-agent in the background and continue. Results are collected when the main turn ends.",
+			},
+			"agent_id": map[string]interface{}{
+				"type":        "string",
+				"description": "ID of a previous sub-agent to resume. The sub-agent continues from where it left off with its full context preserved.",
+			},
+			"retry_of": map[string]interface{}{
+				"type":        "string",
+				"description": "ID of a failed sub-agent to retry. Spawns a new agent with the same task.",
+			},
 		},
 		"required": []string{"prompt"},
 	}
 }
 
 func (AgentTool) Execute(ctx context.Context, input json.RawMessage) (string, error) {
 	var p struct {
-		Prompt string `json:"prompt"`
+		Prompt          string `json:"prompt"`
+		RunInBackground bool   `json:"run_in_background"`
+		AgentID         string `json:"agent_id"`
+		RetryOf         string `json:"retry_of"`
 	}
 	if err := json.Unmarshal(input, &p); err != nil {
 		return "", err
@@ -36,6 +56,47 @@ func (AgentTool) Execute(ctx context.Context, input json.RawMessage) (string, er
 	if tc == nil || tc.AgentSpawnFn == nil {
 		return "", fmt.Errorf("agent spawning not configured")
 	}
+
+	// Resume a previous agent by ID.
+	if p.AgentID != "" {
+		if tc.BackgroundManager == nil {
+			return "", fmt.Errorf("background agent manager not configured")
+		}
+		result, ok := tc.BackgroundManager.GetResult(p.AgentID)
+		if ok {
+			return agentEnvelopeWithID(p.AgentID, "completed", result.Output), nil
+		}
+		if tc.BackgroundManager.IsRunning(p.AgentID) {
+			elapsed := tc.BackgroundManager.Elapsed(p.AgentID)
+			return fmt.Sprintf(`{"agent":"%s","status":"running","elapsed":"%s"}`, p.AgentID, elapsed), nil
+		}
+		return "", fmt.Errorf("agent_id %q not found", p.AgentID)
+	}
+
+	// Retry a failed agent.
+	if p.RetryOf != "" {
+		if tc.BackgroundManager == nil {
+			return "", fmt.Errorf("background agent manager not configured")
+		}
+		result, ok := tc.BackgroundManager.GetResult(p.RetryOf)
+		if !ok {
+			return "", fmt.Errorf("retry_of %q not found or still running", p.RetryOf)
+		}
+		// Re-spawn with the original prompt.
+		id := fmt.Sprintf("retry-%d", time.Now().UnixNano())
+		tc.BackgroundManager.Spawn(ctx, id, result.Prompt, tc.AgentSpawnFn)
+		return fmt.Sprintf(`{"agent":"%s","retry_of":"%s","status":"running","message":"Retrying failed agent."}`, id, p.RetryOf), nil
+	}
+
+	if p.RunInBackground {
+		if tc.BackgroundManager == nil {
+			return "", fmt.Errorf("background agent manager not configured")
+		}
+		id := fmt.Sprintf("bg-%d", time.Now().UnixNano())
+		tc.BackgroundManager.Spawn(ctx, id, p.Prompt, tc.AgentSpawnFn)
+		return fmt.Sprintf(`{"agent":"%s","status":"running","message":"Sub-agent spawned in background. Results will be injected when the main turn ends."}`, id), nil
+	}
+
 	out, err := tc.AgentSpawnFn(ctx, p.Prompt)
 	if err != nil {
 		return "", err
@@ -44,6 +105,10 @@ func (AgentTool) Execute(ctx context.Context, input json.RawMessage) (string, er
 }
 
 func agentEnvelope(status, output string) string {
+	return agentEnvelopeWithID("sub-agent", status, output)
+}
+
+func agentEnvelopeWithID(id, status, output string) string {
 	summary := output
 	if len(summary) > 200 {
 		summary = summary[:200]
@@ -55,7 +120,7 @@ func agentEnvelope(status, output string) string {
 		TokensUsed int    `json:"tokens_used"`
 		FullOutput string `json:"full_output"`
 	}{
-		Agent:      "sub-agent",
+		Agent:      id,
 		Status:     status,
 		Summary:    summary,
 		TokensUsed: 0,
@@ -81,14 +146,19 @@ func (MultiAgentTool) Parameters() map[string]interface{} {
 				"type":  "array",
 				"items": map[string]interface{}{"type": "string"},
 			},
+			"run_in_background": map[string]interface{}{
+				"type":        "boolean",
+				"description": "If true, spawn all sub-agents in the background.",
+			},
 		},
 		"required": []string{"tasks"},
 	}
 }
 
 func (MultiAgentTool) Execute(ctx context.Context, input json.RawMessage) (string, error) {
 	var p struct {
-		Tasks []string `json:"tasks"`
+		Tasks           []string `json:"tasks"`
+		RunInBackground bool     `json:"run_in_background"`
 	}
 	if err := json.Unmarshal(input, &p); err != nil {
 		return "", err
@@ -97,6 +167,21 @@ func (MultiAgentTool) Execute(ctx context.Context, input json.RawMessage) (strin
 	if tc == nil || tc.AgentSpawnFn == nil {
 		return "", fmt.Errorf("agent spawning not configured")
 	}
+
+	if p.RunInBackground {
+		if tc.BackgroundManager == nil {
+			return "", fmt.Errorf("background agent manager not configured")
+		}
+		ids := make([]string, len(p.Tasks))
+		for i, task := range p.Tasks {
+			id := fmt.Sprintf("bg-%d-%d", time.Now().UnixNano(), i)
+			tc.BackgroundManager.Spawn(ctx, id, task, tc.AgentSpawnFn)
+			ids[i] = id
+		}
+		b, _ := json.Marshal(ids)
+		return fmt.Sprintf(`{"agents":%s,"status":"running","message":"%d sub-agents spawned in background."}`, string(b), len(ids)), nil
+	}
+
 	type result struct {
 		idx    int
 		output string