diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md
index b1c04d4e..8d62c0f4 100644
--- a/packages/coding-agent/docs/sdk.md
+++ b/packages/coding-agent/docs/sdk.md
@@ -468,12 +468,15 @@ Custom tools passed via `customTools` are combined with extension-registered too
 
 ### Extensions
 
-Extensions are discovered from `~/.pi/agent/extensions/` and `.pi/extensions/`. You can also pass inline extensions or additional paths:
+By default, extensions are discovered from multiple locations:
+- `~/.pi/agent/extensions/` (global)
+- `.pi/extensions/` (project-local)
+- Paths listed in `settings.json` `"extensions"` array
 
 ```typescript
 import { createAgentSession, type ExtensionFactory } from "@mariozechner/pi-coding-agent";
 
-// Inline extension
+// Inline extension factory
 const myExtension: ExtensionFactory = (pi) => {
   pi.on("tool_call", async (event, ctx) => {
     console.log(`Tool: ${event.toolName}`);
@@ -487,15 +490,20 @@ const myExtension: ExtensionFactory = (pi) => {
   });
 };
 
-// Pass inline extensions (merged with discovery)
+// Pass inline extensions (skips file discovery)
 const { session } = await createAgentSession({
   extensions: [myExtension],
 });
 
-// Or add paths to load (merged with discovery)
+// Add paths to load (merged with discovery)
 const { session } = await createAgentSession({
   additionalExtensionPaths: ["/path/to/my-extension.ts"],
 });
+
+// Disable extension discovery entirely
+const { session } = await createAgentSession({
+  extensions: [],
+});
 ```
 
 Extensions can register tools, subscribe to events, add commands, and more. See [extensions.md](extensions.md) for the full API.
diff --git a/packages/coding-agent/src/core/sdk.ts b/packages/coding-agent/src/core/sdk.ts
index b89f6e85..e84901b0 100644
--- a/packages/coding-agent/src/core/sdk.ts
+++ b/packages/coding-agent/src/core/sdk.ts
@@ -101,7 +101,7 @@ export interface CreateAgentSessionOptions {
 	tools?: Tool[];
 	/** Custom tools to register (in addition to built-in tools). */
 	customTools?: ToolDefinition[];
-	/** Inline extensions (merged with discovery). */
+	/** Inline extensions. When provided (even if empty), skips file discovery. */
 	extensions?: ExtensionFactory[];
 	/** Additional extension paths to load (merged with discovery). */
 	additionalExtensionPaths?: string[];