系统提示与工具 schema 组装

94    this.scope = createScope(loopCtx, this)95    this.ctx = this.scope.ctx.extend({ agent: this })96    this.runtimeContext = new RuntimeContextProjection(this.ctx, session)

137export function createScope(ctx: Context, key: ScopeKey, options?: CreateScopeOptions): Scope {138  if (options?.parent !== undefined) bindScopeParent(key, options.parent)139  const fiber = ctx.plugin(scope)140  const scoped: Context = fiber.ctx.extend({ [kScope]: key })141  let disposing: Promise<void> | undefined142  return {143    ctx: scoped,144    rawDispose: fiber.dispose,145    dispose: () => (disposing ??= quiesceFiber(fiber)),146  }147}

154export function scopeOf(ctx: Context): ScopeKey | undefined {155  return (ctx as Context & { [kScope]?: ScopeKey })[kScope]156}

381  section(section: PromptSection): () => void {382    if (!Number.isFinite(section.order)) {383      throw new TypeError(`prompt section "${section.name}" order must be a finite number`)384    }385    return this.layers.effect(386      this.ctx,387      layer => layer.sections.insert(section.name, section),388      { label: 'systemPrompt.section()' },389    )390  }

226  effect(227    ctx: Context,228    action: (layer: L) => () => void,229    options: { label: string; notify?: boolean },230  ): () => void {231    const scope = scopeOf(ctx)232    const notify = options.notify ?? true233    const dispose = ctx.effect(function* (this: ScopedLayers<L>) {234      let layer: L235      let created = false236      if (scope === undefined) {237        layer = this.global238      } else {239        const existing = this.scoped.get(scope)240        if (existing === undefined) {241          layer = this.createLayer(scope)242          this.scoped.set(scope, layer)243          created = true244        } else {245          layer = existing246        }247      }248249      let undo: () => void250      try {251        undo = action(layer)252      } catch (error) {253        if (scope !== undefined && created && layer.isEmpty()) this.scoped.delete(scope)254        throw error255      }256257      yield () => {258        undo()259        if (scope !== undefined && layer.isEmpty()) this.scoped.delete(scope)260        if (notify) this.onChange()261      }262      if (notify) this.onChange()263    }.bind(this), options.label)264    // oxlint-disable-next-line typescript/no-misused-promises -- exact synchronous disposer preserves Cordis effect identity265    return dispose266  }

293   * This is how a child agent inherits its parent's capabilities. It is a bind,294   * not a mount: the parent's generation is already composed, so the child gets295   * that exact instance — the same plugin objects, the same tool registrations,296   * the same prompt sections. Re-resolving the parent's preset by id instead297   * would re-read the roster, and a composition file edited since the parent298   * started would hand the child a DIFFERENT generation than the one its299   * parent's history was produced under (and a preset deleted since would fail300   * the child outright while its parent keeps running).

225  private async preStep(target: InboxTarget, position: { turn: number; step: number }): Promise<PreparedStep> {226    /* v8 ignore next -- private callers establish the running phase before proposing a step */227    if (this.phase.kind !== 'running') throw new Error(`agent "${this.id}": pre-step outside running phase`)228    const signal = this.phase.abort.signal229    const claimed = this.inbox.claim(target, position.turn)230    const assembly = await this.loopCtx.systemPrompt.assemble(assembleContextFor(this, signal))231    signal.throwIfAborted()232    const sections = renderContextSections(assembly)233    const context = this.runtimeContext.project(joinContextSections(sections), sections)234    const decision = await this.dispatch.waterfall(235      'agent/pre-step', { messages: claimed, ...position, signal },236      (): Promise<PreStepDecision> => Promise.resolve<PreStepDecision>({237        kind: 'enter',238        messages: context === undefined ? claimed : [...claimed, context],239      }),240    )241    signal.throwIfAborted()242    return decision.kind === 'reject' ? decision : { ...decision, assembly }243  }

167/**168 * Build the prompt assembly context with agent and scope set together, so169 * agent-scoped prompt and tool contributions cannot be silently omitted.170 * @param agent - the agent the assembly is for.171 * @param signal - the current turn's explicit control signal, when assembly belongs to a turn.172 * @returns the context to pass to `assemble()`.173 */174export function assembleContextFor(agent: Agent, signal?: AbortSignal): AssembleContext {175  return { agent, scope: agent, ...signal === undefined ? {} : { signal } }176}

467  async assemble(context: AssembleContext = {}): Promise<PromptAssembly> {468    const scope = context.scope469    const scopeLayers = this.layers.chainLayers(scope)470    const runtimeContextSuppressed = !this.layers.global.runtimeContextSuppressors.isEmpty()471      || scopeLayers.some(layer => !layer.runtimeContextSuppressors.isEmpty())472    // Scoped variables shadow globals.473    const variables: Record<string, string | undefined> = {}474    for (const [name, provider] of this.layers.global.variables.entries()) {475      variables[name] = provider(context)476    }477    // Scope-chain variables, farthest first, so the nearest scope wins a name.478    for (const layer of scopeLayers) {479      for (const [name, provider] of layer.variables.entries()) {480        variables[name] = provider(context)481      }482    }483    // Scoped sections shadow globals before the stable order sort.484    const sectionByName = this.layers.merge(scope, layer => layer.sections)485    const contextByName = this.layers.merge(scope, layer => layer.contexts)486    // Validate order against pre-restriction names while collecting visible schemas.487    const providers = [⋯      ...this.layers.global.toolProviders.values(),⋯      ...scopeLayers.flatMap(layer => [...layer.toolProviders.values()]),490    ]491    const collected: ToolSchema[] = []492    const knownNames = new Set<string>()493    for (const provider of providers) {494      const result = provider(context)495      const schemas = result.schemas.map(({ name, description, parameters }): ToolSchema => ({496        name,497        description,498        parameters: structuredClone(parameters),499      }))500      const acceptedKnownNames = result.knownNames ?? schemas.map(tool => tool.name)501      collected.push(...schemas)502      for (const name of acceptedKnownNames) knownNames.add(name)503    }

208  merge<V>(209    scope: ScopeKey | undefined,210    pick: (layer: L) => NamedEntries<V>,211  ): Map<string, V> {212    const merged = new Map(pick(this.global).entries())213    for (const layer of this.chainLayers(scope)) {214      for (const [name, value] of pick(layer).entries()) merged.set(name, value)215    }216    return merged217  }

504    const sectionDefinitions = [...sectionByName.values()].sort((a, b) => a.order - b.order)505    const completeSections = sectionDefinitions.filter(section => section.complete === true)506    if (completeSections.length > 1) {507      throw new Error(`multiple complete prompt sections are active: ${completeSections.map(section => JSON.stringify(section.name)).join(', ')}`)508    }509    let completeSection: AssembledSection | undefined510    const sections = sectionDefinitions511      .map((section) => {512        const assembled = {513          name: section.name,514          text: typeof section.text === 'function' ? section.text(context) : section.text,515        }516        if (section.complete === true) completeSection = { ...assembled }517        return assembled518      })519    const assembly: PromptAssembly = {520      sections,521      contexts: runtimeContextSuppressed522        ? []523        : [...contextByName.values()]524          .sort((a, b) => a.order - b.order)525          .map(entry => ({526            name: entry.name,527            text: typeof entry.text === 'function' ? entry.text(context) : entry.text,528          })),529      tools: orderTools(collected, this.toolOrder, knownNames),530      variables,531    }532    const transformed = await this.ctx.waterfall(533      scopeTarget(this, scope), 'system-prompt/assemble', assembly, context,534      () => Promise.resolve(assembly),535    )536    if (completeSection === undefined && !runtimeContextSuppressed) return transformed537    return {⋯      ...transformed,539      sections: completeSection === undefined ? transformed.sections : [completeSection],540      contexts: runtimeContextSuppressed ? [] : transformed.contexts,541    }

212export function renderPrompt(assembly: PromptAssembly): string {213  return assembly.sections214    .map(section => interpolate(section, assembly.variables, 'section'))215    .filter(text => text.length > 0)216    .join('\n\n')217}

236export function joinContextSections(sections: readonly ContextSnapshotSection[]): string {237  const body = sections.map(section => section.text).join('\n\n')238  if (body.length === 0) return ''239  return `Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\n${body}`240}

258function interpolate(259  input: AssembledSection | AssembledContext,260  variables: Record<string, string | undefined>,261  kind: 'section' | 'context',262): string {263  const text = input.text264  let result = ''265  let last = 0266  for (let open = text.indexOf('{{'); open >= 0; open = text.indexOf('{{', last)) {267    const group = GROUP_AT.exec(text.slice(open))268    if (group === null) {269      // A later closing brace makes this malformed; otherwise it is literal prose.270      if (text.indexOf('}}', open + 2) >= 0) {271        throw new Error(`malformed prompt variable reference at "${text.slice(open, open + 16)}…" in ${kind} "${input.name}" (references are complete simple {{name}} groups)`)272      }273      result += text.slice(last, open + 2)274      last = open + 2275      continue276    }277    // `{{}}` yields an empty name and follows the malformed-reference path.278    const name = group[0].slice(2, -2)279    if (!VARIABLE_NAME.test(name)) {280      throw new Error(`malformed prompt variable reference "{{${name}}}" in ${kind} "${input.name}" (variable names match ${String(VARIABLE_NAME)})`)281    }282    // Do not resolve unregistered names through Object.prototype.283    if (!Object.hasOwn(variables, name)) {284      const known = Object.keys(variables)285      throw new Error(`unknown prompt variable "{{${name}}}" in ${kind} "${input.name}"; registered variables: ${known.length > 0 ? known.join(', ') : '(none)'}`)286    }287    const value = variables[name]288    if (value === undefined) {289      throw new Error(`prompt variable "{{${name}}}" has no value for this assembly (${kind} "${input.name}")`)290    }291    result += text.slice(last, open) + value292    last = open + group[0].length293  }294  return result + text.slice(last)295}

680export interface ToolRestriction {681  /** Global tool names that stay visible; everything else is removed. */682  readonly allow?: readonly string[]683  /** Global tool names removed from visibility. */684  readonly deny?: readonly string[]685}686687/** One restriction compiled at registration for repeated live-global lookup. */688interface CompiledToolRestriction {689  readonly allow?: ReadonlySet<string>690  readonly deny?: ReadonlySet<string>691}692693/** One scope's complete registry view, derived in a single layer traversal. */694interface ToolView {695  /** Visible definitions after restrictions, scoped shadowing, and transport insertion. */696  readonly visible: ReadonlyMap<string, ToolDefinition>697  /** Pre-restriction capability names used by prompt-order validation. */698  readonly knownNames: ReadonlySet<string>699  /** Current global names that a scoped restriction may name. */700  readonly restrictableNames: ReadonlySet<string>701}

1071  restrict(filter: ToolRestriction): () => void {1072    const scope = scopeOf(this.ctx)1073    if (scope === undefined) {1074      throw new Error('tools.restrict() requires a scoped context (agent.ctx): a context-global restriction would mask every agent — deny the tool for the intended agent instead')1075    }1076    const allow = filter.allow1077    const deny = filter.deny1078    if (allow === undefined && deny === undefined) {1079      throw new Error('tools.restrict({}) is a no-op: pass `allow` and/or `deny` (an empty filter is almost always a materialized-empty-config bug)')1080    }1081    const compiled: CompiledToolRestriction = {⋯      ...allow !== undefined ? { allow: new Set(allow) } : {},⋯      ...deny !== undefined ? { deny: new Set(deny) } : {},1084    }1085    if ([...allow ?? [], ...deny ?? []].includes(RUN_CODE_NAME)) {1086      throw new Error(`tools.restrict() cannot name reserved Code Mode presentation transport "${RUN_CODE_NAME}"; restrict end-capability tools instead`)1087    }1088    const known = this.view(scope).restrictableNames1089    const unknown = [...allow ?? [], ...deny ?? []].filter(name => !known.has(name))1090    if (unknown.length > 0) {1091      throw new Error(`tools.restrict() names unknown global tool${unknown.length > 1 ? 's' : ''} ${unknown.map(n => `"${n}"`).join(', ')}; known global tools: ${[...known].sort().join(', ') || '(none)'}`)1092    }1093    return this.layers.effect(1094      this.ctx,1095      layer => layer.restrictions.append(compiled),1096      { label: 'tools.restrict()' },1097    )1098  }

1152  private view(scope?: ScopeKey): ToolView {1153    // Scope-chain layers, farthest ancestor first, the exact scope last.1154    const layers = this.layers.chainLayers(scope)1155    // Chain-blind on purpose: this is the ONE layer whose registrations the1156    // scope owns rather than inherits, and it is absent until the scope1157    // contributes something.1158    const own = this.layers.peek(scope)1159    // Inherited surface, nearest ancestor last: a nearer scope's same-name1160    // entry shadows a farther one, and the global layer is the farthest.1161    const inherited = new Map<string, ToolDefinition>(this.layers.global.tools.entries())1162    for (const layer of layers) {1163      if (layer === own) continue1164      for (const [name, definition] of layer.tools.entries()) inherited.set(name, definition)1165    }1166    const visible = new Map<string, ToolDefinition>()1167    const knownNames = new Set<string>()1168    const restrictableNames = new Set<string>()1169    for (const [name, definition] of inherited) {1170      knownNames.add(name)1171      restrictableNames.add(name)1172      // Restrictions intersect across the whole chain: any scope on it may1173      // mask an inherited name for everything nested inside it.1174      if (layers.every(layer => layer.admits(name))) visible.set(name, definition)1175    }1176    // The scope's own registrations last, shadowing an inherited name and1177    // outside the filter above.1178    if (own !== undefined) {1179      for (const [name, definition] of own.tools.entries()) {1180        knownNames.add(name)1181        visible.set(name, definition)1182      }1183    }1184    // Presentation infrastructure is resolved last and outside capability1185    // filtering. Registration rejects this reserved name, so the insertion is1186    // an invariant assertion as well as protection against future layer1187    // changes. Per scope: a native agent must not find `run_code` in its1188    // dispatch table because some other agent in the process presents it.1189    if (this.modeFor(scope) !== 'native') {1190      visible.set(RUN_CODE_NAME, this.requireCodeTransport())1191    }1192    return { visible, knownNames, restrictableNames }1193  }

737  /** Whether every compiled restriction in this layer admits a global tool name. */738  admits(name: string): boolean {739    for (const filter of this.restrictions.values()) {740      if ((filter.allow !== undefined && !filter.allow.has(name))741        || (filter.deny !== undefined && filter.deny.has(name))) return false742    }743    return true744  }

1256  private schemaOf(definition: ToolDefinition, detachParameters: boolean): ToolSchema {1257    const { name, description, parameters } = definition1258    const detached = detachParameters ? snapshotJsonValue(parameters) : parameters1259    if (detached === undefined) {1260      throw new Error(`tool "${name}" parameters must be lossless JSON before schema projection`)1261    }1262    return {1263      name,1264      description,1265      parameters: detached,1266    }1267  }

18  interface Events {19    /**20     * Expert waterfall over the assembled sections, contexts, tools, and variables.21     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners22     * receive only that scope's assemblies. The returned value is authoritative.23     * A supplied signal controls only this explicit assembly request and must not24     * be retained to control later turns. A registered complete section is25     * restored after this waterfall, so listeners cannot add to or replace26     * that scope's system prompt.27     * @param assembly - the mutable assembly built from registered providers.28     * @param context - the caller's per-assembly context.29     * @mode waterfall30     */31    'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>32    /**33     * Emitted when any prompt provider changes. This registry notification is34     * unfiltered because a global change affects every scope.35     * @mode emit36     */37    'system-prompt/change'(): void38  }

198    /**199     * A tool was registered or unregistered, or a scoped restriction changed200     * (the available tool set changed — possibly for one scope only). An201     * UNFILTERED registry-subject notification, deliberately not scope-filtered202     * dispatch: a global change concerns every agent's next assembly, so a203     * scoped listener subscribing here sees every change, not just its own204     * scope's.205     * @mode emit206     */207    'tools/change'(): void

170export function scopeTarget<T extends object>(base: T, key: ScopeKey | undefined): Scoped<T> {171  const baseFilter = (base as { [CordisContext.filter]?: (ctx: Context) => boolean })[CordisContext.filter]172  const carrier = {173    [CordisContext.filter](ctx: Context): boolean {174      if (baseFilter !== undefined && !baseFilter.call(base, ctx)) return false175      const tag = scopeOf(ctx)176      if (tag === undefined) return true177      for (let cursor = key; cursor !== undefined; cursor = scopeParents.get(cursor)) {178        if (cursor === tag) return true179      }180      return false181    },182  }183  carrierKeys.set(carrier, key)184  return carrier as unknown as Scoped<T>185}

122/**123 * The deployment persona's section name and order. Exported because a124 * composition can replace this slot — an agent preset shadows the125 * deployment's persona with its own — and both sides naming the same section126 * is what makes the replacement work rather than duplicate.127 */128export const PERSONA_SECTION = 'deployment:persona'

72## Visibility is not authority7374These controls compose trusted same-process behavior; they do not authorize it. `toolFilter` changes the child view resolved by the tool registry, but it does not create a parent-to-child grant lattice, require a child to be a subset of its parent, sandbox plugins, or prevent code with another Cordis context from calling services directly.7576In particular, a child-local tool is added after the global filter and may be absent from the parent's view. A deny-only child also sees later global tools not named by the deny-list. Those are deliberate live-composition semantics, not non-escalation guarantees.7778A security design would need a separate authority representation, propagation rule, and execution-time enforcement point. Creation-time grant snapshots, parent-subset grants, explicit future-grant APIs, and generic capability/output/termination tags are outside this feature.

1---2name: code-architect3description: Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences4tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput5model: sonnet6color: green7---

1---2name: conversation-analyzer3description: Use this agent when analyzing conversation transcripts to find behaviors worth preventing with hooks. Examples: <example>Context: User is running /hookify command without arguments\nuser: "/hookify"\nassistant: "I'll analyze the conversation to find behaviors you want to prevent"\n<commentary>The /hookify command without arguments triggers conversation analysis to find unwanted behaviors.</commentary></example><example>Context: User wants to create hooks from recent frustrations\nuser: "Can you look back at this conversation and help me create hooks for the mistakes you made?"\nassistant: "I'll use the conversation-analyzer agent to identify the issues and suggest hooks."\n<commentary>User explicitly asks to analyze conversation for mistakes that should be prevented.</commentary></example>4model: inherit5color: yellow6tools: ["Read", "Grep"]7---

146**Format:** Array of tool names⋯# ... 省略原文 yaml 围栏内的示例块·**Default:** If omitted, agent has access to all tools⋯# ... 原文 153 行为空行，跳过154**Best practice:** Limit tools to minimum needed (principle of least privilege)

4895- Added `disallowedTools` field to custom agent definitions for explicit tool blocking

4733- Added `agent` setting to configure main thread with a specific agent's system prompt, tool restrictions, and model