diff --git a/packages/coding-agent/src/core/custom-tools/types.ts b/packages/coding-agent/src/core/custom-tools/types.ts
index 837462ad..59d800f9 100644
--- a/packages/coding-agent/src/core/custom-tools/types.ts
+++ b/packages/coding-agent/src/core/custom-tools/types.ts
@@ -36,27 +36,6 @@ export interface CustomToolAPI {
 	hasUI: boolean;
 }
 
-/**
- * Clawd here, summarizing what's available to custom tools:
- *
- * CustomToolAPI (passed to factory, stable across session changes):
- *   - cwd: string - current working directory
- *   - exec(cmd, args, options?): Promise<ExecResult> - run shell commands
- *   - ui: CustomToolUIContext - select, confirm, input, notify, custom, setStatus, theme
- *   - hasUI: boolean - false in print/RPC mode
- *
- * CustomToolContext (passed to execute and onSession):
- *   - sessionManager: ReadonlySessionManager - read session entries, branch info
- *   - modelRegistry: ModelRegistry - get API keys, list models
- *   - model: Model | undefined - current model
- *   - isIdle(): boolean - check if agent is streaming
- *   - hasQueuedMessages(): boolean - check if user queued input (skip interactive prompts!)
- *   - abort(): void - fire-and-forget abort (sets signal, doesn't wait)
- *
- * Note: Custom tools run inside the agent loop (like tool_call events in hooks),
- * so they only get the safe read-only methods. No waitForIdle/newSession/branch/navigateTree.
- */
-
 /**
  * Context passed to tool execute and onSession callbacks.
  * Provides access to session state and model information.
diff --git a/packages/coding-agent/src/core/hooks/types.ts b/packages/coding-agent/src/core/hooks/types.ts
index e7af5e87..a15f2e7d 100644
--- a/packages/coding-agent/src/core/hooks/types.ts
+++ b/packages/coding-agent/src/core/hooks/types.ts
@@ -130,31 +130,6 @@ export interface HookUIContext {
 	readonly theme: Theme;
 }
 
-/**
- * Clawd here, summarizing what's available to hooks:
- *
- * HookContext (available in ALL event handlers):
- *   - ui: HookUIContext - select, confirm, input, notify, custom, setStatus, theme
- *   - hasUI: boolean - false in print/RPC mode
- *   - cwd: string - current working directory
- *   - sessionManager: ReadonlySessionManager - read session entries, branch info
- *   - modelRegistry: ModelRegistry - get API keys, list models
- *   - model: Model | undefined - current model
- *   - isIdle(): boolean - check if agent is streaming
- *   - hasQueuedMessages(): boolean - check if user queued input (skip interactive prompts)
- *   - abort(): void - fire-and-forget abort (sets signal, doesn't wait)
- *
- * HookCommandContext (only in registerCommand handlers, extends HookContext):
- *   - waitForIdle(): Promise<void> - wait for agent to finish
- *   - newSession(options?): Promise - create new session with optional setup
- *   - branch(entryId): Promise - branch from specific entry
- *   - navigateTree(targetId, options?): Promise - navigate session tree
- *
- * Why the split? Session control methods (waitForIdle, newSession, etc.) would DEADLOCK
- * if called from event handlers like tool_call or context, because those run inside
- * the agent loop. Slash commands run from user input, outside the loop, so they're safe.
- */
-
 /**
  * Context passed to hook event handlers.
  * For command handlers, see HookCommandContext which extends this with session control methods.