fix(guard): block Task tool for Mayor via GT_ROLE check (#1529)

seanbearden · claude · web-flow · commit 32a891984ff0 · 2026-02-15T21:39:53.000-08:00
* fix(guard): block Task tool for Mayor via GT_ROLE check Adds `gt tap guard task-dispatch` PreToolUse guard that blocks the Claude Code Task tool when GT_ROLE=mayor, directing the Mayor to use bd create + gt sling instead. This prevents subagent spawning that blocks the Mayor's context and violates GUPP. Key changes from v1 (#1524): - Check GT_ROLE=mayor instead of GT_MAYOR (which is never set) - Built-in defaults always merge first, on-disk overrides layer on top (prevents custom overrides from silently dropping the guard) - Removed --force reference from help text Fixes #904 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(guard): clarify override semantics, add conflict tests Address review feedback: the doc comment incorrectly claimed built-in guards remain active with on-disk overrides. The intended design is defaults-first with on-disk layered on top — on-disk overrides CAN replace or disable built-in guards via per-matcher merge semantics. Updated doc comment and added two tests documenting the behavior: - Conflicting Task matcher replaces built-in guard command - Empty Hooks list on Task matcher disables guard entirely Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/internal/cmd/tap_guard.go b/internal/cmd/tap_guard.go
@@ -18,7 +18,8 @@ is violated. They're called before the tool runs, preventing the
 forbidden operation entirely.
 
 Available guards:
-  pr-workflow   - Block PR creation and feature branches
+  pr-workflow      - Block PR creation and feature branches
+  task-dispatch    - Block Task tool for Mayor (use gt sling instead)
 
 Example hook configuration:
   {
@@ -51,9 +52,33 @@ witness, etc.). Humans running outside Gas Town can still use PRs.`,
 	RunE: runTapGuardPRWorkflow,
 }
 
+var tapGuardTaskDispatchCmd = &cobra.Command{
+	Use:   "task-dispatch",
+	Short: "Block Task tool for Mayor (use gt sling instead)",
+	Long: `Block the Claude Code Task tool when running as Mayor.
+
+The Mayor should dispatch work via gt sling, not by spawning Claude Code
+subagents. Subagents block the Mayor's context until they finish, breaking
+GUPP (the propulsion principle) and preventing parallel polecat execution.
+
+This guard blocks:
+  - Task tool invocations (Claude Code subagent spawning)
+
+Exit codes:
+  0 - Operation allowed (not Mayor)
+  2 - Operation BLOCKED (Mayor context detected)
+
+The guard only blocks when GT_ROLE=mayor. Crew members and polecats
+can still use the Task tool for parallel research.
+
+See: https://github.com/steveyegge/gastown/issues/904`,
+	RunE: runTapGuardTaskDispatch,
+}
+
 func init() {
 	tapCmd.AddCommand(tapGuardCmd)
 	tapGuardCmd.AddCommand(tapGuardPRWorkflowCmd)
+	tapGuardCmd.AddCommand(tapGuardTaskDispatchCmd)
 }
 
 func runTapGuardPRWorkflow(cmd *cobra.Command, args []string) error {
@@ -80,6 +105,28 @@ func runTapGuardPRWorkflow(cmd *cobra.Command, args []string) error {
 	return NewSilentExit(2) // Exit 2 = BLOCK in Claude Code hooks
 }
 
+func runTapGuardTaskDispatch(cmd *cobra.Command, args []string) error {
+	// Only block when running as Mayor
+	if os.Getenv("GT_ROLE") != "mayor" {
+		return nil
+	}
+
+	fmt.Fprintln(os.Stderr, "")
+	fmt.Fprintln(os.Stderr, "╔══════════════════════════════════════════════════════════════════╗")
+	fmt.Fprintln(os.Stderr, "║  TASK TOOL BLOCKED -- Mayor cannot spawn subagents              ║")
+	fmt.Fprintln(os.Stderr, "╠══════════════════════════════════════════════════════════════════╣")
+	fmt.Fprintln(os.Stderr, "║  Subagents block your context and prevent parallel execution.    ║")
+	fmt.Fprintln(os.Stderr, "║                                                                  ║")
+	fmt.Fprintln(os.Stderr, "║  Instead of:  Task tool (spawning a subagent)                   ║")
+	fmt.Fprintln(os.Stderr, "║  Do this:     bd create \"...\" && gt sling <bead-id> <rig>       ║")
+	fmt.Fprintln(os.Stderr, "║                                                                  ║")
+	fmt.Fprintln(os.Stderr, "║  Why? Polecats execute in parallel without blocking the Mayor.  ║")
+	fmt.Fprintln(os.Stderr, "║  See: https://github.com/steveyegge/gastown/issues/904          ║")
+	fmt.Fprintln(os.Stderr, "╚══════════════════════════════════════════════════════════════════╝")
+	fmt.Fprintln(os.Stderr, "")
+	return NewSilentExit(2) // Exit 2 = BLOCK in Claude Code hooks
+}
+
 // isGasTownAgentContext returns true if we're running as a Gas Town managed agent.
 func isGasTownAgentContext() bool {
 	// Check environment variables set by Gas Town session management
diff --git a/internal/cmd/tap_guard_test.go b/internal/cmd/tap_guard_test.go
@@ -0,0 +1,50 @@
+package cmd
+
+import (
+	"os"
+	"testing"
+)
+
+func TestTapGuardTaskDispatch_BlocksWhenMayor(t *testing.T) {
+	t.Setenv("GT_ROLE", "mayor")
+
+	err := runTapGuardTaskDispatch(nil, nil)
+	if err == nil {
+		t.Fatal("expected error (exit 2) when GT_ROLE=mayor")
+	}
+
+	se, ok := err.(*SilentExitError)
+	if !ok {
+		t.Fatalf("expected SilentExitError, got %T: %v", err, err)
+	}
+	if se.Code != 2 {
+		t.Errorf("expected exit code 2, got %d", se.Code)
+	}
+}
+
+func TestTapGuardTaskDispatch_AllowsWhenNotMayor(t *testing.T) {
+	os.Unsetenv("GT_ROLE")
+
+	err := runTapGuardTaskDispatch(nil, nil)
+	if err != nil {
+		t.Errorf("expected nil error when GT_ROLE is not set, got %v", err)
+	}
+}
+
+func TestTapGuardTaskDispatch_AllowsForCrew(t *testing.T) {
+	t.Setenv("GT_ROLE", "crew")
+
+	err := runTapGuardTaskDispatch(nil, nil)
+	if err != nil {
+		t.Errorf("expected nil error for crew member, got %v", err)
+	}
+}
+
+func TestTapGuardTaskDispatch_AllowsForPolecat(t *testing.T) {
+	t.Setenv("GT_ROLE", "polecat")
+
+	err := runTapGuardTaskDispatch(nil, nil)
+	if err != nil {
+		t.Errorf("expected nil error for polecat, got %v", err)
+	}
+}
diff --git a/internal/hooks/config.go b/internal/hooks/config.go
@@ -164,9 +164,33 @@ func Merge(base, override *HooksConfig) *HooksConfig {
 	return applyOverride(result, override)
 }
 
+// DefaultOverrides returns built-in role-specific hook overrides.
+// These are always applied as a baseline layer; on-disk overrides merge on top.
+func DefaultOverrides() map[string]*HooksConfig {
+	pathSetup := `export PATH="$HOME/go/bin:$HOME/.local/bin:$PATH"`
+	return map[string]*HooksConfig{
+		"mayor": {
+			PreToolUse: []HookEntry{
+				{
+					Matcher: "Task",
+					Hooks: []Hook{{
+						Type:    "command",
+						Command: fmt.Sprintf("%s && gt tap guard task-dispatch", pathSetup),
+					}},
+				},
+			},
+		},
+	}
+}
+
 // ComputeExpected computes the expected HooksConfig for a target by loading
 // the base config and applying all applicable overrides in order of specificity.
 // If no base config exists, uses DefaultBase().
+//
+// For each override key, built-in defaults (from DefaultOverrides) are merged
+// first, then on-disk overrides layer on top. On-disk overrides can replace
+// or disable built-in guards by providing a matching PreToolUse entry (e.g.,
+// an empty Hooks list for the "Task" matcher disables the task-dispatch guard).
 func ComputeExpected(target string) (*HooksConfig, error) {
 	base, err := LoadBase()
 	if err != nil {
@@ -177,8 +201,15 @@ func ComputeExpected(target string) (*HooksConfig, error) {
 		}
 	}
 
+	defaults := DefaultOverrides()
 	result := base
 	for _, overrideKey := range GetApplicableOverrides(target) {
+		// Always apply built-in defaults first
+		if def, ok := defaults[overrideKey]; ok {
+			result = Merge(result, def)
+		}
+
+		// Then layer on-disk overrides on top
 		override, err := LoadOverride(overrideKey)
 		if err != nil {
 			if os.IsNotExist(err) {
diff --git a/internal/hooks/config_test.go b/internal/hooks/config_test.go
@@ -424,14 +424,134 @@ func TestComputeExpectedNoBase(t *testing.T) {
 	tmpDir := t.TempDir()
 	setTestHome(t, tmpDir)
 
+	// Mayor should get DefaultBase + built-in mayor override (task-dispatch guard)
 	expected, err := ComputeExpected("mayor")
 	if err != nil {
 		t.Fatalf("ComputeExpected failed: %v", err)
 	}
 
 	defaultBase := DefaultBase()
-	if !HooksEqual(expected, defaultBase) {
-		t.Error("expected DefaultBase when no configs exist")
+	mayorDefaults := DefaultOverrides()["mayor"]
+	merged := Merge(defaultBase, mayorDefaults)
+	if !HooksEqual(expected, merged) {
+		t.Error("expected DefaultBase + mayor default override when no configs exist")
+	}
+
+	// Non-mayor target should still just get DefaultBase
+	crew, err := ComputeExpected("crew")
+	if err != nil {
+		t.Fatalf("ComputeExpected(crew) failed: %v", err)
+	}
+	if !HooksEqual(crew, defaultBase) {
+		t.Error("expected DefaultBase for crew when no configs exist")
+	}
+}
+
+// TestComputeExpectedBuiltinPlusOnDisk verifies that on-disk overrides layer
+// on top of built-in defaults rather than replacing them.
+func TestComputeExpectedBuiltinPlusOnDisk(t *testing.T) {
+	tmpDir := t.TempDir()
+	setTestHome(t, tmpDir)
+
+	// Save an on-disk mayor override that adds a custom SessionStart hook
+	customOverride := &HooksConfig{
+		SessionStart: []HookEntry{
+			{Matcher: "", Hooks: []Hook{{Type: "command", Command: "custom-mayor-session"}}},
+		},
+	}
+	if err := SaveOverride("mayor", customOverride); err != nil {
+		t.Fatalf("SaveOverride failed: %v", err)
+	}
+
+	expected, err := ComputeExpected("mayor")
+	if err != nil {
+		t.Fatalf("ComputeExpected failed: %v", err)
+	}
+
+	// Should have the built-in Task guard from DefaultOverrides
+	foundTaskGuard := false
+	for _, entry := range expected.PreToolUse {
+		if entry.Matcher == "Task" {
+			foundTaskGuard = true
+			break
+		}
+	}
+	if !foundTaskGuard {
+		t.Error("built-in Task guard should be present even with on-disk mayor override")
+	}
+
+	// Should also have the custom SessionStart from on-disk override
+	if len(expected.SessionStart) == 0 {
+		t.Error("on-disk SessionStart override should be present")
+	} else if expected.SessionStart[0].Hooks[0].Command != "custom-mayor-session" {
+		t.Errorf("expected custom-mayor-session, got %q", expected.SessionStart[0].Hooks[0].Command)
+	}
+}
+
+// TestComputeExpectedOnDiskReplacesBuiltin verifies that an on-disk override
+// with a conflicting "Task" matcher replaces the built-in guard command.
+func TestComputeExpectedOnDiskReplacesBuiltin(t *testing.T) {
+	tmpDir := t.TempDir()
+	setTestHome(t, tmpDir)
+
+	// On-disk override replaces the Task matcher with a custom command
+	customOverride := &HooksConfig{
+		PreToolUse: []HookEntry{
+			{Matcher: "Task", Hooks: []Hook{{Type: "command", Command: "custom-task-guard"}}},
+		},
+	}
+	if err := SaveOverride("mayor", customOverride); err != nil {
+		t.Fatalf("SaveOverride failed: %v", err)
+	}
+
+	expected, err := ComputeExpected("mayor")
+	if err != nil {
+		t.Fatalf("ComputeExpected failed: %v", err)
+	}
+
+	// The on-disk Task entry should replace the built-in one
+	foundCustom := false
+	for _, entry := range expected.PreToolUse {
+		if entry.Matcher == "Task" {
+			if len(entry.Hooks) == 1 && entry.Hooks[0].Command == "custom-task-guard" {
+				foundCustom = true
+			} else {
+				t.Errorf("Task matcher should have custom command, got %v", entry.Hooks)
+			}
+			break
+		}
+	}
+	if !foundCustom {
+		t.Error("on-disk Task override should replace built-in guard")
+	}
+}
+
+// TestComputeExpectedOnDiskDisablesBuiltin verifies that an on-disk override
+// with an empty Hooks list for "Task" disables the built-in guard entirely.
+func TestComputeExpectedOnDiskDisablesBuiltin(t *testing.T) {
+	tmpDir := t.TempDir()
+	setTestHome(t, tmpDir)
+
+	// On-disk override disables the Task guard with empty hooks
+	disableOverride := &HooksConfig{
+		PreToolUse: []HookEntry{
+			{Matcher: "Task", Hooks: []Hook{}},
+		},
+	}
+	if err := SaveOverride("mayor", disableOverride); err != nil {
+		t.Fatalf("SaveOverride failed: %v", err)
+	}
+
+	expected, err := ComputeExpected("mayor")
+	if err != nil {
+		t.Fatalf("ComputeExpected failed: %v", err)
+	}
+
+	// The Task entry should be removed (empty Hooks = explicit disable)
+	for _, entry := range expected.PreToolUse {
+		if entry.Matcher == "Task" {
+			t.Error("Task matcher should be removed when on-disk override has empty Hooks")
+		}
 	}
 }
 
