@@ -30,6 +30,14 @@ export interface CommandExecuteOutput {
3030
3131const SENTINEL_PREFIX = "__CONTEXT_MANAGEMENT_" ;
3232
33+ /** Throw sentinel error to prevent OpenCode from forwarding the command to the LLM.
34+ * This works in TUI and Desktop. In web mode, the error surfaces as a failure in the
35+ * browser UI — that's an OpenCode limitation (no "handled" return path from
36+ * command.execute.before). Filed as a known issue. */
37+ function throwSentinel ( command : string ) : never {
38+ throw new Error ( `${ SENTINEL_PREFIX } ${ command . toUpperCase ( ) } _HANDLED__` ) ;
39+ }
40+
3341/**
3442 * Execute /ctx-aug: run sidekick to augment the user's prompt with relevant memories,
3543 * then send the augmented prompt as a real user message.
@@ -58,7 +66,7 @@ async function executeAugmentation(
5866 "## /ctx-aug\n\nSidekick is not configured. Add sidekick settings to `magic-context.jsonc` to use /ctx-aug." ,
5967 { } ,
6068 ) ;
61- throw new Error ( ` ${ SENTINEL_PREFIX } CTX-AUG_HANDLED__` ) ;
69+ throwSentinel ( " CTX-AUG" ) ;
6270 }
6371
6472 const prompt = userPrompt . trim ( ) ;
@@ -68,7 +76,7 @@ async function executeAugmentation(
6876 "## /ctx-aug\n\nUsage: `/ctx-aug <your prompt>`\n\nProvide a prompt to augment with project memory context." ,
6977 { } ,
7078 ) ;
71- throw new Error ( ` ${ SENTINEL_PREFIX } CTX-AUG_HANDLED__` ) ;
79+ throwSentinel ( " CTX-AUG" ) ;
7280 }
7381
7482 // Step 1: Show "preparing" notification (hidden from LLM)
@@ -103,7 +111,7 @@ async function executeAugmentation(
103111 // Step 4: Send as a real user prompt (will be processed by the model)
104112 await sendUserPrompt ( deps . sidekick . client , sessionId , augmentedPrompt ) ;
105113
106- throw new Error ( ` ${ SENTINEL_PREFIX } CTX-AUG_HANDLED__` ) ;
114+ throwSentinel ( " CTX-AUG" ) ;
107115}
108116
109117function summarizeDreamResult ( result : DreamRunResult ) : string {
@@ -156,14 +164,14 @@ async function executeDreaming(
156164 "## /ctx-dream\n\nDreaming is not configured for this project." ,
157165 { } ,
158166 ) ;
159- throw new Error ( ` ${ SENTINEL_PREFIX } CTX-DREAM_HANDLED__` ) ;
167+ throwSentinel ( " CTX-DREAM" ) ;
160168 }
161169
162170 // dream_queue table is created in initializeDatabase() — no ensureDreamQueueTable needed
163171 const entry = enqueueDream ( deps . db , deps . dreamer . projectPath , "manual" ) ;
164172 if ( ! entry ) {
165173 await deps . sendNotification ( sessionId , "Dream already queued for this project" , { } ) ;
166- throw new Error ( ` ${ SENTINEL_PREFIX } CTX-DREAM_HANDLED__` ) ;
174+ throwSentinel ( " CTX-DREAM" ) ;
167175 }
168176
169177 await deps . sendNotification ( sessionId , "Starting dream run..." , { } ) ;
@@ -187,7 +195,7 @@ async function executeDreaming(
187195 : "Dream queued, but another worker is already processing the queue." ,
188196 { } ,
189197 ) ;
190- throw new Error ( ` ${ SENTINEL_PREFIX } CTX-DREAM_HANDLED__` ) ;
198+ throwSentinel ( " CTX-DREAM" ) ;
191199}
192200
193201export function createMagicContextCommandHandler ( deps : {
@@ -328,12 +336,7 @@ export function createMagicContextCommandHandler(deps: {
328336 await deps . sendNotification ( sessionId , result , { } ) ;
329337 sessionLog ( sessionId , `command ${ input . command } handled via command.execute.before` ) ;
330338
331- // OpenCode limitation: the command.execute.before hook has no "handled" return path.
332- // Throwing a sentinel exception is the only way to prevent OpenCode from continuing
333- // with normal command execution (which would send the command to the model).
334- // A typed result object or custom error class with an isSentinel flag would be cleaner,
335- // but requires an upstream API change. See audit finding #20.
336- throw new Error ( `${ SENTINEL_PREFIX } ${ input . command . toUpperCase ( ) } _HANDLED__` ) ;
339+ throwSentinel ( input . command ) ;
337340 } ,
338341 } ;
339342}
0 commit comments