Spec ambiguity: global context merge into tool agent `context` field is undefined when agent declares its own context #7

New issue

Open

opened 2026-05-27 05:24:46 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-05-27 05:24:46 +00:00

Member

Problem

§4.9 states:

When an agent is created, the Actor's global context (context.global) MUST be merged into the agent's config.context unless the agent already declares a config.context of its own.

This creates a confusing opt-out behavior: if a tool agent declares even a single key in config.context, the entire global context is not merged in. The agent then has no access to any global context variables unless it explicitly redeclares them all.

This behavior is likely unintentional for the common case where a tool agent wants to declare one or two local defaults while still reading from the global context.

Additionally, the word "declares" is ambiguous. Does it mean:

"Has a non-null config.context mapping" (any non-null value triggers the opt-out)?
"Has a non-empty config.context mapping" (empty {} still gets the global merge)?
"Explicitly sets a key that conflicts with a global key" (only conflicting keys are not merged)?

Impact on Library Implementation

Agent creation code cannot implement context inheritance correctly without an unambiguous merge rule. Different readings produce different observable behaviors for any actor where a tool agent declares local context.

Decision Needed

Clarify what "declares a config.context of its own" means precisely.
Consider changing the rule to a deep-merge where global context is always merged in, but agent-local keys take precedence over global keys — this matches the intuitive expectation.
If the opt-out behavior is intentional, provide an explicit example demonstrating it and explain the rationale.

References

§4.9 — Agent Context Inheritance
§4.5 — Tool Agents (context field definition)
§10.2 — Context Lifecycle

## Problem §4.9 states: > When an agent is created, the Actor's global context (`context.global`) MUST be merged into the agent's `config.context` unless the agent already declares a `config.context` of its own. This creates a confusing opt-out behavior: if a tool agent declares even a single key in `config.context`, the entire global context is **not** merged in. The agent then has no access to any global context variables unless it explicitly redeclares them all. This behavior is likely unintentional for the common case where a tool agent wants to declare one or two local defaults while still reading from the global context. Additionally, the word "declares" is ambiguous. Does it mean: - "Has a non-`null` `config.context` mapping" (any non-null value triggers the opt-out)? - "Has a non-empty `config.context` mapping" (empty `{}` still gets the global merge)? - "Explicitly sets a key that conflicts with a global key" (only conflicting keys are not merged)? ## Impact on Library Implementation Agent creation code cannot implement context inheritance correctly without an unambiguous merge rule. Different readings produce different observable behaviors for any actor where a tool agent declares local context. ## Decision Needed 1. Clarify what "declares a `config.context` of its own" means precisely. 2. Consider changing the rule to a deep-merge where global context is always merged in, but agent-local keys take precedence over global keys — this matches the intuitive expectation. 3. If the opt-out behavior is intentional, provide an explicit example demonstrating it and explain the rationale. ## References - §4.9 — Agent Context Inheritance - §4.5 — Tool Agents (`context` field definition) - §10.2 — Context Lifecycle

Rows
Columns

Spec ambiguity: global context merge into tool agent context field is undefined when agent declares its own context #7

Problem

Impact on Library Implementation

Decision Needed

References

Spec ambiguity: global context merge into tool agent `context` field is undefined when agent declares its own context #7