Add tests and documentation for enable_bang_commands feature

- Add integration test for bang commands configuration loading
- Update USAGE.md with enable_bang_commands documentation
- Add security warning about bang commands
- Document TUI bang commands feature with examples

Co-authored-by: dgageot <153495+dgageot@users.noreply.github.com>

Author: Copilot

docs/USAGE.md

@@ -84,6 +84,18 @@ During CLI sessions, you can use special commands:
 | `/eval`    | Save current conversation for evaluation    |
 | `/compact` | Compact conversation to lower context usage |
 
+#### TUI Bang Commands
+
+When `enable_bang_commands: true` is set for an agent, you can execute shell commands directly in the TUI by prefixing them with `!`:
+
+```
+!ls -la
+!pwd
+!echo "Hello from shell"
+```
+
+**⚠️ Security Note**: Bang commands are disabled by default. Only enable them for trusted agents in secure environments, as they execute arbitrary shell commands with the same permissions as the cagent process.
+
 ## 🔧 Configuration Reference
 
 ### Agent Properties
@@ -100,6 +112,7 @@ During CLI sessions, you can use special commands:
 | `add_environment_info` | boolean      | Add information about the environment (working dir, OS, git...) | ✗        |
 | `max_iterations`       | int          | Specifies how many times the agent can loop when using tools    | ✗        |
 | `commands`             | object/array | Named prompts for /commands                                     | ✗        |
+| `enable_bang_commands` | boolean      | Allow shell commands via `!` prefix in TUI (default: false)     | ✗        |
 
 #### Example
 
@@ -114,6 +127,7 @@ agents:
     add_date: boolean # Add current date to context (optional)
     add_environment_info: boolean # Add information about the environment (working dir, OS, git...) (optional)
     max_iterations: int # How many times this agent can loop when calling tools (optional, default = unlimited)
+    enable_bang_commands: boolean # Allow shell commands via ! prefix in TUI (optional, default: false)
     commands: # Either mapping or list of singleton maps
       df: "check how much free space i have on my disk"
       ls: "list the files in the current directory"

pkg/teamloader/bang_commands_integration_test.go

@@ -0,0 +1,100 @@
+package teamloader
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/docker/cagent/pkg/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBangCommandsIntegration(t *testing.T) {
+	// Set a fake API key for testing
+	t.Setenv("OPENAI_API_KEY", "fake-key-for-testing")
+
+	t.Run("load config with bang commands enabled", func(t *testing.T) {
+		yamlContent := `version: "2"
+agents:
+  root:
+    model: openai/gpt-4o
+    enable_bang_commands: true
+    toolsets:
+      - type: think
+`
+		// Create temp file
+		tmpDir := t.TempDir()
+		tmpFile := filepath.Join(tmpDir, "test.yaml")
+		err := os.WriteFile(tmpFile, []byte(yamlContent), 0644)
+		require.NoError(t, err)
+
+		// Load team
+		team, err := Load(context.Background(), tmpFile, config.RuntimeConfig{}, WithModelOverrides(nil))
+		require.NoError(t, err)
+		require.NotNil(t, team)
+
+		// Get root agent
+		agent, err := team.Agent("root")
+		require.NoError(t, err)
+
+		// Verify bang commands are enabled
+		assert.True(t, agent.EnableBangCommands())
+	})
+
+	t.Run("load config with bang commands disabled", func(t *testing.T) {
+		yamlContent := `version: "2"
+agents:
+  root:
+    model: openai/gpt-4o
+    enable_bang_commands: false
+    toolsets:
+      - type: think
+`
+		// Create temp file
+		tmpDir := t.TempDir()
+		tmpFile := filepath.Join(tmpDir, "test.yaml")
+		err := os.WriteFile(tmpFile, []byte(yamlContent), 0644)
+		require.NoError(t, err)
+
+		// Load team
+		team, err := Load(context.Background(), tmpFile, config.RuntimeConfig{}, WithModelOverrides(nil))
+		require.NoError(t, err)
+		require.NotNil(t, team)
+
+		// Get root agent
+		agent, err := team.Agent("root")
+		require.NoError(t, err)
+
+		// Verify bang commands are disabled
+		assert.False(t, agent.EnableBangCommands())
+	})
+
+	t.Run("default is false when omitted", func(t *testing.T) {
+		yamlContent := `version: "2"
+agents:
+  root:
+    model: openai/gpt-4o
+    toolsets:
+      - type: think
+`
+		// Create temp file
+		tmpDir := t.TempDir()
+		tmpFile := filepath.Join(tmpDir, "test.yaml")
+		err := os.WriteFile(tmpFile, []byte(yamlContent), 0644)
+		require.NoError(t, err)
+
+		// Load team
+		team, err := Load(context.Background(), tmpFile, config.RuntimeConfig{}, WithModelOverrides(nil))
+		require.NoError(t, err)
+		require.NotNil(t, team)
+
+		// Get root agent
+		agent, err := team.Agent("root")
+		require.NoError(t, err)
+
+		// Verify bang commands default to false
+		assert.False(t, agent.EnableBangCommands())
+	})
+}