docs(adr): context-aware token for agent-initiated operations

[chaodu-agent]

Summary

Proposes a context-aware token pattern that gives agents the ability to actively interact with platform APIs when they judge it necessary — instead of relying on always-on transport-layer context injection.

Motivation

Discussion during review of PR #527 (reply/quote context) revealed that always prepending quoted message content at the OAB transport layer:

• Wastes ~500 tokens per reply even when the agent already has context from conversation history
• Only solves one edge case out of a broader set of agent-initiated operations
• Puts the decision in the wrong layer (transport vs intelligence)

A scoped token lets the agent pull context on demand and enables capabilities that were previously impossible:

• Fetch historical messages when context is genuinely missing
• Update thread titles (formalizes existing steering doc pattern)
• Cross-channel bot coordination and notification
• Smart quote resolution — only when the agent determines it's needed

Key Design Principle

OAB core doesn't change. The token lives in the agent's environment, configured by the user. Allowed operations are defined in steering docs. OAB remains a passive transport layer.

Relationship to PR #527

This ADR supersedes PR #527's approach. PR #527 will be closed in favor of this design direction.

Related: #339

Discord discussion: https://discord.com/channels/1491295327620169908/1491365150664560881/1500514858775482418

[chaodu-agent]

LGTM ✅ — Clean ADR that formalizes an existing pattern (steering doc + curl for thread titles) into a documented architecture. Ready to merge with minor suggestions.

四問框架 Review

1. What problem does it solve?

PR #527 always prepended quoted message content at the OAB transport layer (~500 tokens per reply), even when the agent already had context. This ADR proposes an on-demand pattern: give the agent a scoped platform token so it can pull context only when needed.

2. How does it solve it?

New ADR file (docs/adr/context-aware-token.md) proposing:

• Agent gets DISCORD_CONTEXT_TOKEN env var
• Steering docs define allowed/denied operations (trust boundary)
• OAB core stays unchanged — purely agent-side capability
• Covers 4 use cases: smart quote resolution, cross-channel coordination, thread title management, historical context retrieval

3. What was considered?

• PR #527 always-on approach (superseded) — wastes tokens, wrong layer
• This ADR on-demand approach — agent decides when to fetch

4. Is this the best approach?

For an ADR, yes. The document is well-structured, follows existing ADR conventions in the repo, and the phased rollout plan is pragmatic.

Traffic Light

🟢 INFO — Follows existing ADR format (matches custom-gateway.md, multi-platform-adapters.md). Good prior art section linking to PR #527 and issue #339.

🟢 INFO — The "OAB core doesn't change" principle is well-articulated and consistent with OAB philosophy.

🟡 NIT — Section 4 Security: "Trust boundary enforced by steering docs" is honest but worth noting that this is fundamentally a soft boundary. LLMs can hallucinate tool calls or ignore steering doc constraints. Consider adding a sentence acknowledging this is a known limitation of the pattern, not a bug in the design.

🟡 NIT — The ADR references ./custom-gateway.md and ./multi-platform-adapters.md in the References section — these exist on main ✅. But it also references PR #527 as "superseded" — since #527 is already closed, consider noting the close date for future readers.

🟡 NIT — Open Questions table: "How to handle platforms without API tokens?" — LINE and Telegram both have API tokens (LINE Channel Access Token, Telegram Bot Token). The question might be better framed as "platforms with different auth models" rather than "without API tokens."

Disclosure: This PR was authored by chaodu-agent (me). I am reviewing my own PR for completeness and to surface any issues before maintainer review.

[chaodu-agent]

LGTM ✅ — Well-structured ADR with solid prior art research and pragmatic security evolution path. Three cosmetic NITs, no blocking issues.

📋 Four-Question Framework Analysis

1. What problem does this solve?

OAB agents are currently passive receivers — they get a prompt and return a response. Real-world usage requires agents to actively interact with platforms (update thread titles, fetch historical messages, cross-channel coordination). PR #527 solved one edge case (reply/quote context) with always-on prepending at ~500 tokens per reply. This ADR proposes a context-aware token pattern that lets agents pull context on demand, solving #339 and enabling capabilities that were previously impossible.

2. How does it solve it?

• Agent gets a DISCORD_CONTEXT_TOKEN environment variable for platform API calls
• Agent decides at runtime when to use it (on-demand vs always-on)
• OAB core remains unchanged — token is agent-side capability
• For feat: include Discord reply/quote context in agent prompt #339: OAB passthroughs reply metadata (~20 tokens), agent fetches full content only when needed
• Security model evolves across 4 maturity levels (behavioral → audit logging → proxy enforcement → scoped tokens)

3. What alternatives were considered?

• PR feat(discord): include reply/quote context in agent prompt (#339) #527 approach (always-on prepending) — superseded due to token waste and single-case limitation
• OpenClaw mediated architecture — Gateway controls all agent-platform interactions; secure but requires fundamental OAB architecture change
• Hermes Agent tool-based architecture — LLM tools with function-calling schemas; structured but requires each runtime to integrate
• ADR explicitly explains why OAB diverges: passive transport philosophy + 4 different agent runtimes

4. Is this the best approach?

Yes, for OAB's constraints. The ADR honestly acknowledges the security gap (Level 1 is behavioral-only) and provides a concrete evolution path. The tradeoff between pragmatism (works with any agent that has shell access) and security (no technical enforcement initially) is well-reasoned and appropriate for trusted single-operator deployments.

🚦 Traffic Light

🟢 INFO — Strengths:

• Prior art research is thorough — OpenClaw security advisories (with CVE references) and Hermes Agent analysis include concrete code references
• Security model's 4-level evolution path is pragmatic, acknowledging Level 1 limitations while planning toward defense-in-depth
• §6 cleanly separates Scenario A (Discord reply with referenced_message) from Scenario B (non-reply historical lookup) — clear resolution path for feat: include Discord reply/quote context in agent prompt #339
• Format matches existing ADR conventions (consistent with custom-gateway.md)
• 3 commits show responsive iteration to monk team feedback

🟢 INFO — Baseline check:

• main has no context-aware-token.md — this is entirely net-new content
• PR feat(discord): include reply/quote context in agent prompt (#339) #527 is CLOSED, issue feat: include Discord reply/quote context in agent prompt #339 is OPEN — ADR correctly reflects these states
• Existing ADR directory has 4 files; format is consistent

🟡 NIT 1: §10 Rollout Plan Phase 1 could echo the §3 security note about same-bot-token being a convenience shortcut for trusted single-operator deployments only — saves readers from scrolling back to §3.

🟡 NIT 2: §6 Acceptance Criteria uses - [ ] checkbox format, but this is an ADR, not an issue. Consider plain list items or noting where these criteria will be tracked (e.g., "tracked in #339").

🟡 NIT 3: §9 Open Questions row 1 uses strikethrough for "Decided" — some renderers handle this poorly. Consider adding a "Status" column or moving decided items to §3.

📊 Baseline Check

Check	Result
Net-new content?	✅ Yes — entirely new file, no overlap with existing ADRs
PR #527 status	CLOSED — correctly superseded by this ADR
Issue #339 status	OPEN — ADR provides concrete resolution path
ADR format consistency	✅ Matches existing conventions
Stale content risk	✅ None — PR is same-day, 3 commits show active iteration

[chaodu-agent]

LGTM ✅ — Reviewed and recommended for approval. Well-structured ADR with solid prior art research and pragmatic security evolution path. Three cosmetic NITs noted (non-blocking).