diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index b3179a1c..11620c64 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -21,7 +21,7 @@
 - Extension UI dialogs (`ctx.ui.select()`, `ctx.ui.confirm()`, `ctx.ui.input()`) now support a `timeout` option with live countdown display ([#522](https://github.com/badlogic/pi-mono/pull/522) by [@nicobailon](https://github.com/nicobailon))
 - Extensions can now provide custom editor components via `ctx.ui.setEditorComponent()`. See `examples/extensions/modal-editor.ts` and `docs/tui.md` Pattern 7.
 - Extension factories can now be async, enabling dynamic imports and lazy-loaded dependencies ([#513](https://github.com/badlogic/pi-mono/pull/513) by [@austinm911](https://github.com/austinm911))
-- `ctx.shutdown()` is now available in extension contexts for requesting a graceful shutdown. In interactive mode, shutdown is deferred until the agent becomes idle (after processing all queued steering and follow-up messages). In RPC mode, shutdown is deferred until after completing the current command response. In print mode, shutdown is a no-op as the process exits automatically when prompts complete.
+- `ctx.shutdown()` is now available in extension contexts for requesting a graceful shutdown. In interactive mode, shutdown is deferred until the agent becomes idle (after processing all queued steering and follow-up messages). In RPC mode, shutdown is deferred until after completing the current command response. In print mode, shutdown is a no-op as the process exits automatically when prompts complete. ([#542](https://github.com/badlogic/pi-mono/pull/542) by [@kaofelix](https://github.com/kaofelix))
 
 ### Fixed
 
diff --git a/packages/coding-agent/examples/extensions/shutdown-command.ts b/packages/coding-agent/examples/extensions/shutdown-command.ts
index 7cfdf56e..fa0063f5 100644
--- a/packages/coding-agent/examples/extensions/shutdown-command.ts
+++ b/packages/coding-agent/examples/extensions/shutdown-command.ts
@@ -13,7 +13,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerCommand("quit", {
 		description: "Exit pi cleanly",
 		handler: async (_args, ctx) => {
-			await ctx.shutdown();
+			ctx.shutdown();
 		},
 	});
 
@@ -25,12 +25,12 @@ export default function (pi: ExtensionAPI) {
 		parameters: Type.Object({}),
 		async execute(_toolCallId, _params, _onUpdate, ctx, _signal) {
 			// Do any final work here...
-			// Then shutdown
-			await ctx.shutdown();
+			// Request graceful shutdown (deferred until agent is idle)
+			ctx.shutdown();
 
-			// This return won't be reached, but required by type
+			// This return is sent to the LLM before shutdown occurs
 			return {
-				content: [{ type: "text", text: "Shutting down..." }],
+				content: [{ type: "text", text: "Shutdown requested. Exiting after this response." }],
 				details: {},
 			};
 		},
@@ -50,12 +50,12 @@ export default function (pi: ExtensionAPI) {
 			// Example deployment logic
 			// const result = await pi.exec("npm", ["run", "deploy", params.environment], { signal });
 
-			// On success, shutdown
+			// On success, request graceful shutdown
 			onUpdate?.({ content: [{ type: "text", text: "Deployment complete, exiting..." }], details: {} });
-			await ctx.shutdown();
+			ctx.shutdown();
 
 			return {
-				content: [{ type: "text", text: "Done!" }],
+				content: [{ type: "text", text: "Done! Shutdown requested." }],
 				details: { environment: params.environment },
 			};
 		},