@@ -31,12 +31,12 @@ Common issues, error messages, and solutions for the `code_execution` tool.
 Error: code_execution is disabled in configuration. Set 'enable_code_execution: true' in config file.
 ```
 
-**Cause**: The `code_execution` feature is disabled by default for security.
+**Cause**: The `code_execution` feature is disabled by default for security. While it is disabled the tool is not listed in `tools/list`, so an MCP client will normally not see it at all; this error appears when a call reaches the handler by name anyway (the REST API or the CLI). An MCP client that calls the name from a stale tool list gets an unknown-tool error instead.
 
 **Solution**:
 1. Edit your configuration file (`~/.mcpproxy/mcp_config.json`)
 2. Add or update: `"enable_code_execution": true`
-3. Restart mcpproxy: `pkill mcpproxy && mcpproxy serve`
+3. The flag is hot-reloaded: the running proxy picks up the change, advertises the tool, and sends `notifications/tools/list_changed` to connected sessions. No restart is needed; clients that do not honor `list_changed` need to reconnect to see the tool.
 
 **Example Configuration**:
 ```json
@@ -56,13 +56,12 @@ Error: code_execution is disabled in configuration. Set 'enable_code_execution:
 
 **Symptom**: LLM agent lists available tools but `code_execution` is missing.
 
-**Cause**: Feature is not enabled or server didn't restart after configuration change.
+**Cause**: Feature is not enabled — a disabled `code_execution` is deliberately absent from `tools/list` — or the client is holding a tool list from before the flag was enabled.
 
 **Solution**:
 1. Verify configuration has `"enable_code_execution": true`
-2. Restart mcpproxy server
-3. Reconnect LLM client
-4. List tools again
+2. The change is hot-reloaded and announced with `notifications/tools/list_changed`; if the client does not honor that notification, reconnect it
+3. List tools again
 
 **Verification**:
 ```bash
 
@@ -1264,7 +1264,7 @@ See [Tool Quarantine](features/tool-quarantine.md) for complete details.
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `enable_code_execution` | boolean | `false` | Enable JavaScript/TypeScript code execution tool (disabled by default for security) |
+| `enable_code_execution` | boolean | `false` | Enable JavaScript/TypeScript code execution tool (disabled by default for security). While `false` the `code_execution` tool is not advertised in `tools/list`. Hot-reloaded: a flip adds/removes the tool and sends `notifications/tools/list_changed` |
 | `code_execution_timeout_ms` | integer | `120000` | Default timeout in milliseconds (1-600000, max 10 minutes) |
 | `code_execution_max_tool_calls` | integer | `0` | Maximum tool calls per execution (0 = unlimited) |
 | `code_execution_pool_size` | integer | `10` | Number of JavaScript VM instances in pool (1-100) |
 
@@ -37,7 +37,7 @@ Enable code execution in your config:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `enable_code_execution` | boolean | `false` | Enable the code execution tool |
+| `enable_code_execution` | boolean | `false` | Enable the code execution tool. While `false` the tool is not listed in `tools/list`; a flip is hot-reloaded and announced with `notifications/tools/list_changed` |
 | `code_execution_timeout_ms` | integer | `120000` | Execution timeout (2 minutes) |
 | `code_execution_max_tool_calls` | integer | `0` | Max tool calls (0 = unlimited) |
 | `code_execution_pool_size` | integer | `10` | Number of VM instances to pool |
 
@@ -165,7 +165,7 @@ Code execution mode is designed for multi-step orchestration workflows. Instead
 - Complex conditional logic that would require many round-trips in other modes
 - Data transformation pipelines (fetch from one tool, transform, send to another)
 
-**Note:** Code execution must be enabled in config (`"enable_code_execution": true`). If disabled, the `code_execution` tool appears but returns an error message directing the user to enable it.
+**Note:** Code execution must be enabled in config (`"enable_code_execution": true`). While it is disabled, the `code_execution` tool is not listed in `tools/list` on any endpoint, so clients that pick tools from the list never attempt it. An MCP `tools/call` for the name is refused as an unknown tool; a call that reaches the handler through the REST API or the CLI is refused with an error directing the user to enable it. The flag is hot-reloadable: flipping it adds or removes the tool on the live surfaces and sends `notifications/tools/list_changed` to connected sessions, no restart required.
 
 ## Choosing the Right Mode
 
 
@@ -1,8 +1,10 @@
 package server
 
 import (
+	"context"
 	"testing"
 
+	"github.com/mark3labs/mcp-go/mcp"
 	mcpserver "github.com/mark3labs/mcp-go/server"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -11,18 +13,18 @@ import (
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 )
 
-// UX audit F16: Settings advertises enable_code_execution as an
-// instantly-applied field, but the tool surfaces built their code_execution
-// entry — the live tool, or a "disabled" stub whose handler refuses every call
-// unconditionally — exactly once, at construction. Flipping the flag on
-// therefore left the stub in place on /mcp, so `code_execution` kept answering
-// "Code execution is disabled" from a brand-new MCP session until a restart,
-// even though the handler-level gate (mcp_code_execution.go) had already gone
-// live. These tests pin the rebuild seam that makes the promise true.
-
-func isDisabledCodeExecutionStub(tool mcpserver.ServerTool) bool {
-	return tool.Tool.Annotations.Title == "Code Execution (Disabled)"
-}
+// Issue #1236: with enable_code_execution=false (the default) the tool surfaces
+// used to advertise a "disabled" code_execution stub whose handler refused every
+// call. Clients that pick tools from tools/list rather than from descriptions —
+// most of them — kept calling it and burning a round trip per attempt. The
+// contract is now: disabled → NOT advertised on any surface; a runtime toggle
+// (config hot-reload) re-advertises or withdraws the tool and emits
+// notifications/tools/list_changed so caching clients refetch. These tests pin
+// both halves.
+//
+// UX audit F16 (the prior shape of this file) established that the builder
+// resolves the flag on every call and that RefreshCodeExecutionAvailability is
+// the seam config.reloaded drives; those guarantees carry over unchanged.
 
 func codeExecutionToolFrom(tools []mcpserver.ServerTool) *mcpserver.ServerTool {
 	for i := range tools {
@@ -33,107 +35,223 @@ func codeExecutionToolFrom(tools []mcpserver.ServerTool) *mcpserver.ServerTool {
 	return nil
 }
 
-// TestBuildCodeExecutionTool_FollowsCurrentConfig: the builder must resolve the
-// flag on every call, not capture it. currentConfig() falls back to p.config
-// when no runtime is attached, so mutating that snapshot models a hot reload.
+// advertisedCodeExecution returns the registered code_execution entry on a
+// server, or nil when the surface does not list it.
+func advertisedCodeExecution(s *mcpserver.MCPServer) *mcpserver.ServerTool {
+	tool, ok := s.ListTools()["code_execution"]
+	if !ok {
+		return nil
+	}
+	return tool
+}
+
+// notifyingSession is an initialized mcp-go ClientSession whose notification
+// channel is captured, so a test can observe what the server pushed to a
+// connected client. It stands in for a real Streamable HTTP session.
+type notifyingSession struct {
+	id string
+	ch chan mcp.JSONRPCNotification
+}
+
+func newNotifyingSession(id string) *notifyingSession {
+	return &notifyingSession{id: id, ch: make(chan mcp.JSONRPCNotification, 16)}
+}
+
+func (s *notifyingSession) Initialize()                                         {}
+func (s *notifyingSession) Initialized() bool                                   { return true }
+func (s *notifyingSession) NotificationChannel() chan<- mcp.JSONRPCNotification { return s.ch }
+func (s *notifyingSession) SessionID() string                                   { return s.id }
+
+// drainListChanged counts the notifications/tools/list_changed pushes queued
+// on the session and empties the channel.
+func (s *notifyingSession) drainListChanged() int {
+	n := 0
+	for {
+		select {
+		case notif := <-s.ch:
+			if notif.Method == mcp.MethodNotificationToolsListChanged {
+				n++
+			}
+		default:
+			return n
+		}
+	}
+}
+
+// newHotReloadProxy builds a proxy with all three built-in-carrying surfaces
+// registered the way production does it — the routing-mode servers through
+// initRoutingModeServers (which also seeds their content guards), the default
+// surface the way registerTools assembles it — plus one initialized session
+// per surface so list_changed pushes are observable.
+func newHotReloadProxy(t *testing.T, cfg *config.Config) (*MCPProxyServer, map[string]*notifyingSession) {
+	t.Helper()
+	p := &MCPProxyServer{
+		config: cfg,
+		logger: zap.NewNop(),
+		server: mcpserver.NewMCPServer("test", "0.0.0", mcpserver.WithToolCapabilities(true)),
+	}
+	p.initRoutingModeServers()
+	require.NotNil(t, p.callToolServer)
+	require.NotNil(t, p.codeExecServer)
+	// The default surface is assembled by registerTools; the call-tool set is
+	// a faithful stand-in (same built-ins, same code_execution gating).
+	for _, st := range p.buildCallToolModeTools() {
+		p.server.AddTool(st.Tool, st.Handler)
+	}
+
+	sessions := map[string]*notifyingSession{}
+	for name, s := range map[string]*mcpserver.MCPServer{
+		"call_tool": p.callToolServer,
+		"code_exec": p.codeExecServer,
+		"default":   p.server,
+	} {
+		sess := newNotifyingSession("sess-" + name)
+		require.NoError(t, s.RegisterSession(context.Background(), sess))
+		sess.drainListChanged() // registration-time noise, if any
+		sessions[name] = sess
+	}
+	return p, sessions
+}
+
+// TestBuildCodeExecutionTool_FollowsCurrentConfig: the builder resolves the
+// flag on every call, and a disabled flag yields NO tool — not a stub.
+// currentConfig() falls back to p.config when no runtime is attached, so
+// mutating that snapshot models a hot reload.
 func TestBuildCodeExecutionTool_FollowsCurrentConfig(t *testing.T) {
 	cfg := &config.Config{EnableCodeExecution: false}
 	p := &MCPProxyServer{config: cfg}
 
-	disabled := p.buildCodeExecutionTool()
-	require.Len(t, disabled, 1)
-	assert.True(t, isDisabledCodeExecutionStub(disabled[0]), "expected the disabled stub while the flag is off")
+	assert.Empty(t, p.buildCodeExecutionTool(),
+		"issue #1236: a disabled code_execution must not be advertised at all")
 
 	cfg.EnableCodeExecution = true
 	enabled := p.buildCodeExecutionTool()
 	require.Len(t, enabled, 1)
-	assert.False(t, isDisabledCodeExecutionStub(enabled[0]), "the live tool must appear once the flag is on")
+	assert.Equal(t, "code_execution", enabled[0].Tool.Name)
 	assert.Equal(t, codeExecutionToolDescription, enabled[0].Tool.Description)
+	assert.Equal(t, "Code Execution", enabled[0].Tool.Annotations.Title)
 
 	cfg.EnableCodeExecution = false
-	assert.True(t, isDisabledCodeExecutionStub(p.buildCodeExecutionTool()[0]),
-		"turning the flag back off must restore the stub")
+	assert.Empty(t, p.buildCodeExecutionTool(),
+		"turning the flag back off must withdraw the tool again")
 }
 
-// TestRefreshCodeExecutionAvailability_SwapsAdvertisedTool: the call-tool
-// surface (/mcp in the default retrieve_tools routing mode) and the code-exec
-// surface must both re-advertise code_execution after a config reload.
-func TestRefreshCodeExecutionAvailability_SwapsAdvertisedTool(t *testing.T) {
-	cfg := &config.Config{EnableCodeExecution: false}
-	p := &MCPProxyServer{
-		config:         cfg,
-		logger:         zap.NewNop(),
-		callToolServer: mcpserver.NewMCPServer("test", "0.0.0"),
-		codeExecServer: mcpserver.NewMCPServer("test", "0.0.0"),
-		server:         mcpserver.NewMCPServer("test", "0.0.0"),
-	}
+// TestRoutingModeSurfaces_OmitDisabledCodeExecution: neither routing-mode
+// builder may carry code_execution while the flag is off. The retrieve_tools
+// surface is what /mcp serves in the default routing mode, so this is the
+// listing the issue reporter saw.
+func TestRoutingModeSurfaces_OmitDisabledCodeExecution(t *testing.T) {
+	p := &MCPProxyServer{config: &config.Config{EnableCodeExecution: false}, logger: zap.NewNop()}
 
-	for _, st := range p.buildCallToolModeTools() {
-		p.callToolServer.AddTool(st.Tool, st.Handler)
-	}
-	for _, st := range p.buildCodeExecModeTools() {
-		p.codeExecServer.AddTool(st.Tool, st.Handler)
-	}
+	assert.Nil(t, codeExecutionToolFrom(p.buildCallToolModeTools()),
+		"retrieve_tools mode (/mcp default) must not list a disabled code_execution")
+	assert.Nil(t, codeExecutionToolFrom(p.buildCodeExecModeTools()),
+		"code_execution mode must not list a disabled code_execution")
 
-	advertised := func(s *mcpserver.MCPServer) *mcpserver.ServerTool {
-		tool, ok := s.ListTools()["code_execution"]
-		if !ok {
-			return nil
-		}
-		return tool
-	}
+	p.config.EnableCodeExecution = true
+	assert.NotNil(t, codeExecutionToolFrom(p.buildCallToolModeTools()))
+	assert.NotNil(t, codeExecutionToolFrom(p.buildCodeExecModeTools()))
+}
+
+// TestRefreshCodeExecutionAvailability_TogglesAdvertisedTool: a hot enable
+// adds code_execution to every surface that carries it and a hot disable
+// withdraws it again — including the default surface, which is updated in
+// place (AddTools / DeleteTools) rather than rebuilt.
+func TestRefreshCodeExecutionAvailability_TogglesAdvertisedTool(t *testing.T) {
+	cfg := &config.Config{EnableCodeExecution: false}
+	p, _ := newHotReloadProxy(t, cfg)
 
-	require.NotNil(t, advertised(p.callToolServer))
-	assert.True(t, isDisabledCodeExecutionStub(*advertised(p.callToolServer)))
-	assert.True(t, isDisabledCodeExecutionStub(*advertised(p.codeExecServer)))
+	require.Nil(t, advertisedCodeExecution(p.callToolServer), "precondition: disabled at startup")
+	require.Nil(t, advertisedCodeExecution(p.codeExecServer))
+	require.Nil(t, advertisedCodeExecution(p.server))
 
 	// The operator flips the toggle; ApplyConfig swaps the live snapshot and
 	// emits config.reloaded, which drives this call.
 	cfg.EnableCodeExecution = true
 	p.RefreshCodeExecutionAvailability()
 
-	require.NotNil(t, advertised(p.callToolServer), "code_execution must still be advertised")
-	assert.False(t, isDisabledCodeExecutionStub(*advertised(p.callToolServer)),
-		"the call-tool surface must serve the live tool after a hot enable")
-	assert.False(t, isDisabledCodeExecutionStub(*advertised(p.codeExecServer)),
-		"the code-exec surface must serve the live tool after a hot enable")
+	for name, s := range map[string]*mcpserver.MCPServer{
+		"call_tool": p.callToolServer, "code_exec": p.codeExecServer, "default": p.server,
+	} {
+		tool := advertisedCodeExecution(s)
+		require.NotNil(t, tool, "%s surface must advertise code_execution after a hot enable", name)
+		assert.Equal(t, codeExecutionToolDescription, tool.Tool.Description,
+			"%s surface must serve the live tool, never a stub", name)
+	}
+
+	// And back off again: the tool disappears from every surface.
+	cfg.EnableCodeExecution = false
+	p.RefreshCodeExecutionAvailability()
+
+	assert.Nil(t, advertisedCodeExecution(p.callToolServer),
+		"turning the flag off must withdraw code_execution from the retrieve_tools surface")
+	assert.Nil(t, advertisedCodeExecution(p.codeExecServer),
+		"turning the flag off must withdraw code_execution from the code-exec surface")
+	assert.Nil(t, advertisedCodeExecution(p.server),
+		"turning the flag off must withdraw code_execution from the default surface")
+}
+
+// TestRefreshCodeExecutionAvailability_EmitsListChangedOnlyOnAFlip: a runtime
+// toggle must push notifications/tools/list_changed to connected sessions on
+// every affected surface (the issue's second expectation), and an unrelated
+// config reload — which also drives this refresh — must push nothing, or every
+// config edit looks to a client exactly like the tool set changing.
+func TestRefreshCodeExecutionAvailability_EmitsListChangedOnlyOnAFlip(t *testing.T) {
+	cfg := &config.Config{EnableCodeExecution: false}
+	p, sessions := newHotReloadProxy(t, cfg)
 
-	// The default/stdio surface is updated in place with AddTools, which must
-	// not disturb the tools registerTools put there.
-	require.NotNil(t, advertised(p.server))
-	assert.False(t, isDisabledCodeExecutionStub(*advertised(p.server)))
+	// Unrelated reload: same flag value, nothing to announce.
+	p.RefreshCodeExecutionAvailability()
+	p.RefreshCodeExecutionAvailability()
+	for name, sess := range sessions {
+		assert.Zero(t, sess.drainListChanged(),
+			"%s surface: a reload that changes nothing must not emit list_changed", name)
+	}
 
-	// And back off again.
+	// Enable: exactly one list_changed per surface.
+	cfg.EnableCodeExecution = true
+	p.RefreshCodeExecutionAvailability()
+	for name, sess := range sessions {
+		assert.Equal(t, 1, sess.drainListChanged(),
+			"%s surface: a hot enable must emit exactly one list_changed", name)
+	}
+
+	// Steady state again: silence.
+	p.RefreshCodeExecutionAvailability()
+	for name, sess := range sessions {
+		assert.Zero(t, sess.drainListChanged(),
+			"%s surface: a reload after the flip must not re-announce it", name)
+	}
+
+	// Disable: exactly one list_changed per surface.
 	cfg.EnableCodeExecution = false
 	p.RefreshCodeExecutionAvailability()
-	assert.True(t, isDisabledCodeExecutionStub(*advertised(p.callToolServer)),
-		"turning the flag off must restore the refusing stub")
+	for name, sess := range sessions {
+		assert.Equal(t, 1, sess.drainListChanged(),
+			"%s surface: a hot disable must emit exactly one list_changed", name)
+	}
 }
 
 // TestRefreshCodeExecutionAvailability_PreservesOtherTools: the default surface
-// is refreshed with AddTools rather than SetTools precisely because its tool set
-// is assembled once by registerTools; SetTools would drop everything else.
+// is refreshed in place precisely because its tool set is assembled once by
+// registerTools; a rebuild would drop everything else. Neither the add nor the
+// remove may disturb the other registrations.
 func TestRefreshCodeExecutionAvailability_PreservesOtherTools(t *testing.T) {
 	cfg := &config.Config{EnableCodeExecution: false}
-	p := &MCPProxyServer{
-		config: cfg,
-		logger: zap.NewNop(),
-		server: mcpserver.NewMCPServer("test", "0.0.0"),
-	}
+	p, _ := newHotReloadProxy(t, cfg)
 
-	callToolTools := p.buildCallToolModeTools()
-	for _, st := range callToolTools {
-		p.server.AddTool(st.Tool, st.Handler)
-	}
 	before := len(p.server.ListTools())
 	require.Greater(t, before, 1)
 
 	cfg.EnableCodeExecution = true
 	p.RefreshCodeExecutionAvailability()
+	assert.Len(t, p.server.ListTools(), before+1,
+		"a hot enable adds code_execution and nothing else")
 
+	cfg.EnableCodeExecution = false
+	p.RefreshCodeExecutionAvailability()
 	assert.Len(t, p.server.ListTools(), before,
-		"refreshing code_execution must not add or drop any other tool")
-	assert.NotNil(t, codeExecutionToolFrom(callToolTools), "sanity: the builder emits code_execution")
+		"a hot disable removes code_execution and nothing else")
 }
 
 // TestRefreshCodeExecutionAvailability_NilSafe: the refresh runs from the shared