feat(tools): configurable LLM tool list (#46)

* test(tools): RED tests for configurable LLM tool list

Add failing tests that define the contract for a new tools configuration
section:

- internal/config/tools_test.go: ToolConfig loading from global/project
  config, env vars (ODEK_TOOLS_ENABLED/DISABLED), and CLI flags. Project
  config may only disable tools, not enable them.
- internal/tool/filter_test.go: ToolFilter whitelist/blacklist semantics,
  required-tool preservation, and unknown-name tolerance.
- cmd/odek/run_flags_tools_test.go: --tool/--no-tool CLI flag parsing.

* feat(tools): configurable LLM tool list via tools config, env, and --tool/--no-tool

Add a new  config section with  (whitelist) and
(blacklist) plus CLI flags  /  and env vars
 / . This supports deployments
where odek should only expose a subset of tools, e.g. a chatbot with
web_search + voice but no shell or file writes.

Key changes:
- internal/config/loader.go: ToolConfig/ToolsConfig types, file/env/CLI
  merge logic, and project-level security restriction (project config can
  only disable, never enable).
- internal/tool/registry.go: FilterTools helper with whitelist/blacklist
  and required-tool preservation.
- odek.go: ToolFilterConfig on Config; memory tool is no longer appended
  unconditionally — it respects the filter.
- cmd/odek/*.go: wire filtering into run, continue, repl, serve, telegram,
  subagent, schedule, and mcp surfaces.
- Docs and help text updated with examples and env vars.

Tests:
- internal/config/tools_test.go
- internal/tool/filter_test.go
- cmd/odek/run_flags_tools_test.go
- odek_test.go memory-filter regression tests

All existing tests pass.

* docs(tools): add TOOL_SELECTION.md user guide

Explain default behaviour (all tools registered), the four configuration
layers, whitelist vs blacklist semantics, security restriction on project
config, and concrete deployment examples (chatbot, read-only research,
locked-down CI, memory disable). Include the full tool-name reference table.

* docs(tools): add ChatBot example and clarify Telegram-only tools

Replace the confusing CLI chatbot example (which mixed whitelist and
blacklist and referenced Telegram-only send_message) with a clear ChatBot
config example suitable for ~/.odek/config.json and odek serve. Explain
why each tool is included and note that send_message/clarify are only
auto-injected by odek telegram.

* docs(tools): clarify session tool surface

Only session_search is exposed to the LLM; session management is handled
by the odek session CLI command and --session/--continue flags.

* fix(tools): apply filter after MCP tools, clean up config template and signatures

- Remove empty tools block from default config template so odek config init
  does not disable every tool.
- Apply tools.enabled/tools.disabled after MCP tools are loaded so MCP tool
  names can be filtered too (run, continue, repl, serve, subagent, mcp, schedule).
- Correct ToolFilter comment to reflect that it only filters auto-registered
  tools, not caller-supplied Tools.
- Return explicit errors for serve --tool/--no-tool without values.
- Make FilterTools whitelist order deterministic.
- Remove unused sliceContains helper and stale RED-test comments.
- Document --tool/--no-tool for serve and repl in docs/CLI.md.
- Flatten filterBuiltinTools variadic signature.
- Add serve-mode tool flag parsing tests.

Author: jkyberneees

cmd/odek/main.go

@@ -26,6 +26,7 @@ import (
 	"github.com/BackendStack21/odek/internal/session"
 	"github.com/BackendStack21/odek/internal/skills"
 	"github.com/BackendStack21/odek/internal/telegram"
+	"github.com/BackendStack21/odek/internal/tool"
 )
 
 // version is set at build time via ldflags: -ldflags "-X main.version=v0.2.1"
@@ -253,8 +254,14 @@ type runFlags struct {
 	NoAgents       *bool   // nil = not set
 	PromptCaching  *bool   // nil = not set; true = enable prompt caching
 	Session        *bool   // nil = not set; true = save session after run
-	Learn          *bool   // nil = not set; true = enable skills learning mode
-	Task           string
+	Learn    *bool // nil = not set; true = enable skills learning mode
+	Task     string
+
+	// ToolsEnabled and ToolsDisabled control which tools are exposed to the LLM.
+	// Repeated --tool/--no-tool flags accumulate. They are the highest priority
+	// layer after file config and env vars.
+	ToolsEnabled  []string
+	ToolsDisabled []string
 	Ctx            []string // --ctx files to attach
 
 	// Sandbox-specific CLI flags
@@ -333,6 +340,18 @@ func parseRunFlags(args []string) (runFlags, error) {
 		case "--no-learn":
 			f.Learn = boolPtr(false)
 			i++
+		case "--tool":
+			if i+1 >= len(args) {
+				return f, fmt.Errorf("--tool requires a value")
+			}
+			f.ToolsEnabled = append(f.ToolsEnabled, args[i+1])
+			i += 2
+		case "--no-tool":
+			if i+1 >= len(args) {
+				return f, fmt.Errorf("--no-tool requires a value")
+			}
+			f.ToolsDisabled = append(f.ToolsDisabled, args[i+1])
+			i += 2
 		case "--no-color":
 			f.NoColor = boolPtr(true)
 			i++
@@ -604,6 +623,8 @@ Run flags:
   --session            Save conversation as a multi-turn session
   --learn              Enable skill learning mode — on by default, no flag needed
   --no-learn           Disable skill learning mode (overrides config/default)
+  --tool <name>        Enable a tool for the LLM (repeatable)
+  --no-tool <name>     Disable a tool for the LLM (repeatable)
   --system <prompt>    System prompt override
 
 Skill commands:
@@ -641,6 +662,8 @@ Environment variables:
   ODEK_NO_COLOR        true/false — disable colors
   ODEK_NO_AGENTS       true/false — skip AGENTS.md
   ODEK_SYSTEM          System prompt override
+  ODEK_TOOLS_ENABLED   Comma-separated tool whitelist
+  ODEK_TOOLS_DISABLED  Comma-separated tool blacklist
   ODEK_SANDBOX_IMAGE   Docker image for sandbox container
   ODEK_SANDBOX_NETWORK Network mode (none | bridge | host)
   ODEK_SANDBOX_READONLY true/false — mount read-only
@@ -835,6 +858,8 @@ func run(args []string) error {
 		Learn:         f.Learn,
 		System:        f.System,
 		Task:          f.Task,
+		ToolsEnabled:  f.ToolsEnabled,
+		ToolsDisabled: f.ToolsDisabled,
 
 		SandboxImage:    f.SandboxImage,
 		SandboxNetwork:  f.SandboxNetwork,
@@ -892,6 +917,10 @@ func run(args []string) error {
 		defer mcpCleanup()
 	}
 
+	// Apply tool filtering based on configuration (after MCP tools are loaded
+	// so disabled/enabled lists can reference MCP tool names too).
+	tools = filterBuiltinTools(tools, resolved.Tools, nil)
+
 	if resolved.Sandbox {
 		var containerName string
 		containerName, sandboxCleanup, err = setupSandbox(tools, sbCfg)
@@ -951,6 +980,7 @@ func run(args []string) error {
 		ThinkingBudget:  f.ThinkingBudget,
 		Temperature:     0, // deterministic by default; override with --temperature
 		Tools:           tools,
+		ToolFilter:      odek.ToolFilterConfig{Enabled: resolved.Tools.Enabled, Disabled: resolved.Tools.Disabled},
 		SandboxCleanup:  sandboxCleanup,
 		Renderer:        rend,
 		Skills:          skillsCfg,
@@ -1235,6 +1265,34 @@ func builtinTools(dc danger.DangerousConfig, sm *skills.SkillManager, approver d
 	return tools
 }
 
+// filterBuiltinTools applies the configured tools.enabled / tools.disabled
+// lists to a slice of tools. Unknown names are ignored. Required tools are
+// always preserved.
+func filterBuiltinTools(tools []odek.Tool, cfg config.ToolConfig, required map[string]bool) []odek.Tool {
+	adapted := make([]tool.Tool, len(tools))
+	for i, t := range tools {
+		adapted[i] = odekToolAdapter{t}
+	}
+	filtered := tool.FilterTools(adapted, cfg.Enabled, cfg.Disabled, required)
+	out := make([]odek.Tool, len(filtered))
+	for i, t := range filtered {
+		out[i] = t.(odekToolAdapter).tool
+	}
+	return out
+}
+
+// odekToolAdapter bridges odek.Tool to internal/tool.Tool.
+type odekToolAdapter struct {
+	tool odek.Tool
+}
+
+func (a odekToolAdapter) Name() string        { return a.tool.Name() }
+func (a odekToolAdapter) Description() string { return a.tool.Description() }
+func (a odekToolAdapter) Schema() any         { return a.tool.Schema() }
+func (a odekToolAdapter) Call(args string) (string, error) {
+	return a.tool.Call(args)
+}
+
 // loadMCPTools connects to configured MCP servers and appends their tools
 // to the tool slice. Returns a cleanup function that closes all connections.
 // The passed-in tool slice pointer is extended with ToolAdapters.
@@ -1792,7 +1850,6 @@ func continueCmd(args []string) error {
 		)
 	}
 	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{Transcription: resolved.Transcription, Vision: resolved.Vision, WebSearch: resolved.WebSearch}, store)
-	var sandboxCleanup func() error
 
 	// MCP server tools
 	var mcpCleanup func()
@@ -1805,9 +1862,14 @@ func continueCmd(args []string) error {
 		defer mcpCleanup()
 	}
 
+	// Apply tool filtering based on configuration (after MCP tools are loaded
+	// so disabled/enabled lists can reference MCP tool names too).
+	tools = filterBuiltinTools(tools, resolved.Tools, nil)
+
 	systemMessage := buildSystemPrompt(resolved)
 
-	// Sandbox (if enabled in config) (second occurrence)
+	var sandboxCleanup func() error
+
 	if resolved.Sandbox {
 		sbCfg := sandboxConfig{
 			Image:    resolved.SandboxImage,
@@ -1853,6 +1915,7 @@ func continueCmd(args []string) error {
 		Thinking:        resolved.Thinking,
 		Temperature:     0, // deterministic by default; override with --temperature
 		Tools:           tools,
+		ToolFilter:      odek.ToolFilterConfig{Enabled: resolved.Tools.Enabled, Disabled: resolved.Tools.Disabled},
 		SandboxCleanup:  sandboxCleanup,
 		Renderer:        rend,
 		Skills:          skillsCfg,

cmd/odek/mcp.go

@@ -87,6 +87,10 @@ Flags:
 		defer mcpCleanup()
 	}
 
+	// Apply tool filtering based on configuration (after MCP tools are loaded
+	// so disabled/enabled lists can reference MCP tool names too).
+	toolSet = filterBuiltinTools(toolSet, resolved.Tools, nil)
+
 	// Sandbox setup (must happen after tools are created)
 	var sandboxCleanup func() error
 	if resolved.Sandbox {

cmd/odek/repl.go

@@ -79,7 +79,6 @@ func replCmd(args []string) error {
 		)
 	}
 	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{WebSearch: resolved.WebSearch}, nil)
-	var sandboxCleanup func() error
 
 	// MCP server tools
 	var mcpCleanup func()
@@ -92,6 +91,12 @@ func replCmd(args []string) error {
 		defer mcpCleanup()
 	}
 
+	// Apply tool filtering based on configuration (after MCP tools are loaded
+	// so disabled/enabled lists can reference MCP tool names too).
+	tools = filterBuiltinTools(tools, resolved.Tools, nil)
+
+	var sandboxCleanup func() error
+
 	if resolved.Sandbox {
 		sbCfg := sandboxConfig{
 			Image:    resolved.SandboxImage,
@@ -139,6 +144,7 @@ func replCmd(args []string) error {
 		Thinking:       resolved.Thinking,
 		ThinkingBudget: f.ThinkingBudget,
 		Tools:          tools,
+		ToolFilter:     odek.ToolFilterConfig{Enabled: resolved.Tools.Enabled, Disabled: resolved.Tools.Disabled},
 		SandboxCleanup: sandboxCleanup,
 		Renderer:       rend,
 		Skills:         skillsCfg,

cmd/odek/run_flags_tools_test.go

@@ -0,0 +1,82 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestParseRunFlags_ToolWhitelist(t *testing.T) {
+	f, err := parseRunFlags([]string{
+		"--tool", "web_search",
+		"--tool", "transcribe",
+		"--tool", "vision",
+		"hello",
+	})
+	if err != nil {
+		t.Fatalf("parseRunFlags error: %v", err)
+	}
+	want := []string{"web_search", "transcribe", "vision"}
+	if !reflect.DeepEqual(f.ToolsEnabled, want) {
+		t.Errorf("ToolsEnabled = %v, want %v", f.ToolsEnabled, want)
+	}
+}
+
+func TestParseRunFlags_ToolBlacklist(t *testing.T) {
+	f, err := parseRunFlags([]string{
+		"--no-tool", "shell",
+		"--no-tool", "write_file",
+		"hello",
+	})
+	if err != nil {
+		t.Fatalf("parseRunFlags error: %v", err)
+	}
+	want := []string{"shell", "write_file"}
+	if !reflect.DeepEqual(f.ToolsDisabled, want) {
+		t.Errorf("ToolsDisabled = %v, want %v", f.ToolsDisabled, want)
+	}
+}
+
+func TestParseRunFlags_ToolMixed(t *testing.T) {
+	f, err := parseRunFlags([]string{
+		"--tool", "web_search",
+		"--no-tool", "shell",
+		"--tool", "vision",
+		"--no-tool", "delegate_tasks",
+		"hello",
+	})
+	if err != nil {
+		t.Fatalf("parseRunFlags error: %v", err)
+	}
+	wantEnabled := []string{"web_search", "vision"}
+	wantDisabled := []string{"shell", "delegate_tasks"}
+	if !reflect.DeepEqual(f.ToolsEnabled, wantEnabled) {
+		t.Errorf("ToolsEnabled = %v, want %v", f.ToolsEnabled, wantEnabled)
+	}
+	if !reflect.DeepEqual(f.ToolsDisabled, wantDisabled) {
+		t.Errorf("ToolsDisabled = %v, want %v", f.ToolsDisabled, wantDisabled)
+	}
+}
+
+func TestParseRunFlags_ToolRequiresValue(t *testing.T) {
+	_, err := parseRunFlags([]string{"--tool"})
+	if err == nil {
+		t.Fatal("expected error for --tool without value")
+	}
+	_, err = parseRunFlags([]string{"--no-tool"})
+	if err == nil {
+		t.Fatal("expected error for --no-tool without value")
+	}
+}
+
+func TestParseRunFlags_ToolDefaults(t *testing.T) {
+	f, err := parseRunFlags([]string{"hello"})
+	if err != nil {
+		t.Fatalf("parseRunFlags error: %v", err)
+	}
+	if len(f.ToolsEnabled) != 0 {
+		t.Errorf("ToolsEnabled should default to empty, got %v", f.ToolsEnabled)
+	}
+	if len(f.ToolsDisabled) != 0 {
+		t.Errorf("ToolsDisabled should default to empty, got %v", f.ToolsDisabled)
+	}
+}

cmd/odek/schedule.go

@@ -671,8 +671,13 @@ func runTaskHeadless(ctx context.Context, resolved config.ResolvedConfig, system
 	dangerCfg := buildHeadlessDangerConfig(resolved)
 
 	tools := builtinTools(dangerCfg, nil, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{Transcription: resolved.Transcription, Vision: resolved.Vision, WebSearch: resolved.WebSearch}, nil)
+
 	tools = append(tools, mcpTools...)
 
+	// Apply tool filtering based on configuration (after MCP tools are appended
+	// so disabled/enabled lists can reference MCP tool names too).
+	tools = filterBuiltinTools(tools, resolved.Tools, nil)
+
 	// Capture cumulative token usage from the final iteration so the Runner
 	// can report it (the engine logs it; the bot bills it against the budget).
 	// RunWithMessages drives the loop synchronously on this goroutine, so the
@@ -691,6 +696,7 @@ func runTaskHeadless(ctx context.Context, resolved config.ResolvedConfig, system
 		Thinking:          resolved.Thinking,
 		Temperature:       0,
 		Tools:             tools,
+		ToolFilter:        odek.ToolFilterConfig{Enabled: resolved.Tools.Enabled, Disabled: resolved.Tools.Disabled},
 		Renderer:          render.New(io.Discard, false), // silent: unattended
 		InteractionMode:   "off",
 		PromptCaching:     resolved.PromptCaching,

cmd/odek/serve.go

@@ -185,6 +185,7 @@ func serveCmd(args []string) error {
 	var sandboxReadonly *bool
 	var promptCaching *bool
 	var sandboxImage, sandboxNetwork, sandboxMemory, sandboxCPUs, sandboxUser string
+	var toolsEnabled, toolsDisabled []string
 
 	for i := 0; i < len(args); i++ {
 		switch args[i] {
@@ -232,6 +233,18 @@ func serveCmd(args []string) error {
 			}
 		case "--prompt-caching":
 			promptCaching = boolPtr(true)
+		case "--tool":
+			i++
+			if i >= len(args) {
+				return fmt.Errorf("--tool requires a value")
+			}
+			toolsEnabled = append(toolsEnabled, args[i])
+		case "--no-tool":
+			i++
+			if i >= len(args) {
+				return fmt.Errorf("--no-tool requires a value")
+			}
+			toolsDisabled = append(toolsDisabled, args[i])
 		default:
 			return fmt.Errorf("unknown flag %q for serve", args[i])
 		}
@@ -246,6 +259,8 @@ func serveCmd(args []string) error {
 		SandboxMemory:   sandboxMemory,
 		SandboxCPUs:     sandboxCPUs,
 		SandboxUser:     sandboxUser,
+		ToolsEnabled:    toolsEnabled,
+		ToolsDisabled:   toolsDisabled,
 	})
 	// Serve mode default-on for sandbox: the Web UI surface is the
 	// largest blast radius (browser-driven tool calls, untrusted-page
@@ -331,6 +346,8 @@ Flags:
   --sandbox-memory limit   Container memory limit (e.g. 512m, 2g)
   --sandbox-cpus limit     Container CPU limit (e.g. 0.5, 2, 4)
   --sandbox-user user      Container user (e.g. 1000:1000)
+  --tool name              Enable a tool for the LLM (repeatable)
+  --no-tool name           Disable a tool for the LLM (repeatable)
   --help, -h               Show this help`)
 }
 
@@ -412,6 +429,20 @@ func newServeAgent(resolved config.ResolvedConfig, system string, sendFn func(v
 
 	tools := builtinTools(resolved.Dangerous, sm, approver, resolved.MaxConcurrency, resolved.APIKey, toolConfig{WebSearch: resolved.WebSearch}, nil)
 
+	// MCP server tools
+	var mcpCleanup func()
+	if len(resolved.MCPServers) > 0 {
+		cl, err := loadMCPTools(resolved, &tools)
+		if err != nil {
+			return nil, nil, nil, nil, fmt.Errorf("mcp: %w", err)
+		}
+		mcpCleanup = cl
+	}
+
+	// Apply tool filtering based on configuration (after MCP tools are loaded
+	// so disabled/enabled lists can reference MCP tool names too).
+	tools = filterBuiltinTools(tools, resolved.Tools, nil)
+
 	// Find the delegateTasksTool to wire up sub-agent log streaming
 	var subagentTool *delegateTasksTool
 	for _, t := range tools {
@@ -441,16 +472,6 @@ func newServeAgent(resolved config.ResolvedConfig, system string, sendFn func(v
 	}
 	var sandboxCleanup func() error
 
-	// MCP server tools
-	var mcpCleanup func()
-	if len(resolved.MCPServers) > 0 {
-		cl, err := loadMCPTools(resolved, &tools)
-		if err != nil {
-			return nil, nil, nil, nil, fmt.Errorf("mcp: %w", err)
-		}
-		mcpCleanup = cl
-	}
-
 	if resolved.Sandbox {
 		cfg := sandboxConfig{
 			Image:    resolved.SandboxImage,
@@ -503,6 +524,7 @@ func newServeAgent(resolved config.ResolvedConfig, system string, sendFn func(v
 		Thinking:        resolved.Thinking,
 		InteractionMode: resolved.InteractionMode,
 		Tools:           tools,
+		ToolFilter:      odek.ToolFilterConfig{Enabled: resolved.Tools.Enabled, Disabled: resolved.Tools.Disabled},
 		// SandboxCleanup is intentionally NOT passed here. In serve mode,
 		// cleanup is the caller's responsibility (handleWS defers it).
 		// Passing it here would cause agent.Close() to call docker rm -f,