feat: MCP mid-session management, granular sandbox, additional dirs, fork session, hooks system

- MCP: toggle/reconnect servers mid-session via /mcp command
- Sandbox: granular config (network, filesystem, ignoreViolations, excludedCommands)
- Additional directories: multi-repo access via settings
- Fork session: option to fork Claude sessions
- Hooks: passive SDK callbacks for tool/notification/task observability
- Hooks route events to Discord as system messages when enabled
- Updated help docs with MCP and new feature entries

Author: zebbern

claude/client.ts

@@ -1,4 +1,4 @@
-import { query as claudeQuery, type SDKMessage, type AgentDefinition as SDKAgentDefinition, type ModelInfo as SDKModelInfo, type SdkBeta, type McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import { query as claudeQuery, type SDKMessage, type AgentDefinition as SDKAgentDefinition, type ModelInfo as SDKModelInfo, type SdkBeta, type McpServerConfig, type HookEvent, type HookCallbackMatcher } from "@anthropic-ai/claude-agent-sdk";
 import { setActiveQuery, trackMessageId, clearTrackedMessages } from "./query-manager.ts";
 import type { AskUserQuestionInput, AskUserCallback } from "./user-question.ts";
 import * as path from "https://deno.land/std@0.208.0/path/mod.ts";
@@ -111,10 +111,36 @@ export interface ClaudeModelOptions {
   betas?: SdkBeta[];
   /** Enable file checkpointing for undo/rewind */
   enableFileCheckpointing?: boolean;
-  /** Sandbox settings for safer command execution */
-  sandbox?: { enabled: boolean; autoAllowBashIfSandboxed?: boolean };
+  /** Sandbox settings for safer command execution — full SDK SandboxSettings */
+  sandbox?: {
+    enabled?: boolean;
+    autoAllowBashIfSandboxed?: boolean;
+    allowUnsandboxedCommands?: boolean;
+    network?: {
+      allowedDomains?: string[];
+      allowManagedDomainsOnly?: boolean;
+      allowUnixSockets?: string[];
+      allowAllUnixSockets?: boolean;
+      allowLocalBinding?: boolean;
+      httpProxyPort?: number;
+      socksProxyPort?: number;
+    };
+    filesystem?: {
+      allowWrite?: string[];
+      denyWrite?: string[];
+      denyRead?: string[];
+    };
+    ignoreViolations?: Record<string, string[]>;
+    excludedCommands?: string[];
+  };
   /** Enable experimental Agent Teams (multi-agent collaboration) */
   enableAgentTeams?: boolean;
+  /** Additional directories Claude can access beyond cwd (absolute paths) */
+  additionalDirectories?: string[];
+  /** Fork a resumed session into a new session instead of continuing the original */
+  forkSession?: boolean;
+  /** SDK hooks — deep integration callbacks for tool use, notifications, etc. */
+  hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
   /** Structured output format (JSON schema) */
   outputFormat?: { type: 'json_schema'; schema: Record<string, unknown> };
   /** Callback for AskUserQuestion tool — Claude asks the user mid-session.
@@ -212,10 +238,14 @@ export async function sendToClaudeCode(
           // Native SDK agent support
           ...(modelOptions?.agents && { agents: modelOptions.agents }),
           ...(modelOptions?.agent && { agent: modelOptions.agent }),
-          // Advanced features: betas, file checkpointing, sandbox
+          // Advanced features: betas, file checkpointing, sandbox, additional dirs, fork
           ...(modelOptions?.betas && modelOptions.betas.length > 0 && { betas: modelOptions.betas }),
           ...(modelOptions?.enableFileCheckpointing && { enableFileCheckpointing: true }),
           ...(modelOptions?.sandbox && { sandbox: modelOptions.sandbox }),
+          ...(modelOptions?.additionalDirectories && modelOptions.additionalDirectories.length > 0 && { additionalDirectories: modelOptions.additionalDirectories }),
+          ...(modelOptions?.forkSession && { forkSession: true }),
+          // SDK hooks — deep integration callbacks
+          ...(modelOptions?.hooks && Object.keys(modelOptions.hooks).length > 0 && { hooks: modelOptions.hooks }),
           ...(modelOptions?.outputFormat && { outputFormat: modelOptions.outputFormat }),
           // MCP servers from .claude/mcp.json
           ...(mcpServers && { mcpServers }),

claude/hooks.ts

@@ -0,0 +1,161 @@
+/**
+ * SDK Hooks — Discord-integrated hook callbacks for Claude Code SDK.
+ * 
+ * Hooks provide deep integration points that fire during query execution:
+ * - PreToolUse: Log/audit tool usage before execution
+ * - PostToolUse: Log completed tool usage
+ * - PostToolUseFailure: Log tool failures
+ * - Notification: Forward Claude's notifications to Discord
+ * - TaskCompleted: Notify when background tasks finish
+ * 
+ * All hooks are passive observers — they log to Discord but don't block execution.
+ * They return `{ continue: true }` to let the SDK proceed normally.
+ * 
+ * @module claude/hooks
+ */
+
+import type { 
+  HookCallbackMatcher, 
+  HookCallback,
+  HookInput,
+  PreToolUseHookInput,
+  PostToolUseHookInput,
+  PostToolUseFailureHookInput,
+  NotificationHookInput,
+  TaskCompletedHookInput,
+  HookEvent,
+  SyncHookJSONOutput,
+} from "@anthropic-ai/claude-agent-sdk";
+
+/**
+ * Configuration for which hooks to enable and how to route events.
+ */
+export interface HookConfig {
+  /** Enable tool-use logging (PreToolUse + PostToolUse + PostToolUseFailure) */
+  logToolUse: boolean;
+  /** Enable notification forwarding */
+  logNotifications: boolean;
+  /** Enable task completion notifications */
+  logTaskCompletions: boolean;
+  /** Callback to send hook events to Discord */
+  onHookEvent: (event: HookEvent_Discord) => void;
+}
+
+/**
+ * Discord-formatted hook event for display.
+ */
+export interface HookEvent_Discord {
+  type: 'tool_start' | 'tool_complete' | 'tool_failure' | 'notification' | 'task_completed';
+  toolName?: string;
+  // deno-lint-ignore no-explicit-any
+  toolInput?: any;
+  // deno-lint-ignore no-explicit-any
+  toolResponse?: any;
+  error?: string;
+  message?: string;
+  title?: string;
+  taskId?: string;
+  taskSubject?: string;
+  timestamp: number;
+}
+
+/**
+ * Build SDK hook callbacks based on the provided configuration.
+ * Returns a Partial<Record<HookEvent, HookCallbackMatcher[]>> suitable
+ * for passing directly to the SDK query `options.hooks`.
+ */
+export function buildHooks(config: HookConfig): Partial<Record<HookEvent, HookCallbackMatcher[]>> {
+  const hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>> = {};
+
+  if (config.logToolUse) {
+    // PreToolUse — log when a tool is about to be used
+    const preToolHook: HookCallback = async (input: HookInput) => {
+      const preInput = input as PreToolUseHookInput;
+      config.onHookEvent({
+        type: 'tool_start',
+        toolName: preInput.tool_name,
+        toolInput: preInput.tool_input,
+        timestamp: Date.now(),
+      });
+      // Passive: don't block, don't modify
+      return { continue: true } satisfies SyncHookJSONOutput;
+    };
+
+    hooks.PreToolUse = [{
+      hooks: [preToolHook],
+    }];
+
+    // PostToolUse — log after a tool runs successfully
+    const postToolHook: HookCallback = async (input: HookInput) => {
+      const postInput = input as PostToolUseHookInput;
+      config.onHookEvent({
+        type: 'tool_complete',
+        toolName: postInput.tool_name,
+        toolInput: postInput.tool_input,
+        toolResponse: postInput.tool_response,
+        timestamp: Date.now(),
+      });
+      return { continue: true } satisfies SyncHookJSONOutput;
+    };
+
+    hooks.PostToolUse = [{
+      hooks: [postToolHook],
+    }];
+
+    // PostToolUseFailure — log tool failures
+    const failureHook: HookCallback = async (input: HookInput) => {
+      const failInput = input as PostToolUseFailureHookInput;
+      config.onHookEvent({
+        type: 'tool_failure',
+        toolName: failInput.tool_name,
+        toolInput: failInput.tool_input,
+        error: failInput.error,
+        timestamp: Date.now(),
+      });
+      return { continue: true } satisfies SyncHookJSONOutput;
+    };
+
+    hooks.PostToolUseFailure = [{
+      hooks: [failureHook],
+    }];
+  }
+
+  if (config.logNotifications) {
+    // Notification — forward Claude's notifications to Discord
+    const notificationHook: HookCallback = async (input: HookInput) => {
+      const notifInput = input as NotificationHookInput;
+      config.onHookEvent({
+        type: 'notification',
+        message: notifInput.message,
+        title: notifInput.title,
+        timestamp: Date.now(),
+      });
+      return { continue: true } satisfies SyncHookJSONOutput;
+    };
+
+    hooks.Notification = [{
+      hooks: [notificationHook],
+    }];
+  }
+
+  if (config.logTaskCompletions) {
+    // TaskCompleted — notify when background tasks finish
+    const taskHook: HookCallback = async (input: HookInput) => {
+      const taskInput = input as TaskCompletedHookInput;
+      config.onHookEvent({
+        type: 'task_completed',
+        taskId: taskInput.task_id,
+        taskSubject: taskInput.task_subject,
+        message: taskInput.task_description,
+        timestamp: Date.now(),
+      });
+      return { continue: true } satisfies SyncHookJSONOutput;
+    };
+
+    hooks.TaskCompleted = [{
+      hooks: [taskHook],
+    }];
+  }
+
+  return hooks;
+}

claude/index.ts

@@ -46,8 +46,14 @@ export {
   getSupportedModels,
   getMcpServerStatus,
   fetchClaudeInfo,
+  toggleMcpServerActive,
+  reconnectMcpServerActive,
+  setMcpServersActive,
 } from "./query-manager.ts";
 export type { ClaudeInitInfo, RewindFilesResult } from "./query-manager.ts";
+// Hooks — passive SDK callbacks for tool/notification/task observability
+export { buildHooks } from "./hooks.ts";
+export type { HookConfig, HookEvent_Discord } from "./hooks.ts";
 // AskUserQuestion — interactive question flow (SDK v0.1.71+)
 export { buildQuestionMessages, parseAskUserButtonId, parseAskUserConfirmId } from "./user-question.ts";
 export type { AskUserCallback, AskUserQuestionInput, AskUserQuestionItem, AskUserOption } from "./user-question.ts";

claude/query-manager.ts

@@ -9,10 +9,10 @@
  * @module claude/query-manager
  */
 
-import { query as claudeQuery, type Query, type AccountInfo, type ModelInfo, type McpServerStatus, type SlashCommand, type RewindFilesResult, type PermissionMode } from "@anthropic-ai/claude-agent-sdk";
+import { query as claudeQuery, type Query, type AccountInfo, type ModelInfo, type McpServerStatus, type SlashCommand, type RewindFilesResult, type PermissionMode, type McpSetServersResult, type McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 
 // Re-export SDK types for consumers
-export type { Query, AccountInfo, ModelInfo as SDKModelInfoFull, McpServerStatus, SlashCommand as SDKSlashCommand, RewindFilesResult };
+export type { Query, AccountInfo, ModelInfo as SDKModelInfoFull, McpServerStatus, SlashCommand as SDKSlashCommand, RewindFilesResult, McpSetServersResult, McpServerConfig };
 
 /**
  * Full initialization result from the SDK.
@@ -219,6 +219,58 @@ export async function stopActiveTask(taskId: string): Promise<boolean> {
   }
 }
 
+// ================================
+// MCP Server Management
+// ================================
+
+/**
+ * Toggle an MCP server on/off mid-session via the SDK Query.
+ * 
+ * @param serverName - The name of the MCP server to toggle
+ * @param enabled - Whether the server should be enabled
+ */
+export async function toggleMcpServerActive(serverName: string, enabled: boolean): Promise<boolean> {
+  if (!activeQuery) return false;
+  try {
+    await activeQuery.toggleMcpServer(serverName, enabled);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reconnect an MCP server mid-session via the SDK Query.
+ * Useful when a server has failed or disconnected.
+ * 
+ * @param serverName - The name of the MCP server to reconnect
+ */
+export async function reconnectMcpServerActive(serverName: string): Promise<boolean> {
+  if (!activeQuery) return false;
+  try {
+    await activeQuery.reconnectMcpServer(serverName);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Dynamically set MCP servers mid-session via the SDK Query.
+ * Replaces the current set of dynamically-added servers.
+ * Servers from settings files are not affected.
+ * 
+ * @param servers - Record of server name to configuration
+ */
+export async function setMcpServersActive(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult | null> {
+  if (!activeQuery) return null;
+  try {
+    return await activeQuery.setMcpServers(servers);
+  } catch {
+    return null;
+  }
+}
+
 // ================================
 // Ephemeral Info Query
 // ================================

core/command-wrappers.ts

@@ -462,7 +462,8 @@ export function createSettingsCommandHandlers(
         const serverName = ctx.getString('server_name');
         const command = ctx.getString('command');
         const description = ctx.getString('description');
-        await unifiedSettingsHandlers.onMCP(ctx, action, serverName || undefined, command || undefined, description || undefined);
+        const value = ctx.getString('value');
+        await unifiedSettingsHandlers.onMCP(ctx, action, serverName || undefined, command || undefined, description || undefined, value || undefined);
       }
     }],
     ['agent', {

core/handler-registry.ts

@@ -30,6 +30,8 @@ import { infoCommands, createInfoCommandHandlers } from "../claude/index.ts";
 import { cleanSessionId, ClaudeSessionManager } from "../claude/index.ts";
 import type { ClaudeModelOptions } from "../claude/index.ts";
 import type { AskUserCallback } from "../claude/index.ts";
+import { buildHooks } from "../claude/hooks.ts";
+import type { HookEvent_Discord } from "../claude/hooks.ts";
 import { THINKING_MODES, OPERATION_MODES, EFFORT_LEVELS } from "../settings/index.ts";
 
 import type { ShellManager } from "../shell/index.ts";
@@ -433,7 +435,10 @@ export function createAllHandlers(
     if (s.enableFileCheckpointing) {
       opts.enableFileCheckpointing = true;
     }
-    if (s.enableSandbox) {
+    // Sandbox — granular config takes precedence over simple enableSandbox toggle
+    if (s.sandboxConfig) {
+      opts.sandbox = s.sandboxConfig;
+    } else if (s.enableSandbox) {
       opts.sandbox = { enabled: true, autoAllowBashIfSandboxed: true };
     }
     if (s.enableAgentTeams) {
@@ -442,6 +447,44 @@ export function createAllHandlers(
     if (s.outputJsonSchema) {
       opts.outputFormat = { type: 'json_schema', schema: s.outputJsonSchema };
     }
+    // Additional directories for multi-repo access
+    if (s.additionalDirectories && s.additionalDirectories.length > 0) {
+      opts.additionalDirectories = s.additionalDirectories;
+    }
+    
+    // Hooks — passive SDK callbacks for tool/notification/task observability
+    if (s.hooksLogToolUse || s.hooksLogNotifications || s.hooksLogTaskCompletions) {
+      const hookEventToMessage = (event: HookEvent_Discord): void => {
+        const prefix = '🪝';
+        let content = '';
+        switch (event.type) {
+          case 'tool_start':
+            content = `${prefix} Tool started: **${event.toolName}**`;
+            break;
+          case 'tool_complete':
+            content = `${prefix} Tool completed: **${event.toolName}**`;
+            break;
+          case 'tool_failure':
+            content = `${prefix} Tool failed: **${event.toolName}** — ${event.error ?? 'unknown error'}`;
+            break;
+          case 'notification':
+            content = `${prefix} Notification: ${event.title ? `**${event.title}** — ` : ''}${event.message ?? ''}`;
+            break;
+          case 'task_completed':
+            content = `${prefix} Task completed: ${event.taskSubject ?? event.taskId ?? 'unknown'}`;
+            break;
+        }
+        if (content) {
+          sendClaudeMessages([{ type: 'system', content }]);
+        }
+      };
+      opts.hooks = buildHooks({
+        logToolUse: s.hooksLogToolUse,
+        logNotifications: s.hooksLogNotifications,
+        logTaskCompletions: s.hooksLogTaskCompletions,
+        onHookEvent: hookEventToMessage,
+      });
+    }
 
     // AskUserQuestion — interactive question flow (late-bound from index.ts)
     if (deps.onAskUser) {