feat: add skipRelayPrompt flag to skip MCP injection on spawn

packages/sdk-py/src/agent_relay/client.py

@@ -557,6 +557,7 @@ async def spawn_pty(
         idle_threshold_secs: Optional[int] = None,
         restart_policy: Optional[dict[str, Any]] = None,
         continue_from: Optional[str] = None,
+        skip_relay_prompt: Optional[bool] = None,
     ) -> dict[str, Any]:
         await self.start_client()
         built_args = _build_pty_args_with_model(cli, args or [], model)
@@ -585,6 +586,8 @@ async def spawn_pty(
             request_payload["idle_threshold_secs"] = idle_threshold_secs
         if continue_from is not None:
             request_payload["continue_from"] = continue_from
+        if skip_relay_prompt is not None:
+            request_payload["skip_relay_prompt"] = skip_relay_prompt
         return await self._request_ok("spawn_agent", request_payload)
 
     async def spawn_headless(
@@ -595,6 +598,7 @@ async def spawn_headless(
         args: Optional[list[str]] = None,
         channels: Optional[list[str]] = None,
         task: Optional[str] = None,
+        skip_relay_prompt: Optional[bool] = None,
     ) -> dict[str, Any]:
         await self.start_client()
         agent = AgentSpec(
@@ -607,6 +611,8 @@ async def spawn_headless(
         request_payload: dict[str, Any] = {"agent": agent.to_dict()}
         if task is not None:
             request_payload["initial_task"] = task
+        if skip_relay_prompt is not None:
+            request_payload["skip_relay_prompt"] = skip_relay_prompt
         return await self._request_ok("spawn_agent", request_payload)
 
     async def spawn_provider(
@@ -626,6 +632,7 @@ async def spawn_provider(
         idle_threshold_secs: Optional[int] = None,
         restart_policy: Optional[dict[str, Any]] = None,
         continue_from: Optional[str] = None,
+        skip_relay_prompt: Optional[bool] = None,
     ) -> dict[str, Any]:
         resolved_transport: AgentTransport = transport or (
             "headless" if provider == "opencode" else "pty"
@@ -645,6 +652,7 @@ async def spawn_provider(
                 args=args,
                 channels=channels,
                 task=task,
+                skip_relay_prompt=skip_relay_prompt,
             )
 
         return await self.spawn_pty(
@@ -661,6 +669,7 @@ async def spawn_provider(
             idle_threshold_secs=idle_threshold_secs,
             restart_policy=restart_policy,
             continue_from=continue_from,
+            skip_relay_prompt=skip_relay_prompt,
         )
 
     async def spawn_claude(self, **kwargs: Any) -> dict[str, Any]:

packages/sdk-py/src/agent_relay/relay.py

@@ -51,6 +51,7 @@ class SpawnOptions:
     shadow_mode: Optional[str] = None
     idle_threshold_secs: Optional[int] = None
     restart_policy: Optional[dict[str, Any]] = None
+    skip_relay_prompt: Optional[bool] = None
     on_start: LifecycleHook = None
     on_success: LifecycleHook = None
     on_error: LifecycleHook = None
@@ -304,6 +305,7 @@ async def spawn(
         task: Optional[str] = None,
         model: Optional[str] = None,
         cwd: Optional[str] = None,
+        skip_relay_prompt: Optional[bool] = None,
         on_start: LifecycleHook = None,
         on_success: LifecycleHook = None,
         on_error: LifecycleHook = None,
@@ -332,6 +334,7 @@ async def spawn(
                 task=task,
                 model=model,
                 cwd=cwd,
+                skip_relay_prompt=skip_relay_prompt,
             )
         except Exception as error:
             await self._relay._invoke_lifecycle_hook(
@@ -512,6 +515,7 @@ async def spawn(
                 shadow_mode=opts.shadow_mode,
                 idle_threshold_secs=opts.idle_threshold_secs,
                 restart_policy=opts.restart_policy,
+                skip_relay_prompt=opts.skip_relay_prompt,
             )
         except Exception as error:
             await self._invoke_lifecycle_hook(

packages/sdk/src/client.ts

@@ -50,6 +50,9 @@ export interface SpawnPtyInput {
   restartPolicy?: RestartPolicy;
   /** Name of a previously released agent whose continuity context should be injected. */
   continueFrom?: string;
+  /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
+   *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
+  skipRelayPrompt?: boolean;
 }
 
 export interface SpawnHeadlessInput {
@@ -58,6 +61,9 @@ export interface SpawnHeadlessInput {
   args?: string[];
   channels?: string[];
   task?: string;
+  /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
+   *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
+  skipRelayPrompt?: boolean;
 }
 
 export type AgentTransport = 'pty' | 'headless';
@@ -77,6 +83,9 @@ export interface SpawnProviderInput {
   idleThresholdSecs?: number;
   restartPolicy?: RestartPolicy;
   continueFrom?: string;
+  /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
+   *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
+  skipRelayPrompt?: boolean;
 }
 
 export interface SendMessageInput {
@@ -278,6 +287,7 @@ export class AgentRelayClient {
       ...(input.task != null ? { initial_task: input.task } : {}),
       ...(input.idleThresholdSecs != null ? { idle_threshold_secs: input.idleThresholdSecs } : {}),
       ...(input.continueFrom != null ? { continue_from: input.continueFrom } : {}),
+      ...(input.skipRelayPrompt != null ? { skip_relay_prompt: input.skipRelayPrompt } : {}),
     });
     return result;
   }
@@ -294,6 +304,7 @@ export class AgentRelayClient {
     const result = await this.requestOk<{ name: string; runtime: AgentRuntime }>('spawn_agent', {
       agent,
       ...(input.task != null ? { initial_task: input.task } : {}),
+      ...(input.skipRelayPrompt != null ? { skip_relay_prompt: input.skipRelayPrompt } : {}),
     });
     return result;
   }
@@ -312,6 +323,7 @@ export class AgentRelayClient {
         args: input.args,
         channels: input.channels,
         task: input.task,
+        skipRelayPrompt: input.skipRelayPrompt,
       });
     }
 
@@ -329,6 +341,7 @@ export class AgentRelayClient {
       idleThresholdSecs: input.idleThresholdSecs,
       restartPolicy: input.restartPolicy,
       continueFrom: input.continueFrom,
+      skipRelayPrompt: input.skipRelayPrompt,
     });
   }
 

packages/sdk/src/protocol.ts

@@ -51,7 +51,7 @@ export type SdkToBroker =
     }
   | {
       type: 'spawn_agent';
-      payload: { agent: AgentSpec; initial_task?: string };
+      payload: { agent: AgentSpec; initial_task?: string; skip_relay_prompt?: boolean };
     }
   | {
       type: 'send_message';

packages/sdk/src/relay.ts

@@ -137,6 +137,9 @@ export interface SpawnOptions extends SpawnLifecycleHooks {
   shadowMode?: string;
   idleThresholdSecs?: number;
   restartPolicy?: RestartPolicy;
+  /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
+   *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
+  skipRelayPrompt?: boolean;
 }
 
 export interface SpawnAndWaitOptions extends SpawnOptions {
@@ -202,6 +205,9 @@ export interface SpawnerSpawnOptions extends SpawnLifecycleHooks {
   task?: string;
   model?: string;
   cwd?: string;
+  /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
+   *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
+  skipRelayPrompt?: boolean;
 }
 
 export type EventHook<T> = ((value: T) => void) | null;
@@ -369,6 +375,7 @@ export class AgentRelay {
         shadowMode: input.shadowMode,
         idleThresholdSecs: input.idleThresholdSecs,
         restartPolicy: input.restartPolicy,
+        skipRelayPrompt: input.skipRelayPrompt,
       });
     } catch (error) {
       await this.invokeLifecycleHook(
@@ -410,6 +417,7 @@ export class AgentRelay {
       shadowMode: options?.shadowMode,
       idleThresholdSecs: options?.idleThresholdSecs,
       restartPolicy: options?.restartPolicy,
+      skipRelayPrompt: options?.skipRelayPrompt,
       onStart: options?.onStart,
       onSuccess: options?.onSuccess,
       onError: options?.onError,
@@ -1225,6 +1233,7 @@ export class AgentRelay {
             task,
             model: options?.model,
             cwd: options?.cwd,
+            skipRelayPrompt: options?.skipRelayPrompt,
             onStart: options?.onStart,
             onSuccess: options?.onSuccess,
             onError: options?.onError,
@@ -1248,6 +1257,7 @@ export class AgentRelay {
             args,
             channels,
             task,
+            skipRelayPrompt: options?.skipRelayPrompt,
           });
         } catch (error) {
           await this.invokeLifecycleHook(