Add an opt-in `useRegisteredPrompt` flag to lock `task` dispatch against orchestrator-LLM prompt overrides

[kevinlims]

Summary

The task built-in tool accepts an optional prompt field that overrides the agent's registered prompt at dispatch time. There is no opt-in way to mark a registered prompt as "locked" against override. For production pipelines that codify agent prompts for testability, reproducibility, or downstream-parser contracts, the runtime LLM's override capability is a real failure mode.

Scenario

const session = await client.createSession({
  customAgents: [
    {
      name: "fix-architect",
      prompt: "<carefully tuned, schema-aware prompt that produces specific output shape>",
      // ...
    },
  ],
});

await session.sendAndWait({ prompt: "Dispatch the fix-architect..." });
// Orchestrator LLM decides at runtime to call:
//   task({ name: "fix-architect", prompt: "<improvised prompt with different output shape>" })
// Sub-agent runs with the orchestrator's prompt; downstream parsers expecting the registered schema get the improvised one.
// Silent contract breach.

What's missing

CustomAgentConfig does not include useRegisteredPrompt, lockPrompt, preventOverride, or any similar flag. The task API also has no such option.

Suggested API

task({
  name: "fix-architect",
  prompt: customPrompt,           // would be ignored if useRegisteredPrompt: true
  useRegisteredPrompt: true,      // NEW: lock to the agent's registered prompt
})

When useRegisteredPrompt: true, the SDK/CLI ignores any prompt override and uses the registered agent's prompt verbatim. Default false for backward compatibility.

Alternative: CustomAgentConfig.lockedPrompt: true declared at registration time so the lock applies to every dispatch of that agent regardless of the task call shape. This puts the decision with the agent author rather than the dispatcher, which matches the "agent is the trusted unit" mental model better.

Consumer impact

Production pipelines where the agent prompt is the source of truth for the output schema have no way to enforce that contract upstream. They must validate the output post-hoc and either re-run or fix downstream. This is a real failure mode in multi-phase pipelines where the output of one phase is consumed by deterministic parsers in the next.

In one observed run, the orchestrator dispatched a sub-agent with a custom prompt that used rootCauses[] array shape instead of the registered issues[] / notActionableIssues[] shape. Downstream parsers saw zero issues; the next phase ran on nothing. Cost of the failure: one full session re-run.

Why this is a feature request, not a bug

The SDK is doing what it advertises — the task API allows orchestrator-driven prompt customization. But for production-grade reliability scenarios, an opt-in lock would prevent silent contract breakage at no cost to flexibility (the default stays open and the feature is opt-in per call or per agent).

Related

• sendAndWait returns prematurely when orchestrator dispatches sub-agents via task and ends its turn #1275 — sendAndWait early-resolve. Different shape but same general theme: production consumers need more guarantees from the SDK about sub-agent contracts.

Environment

- SDK: @github/copilot-sdk@0.3.0
- CLI: @github/copilot@1.0.45
- Node: 22 LTS
- OS: Windows 11
- Model: claude-sonnet-4-6