github / github/copilot-sdk

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

未关闭
#1,279 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
enhancement
主要语言
Java
星标
10.5k
派生
1.5k
平均合并
1 天 14 小时
30 天内合并 PR
129

描述

### 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

```ts
const session = await client.createSession({
customAgents: [
{
name: "fix-architect",
prompt: "",
// ...
},
],
});

await session.sendAndWait({ prompt: "Dispatch the fix-architect..." });
// Orchestrator LLM decides at runtime to call:
// task({ name: "fix-architect", prompt: "" })
// 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

```ts
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

- #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
```

贡献指南

打开贡献指南

调研方向

首先跟踪 SDK/CLI 中 CustomAgentConfig 的注册过程和 task API 的 dispatch 路径。比较每次调用时加锁与注册时加锁这两种方案,然后验证被锁定的 agent 使用其已注册的 prompt、普通覆盖默认保持不变,并且现有测试套件覆盖了该行为。

由索引模型根据 Issue 内容生成。

评估

技术栈
node.js, typescript
领域
api, backend
Issue 类型
功能
难度
4/5
预计耗时
3-5 天
活跃度
冷清
描述清晰度
基本清楚
新手友好度
48/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。