Summary

• Problem: Plugin tools could not safely request a per-user Microsoft Teams delegated token from the current Teams conversation.
• Why it matters: Teams/Graph OBO-style integrations need user-delegated context without leaking channel tokens into prompts, transcripts, or broad plugin surfaces.
• What changed: Added generic plugin delegated-auth policy, runtime propagation, Teams Bot Framework SSO handling, Codex tool forwarding, docs, and a production-shaped example plugin/downstream API.
• What did NOT change (scope boundary): Delegated auth is implemented for Microsoft Teams only; non-Teams channels are not broadened by this PR.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes N/A
• Related N/A
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: End-to-end Teams delegated-auth consent for an OpenClaw plugin tool, including missing-consent handling, Bot Framework sign-in fallback, six-digit code completion, and retrying the tool with delegated auth available.
• Real environment tested: Local macOS OpenClaw dev checkout, pnpm openclaw --dev gateway, Microsoft Teams dev app, Bot Framework OAuth connection, devtunnel on port 3978, local downstream OBO API, and the example msteams-graph-profile plugin.
• Exact steps or command run after this patch:
  1. Started the local downstream OBO API.
  2. Started the OpenClaw dev gateway with the Teams channel and msteams-graph-profile plugin configured.
  3. Sent hi, run teams whoami to the OpenClaw Teams dev app.
  4. Opened the Bot Framework sign-in link rendered in Teams.
  5. Completed Microsoft sign-in/consent and sent the six-digit fallback code back to the Teams chat.
  6. Sent hi, run teams whoami again.
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Teams chat screenshot plus copied live output:
  

  msteams_whoami ran again. Result:
  Microsoft Teams delegated auth unavailable: missing_consent
  
  Microsoft Teams delegated auth is connected. Retry the tool now.
  
  Success again:
  Stefan Stüben <redacted email>
  

• Observed result after fix: The initial tool run requested consent, the six-digit fallback completed the Teams delegated-auth flow, and the retried msteams_whoami call returned the signed-in Teams user profile/email through the downstream OBO API.
• What was not tested: Non-Teams channels, production-hosted downstream API deployment, broad tenant rollout beyond the dev tenant, and every Teams client rendering variant. The observed Teams client rendered the Bot Framework OAuth flow as a sign-in link fallback; the fallback and six-digit completion path were tested.
• Before evidence (optional but encouraged): Before consent, msteams_whoami returned Microsoft Teams delegated auth unavailable: missing_consent.

Root Cause (if applicable)

• Root cause: N/A. This PR adds a new capability.
• Missing detection / guardrail: N/A.
• Contributing context (if known): Existing plugin tool execution had no channel-delegated auth context or Teams SSO consent bridge.

Regression Test Plan (if applicable)

N/A for a new feature, but the smallest reliable guardrails added/used are:

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/plugins/tools.optional.test.ts, extensions/msteams/src/delegated-auth.test.ts, extensions/msteams/src/monitor-handler.sso.test.ts, extensions/msteams/src/monitor-handler/message-handler.delegated-auth.test.ts, extensions/codex/src/app-server/run-attempt.test.ts, src/agents/pi-embedded-runner/run.delegated-auth-context.test.ts, src/auto-reply/reply/followup-runner.test.ts.
• Scenario the test should lock in: Delegated auth is available only when policy allows it, propagates through agent/tool execution paths, survives cached plugin descriptors, handles Teams missing-consent/sign-in flows, and does not swallow ordinary six-digit messages without a pending auth challenge.
• Why this is the smallest reliable guardrail: These tests cover the generic plugin policy seam, the Teams SSO edge cases, and the runtime paths that carry hidden delegated-auth context without requiring live Microsoft infrastructure in CI.
• Existing test that already covers this (if any): N/A before this PR.
• If no new test is added, why not: New tests were added/updated.

User-visible / Behavior Changes

• Plugin authors can opt into delegated auth with plugins.entries.<pluginId>.auth.delegatedAccess.
• Microsoft Teams plugin tools can request a Teams delegated token for the current user/conversation when explicitly allowlisted by config.
• Teams users may see a Bot Framework sign-in link/fallback when a delegated-auth tool needs consent.
• Added docs for Teams delegated-auth setup and plugin author usage.
• Added examples/plugins/msteams-graph-profile and examples/msteams-obo-downstream-api.

Diagram (if applicable)

Before:
Teams message -> agent -> plugin tool -> no delegated Teams user token -> downstream OBO unavailable

After:
Teams message -> Teams SSO provider -> gated plugin ctx.auth -> plugin tool -> downstream API OBO -> Microsoft Graph profile

Security Impact (required)

• New permissions/capabilities? (Yes)
• Secrets/tokens handling changed? (Yes)
• New/changed network calls? (Yes)
• Command/tool execution surface changed? (Yes)
• Data access scope changed? (Yes)
• If any Yes, explain risk + mitigation: Delegated Teams tokens are sensitive. This PR keeps access opt-in and policy-gated by plugin/tool allowlists plus provider, audience, scope, user, tenant, chat, and chat-type checks. Tokens are passed as hidden runtime context to plugin execution, not prompt text or transcript content. The example keeps Microsoft Graph access server-side in a downstream API so client secrets and Graph permissions stay behind an API boundary.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node/pnpm local dev checkout
• Model/provider: OpenAI dev agent profile
• Integration/channel (if any): Microsoft Teams dev app via devtunnel, Bot Framework OAuth connection
• Relevant config (redacted): Teams channel enabled, delegated-auth plugin entry enabled, local downstream OBO API configured with redacted client secret and app ids.

Steps

1. Start devtunnel for the Teams bot endpoint on port 3978.
2. Start the local downstream OBO API.
3. Start pnpm openclaw --dev gateway.
4. Send hi, run teams whoami in Teams.
5. Complete the Bot Framework sign-in link and send the six-digit fallback code.
6. Retry hi, run teams whoami.

Expected

• First run requests consent.
• Six-digit fallback completes delegated auth.
• Retried tool returns the signed-in Teams user profile/email.

Actual

• First run returned missing_consent.
• Teams received the Bot Framework sign-in link.
• Six-digit fallback completed with Microsoft Teams delegated auth is connected. Retry the tool now.
• Retried msteams_whoami returned the signed-in Teams user profile/email.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Teams missing-consent flow, Bot Framework sign-in link fallback, six-digit code completion, retrying msteams_whoami, and downstream OBO profile lookup.
• Edge cases checked: Six-digit messages are handled only while a pending sign-in challenge exists; delegated auth is rejected when missing/unconfigured/unavailable; Teams user-id fallback paths are covered by tests.
• What you did not verify: Non-Teams channels, production tenant rollout, hosted downstream API deployment, and every Teams client native OAuth-card rendering variant.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (Yes)
• Migration needed? (No)
• If yes, exact upgrade steps: Existing configs continue to work. To use delegated auth, explicitly configure plugins.entries.<pluginId>.auth.delegatedAccess and the Teams Bot Framework OAuth connection described in the docs.

Risks and Mitigations

• Risk: A plugin could receive a user token unexpectedly.
  • Mitigation: Delegated auth is opt-in, allowlist-gated, and claim-validated before tool execution.
• Risk: Teams clients may render OAuth consent as a sign-in link instead of a native card.
  • Mitigation: The Teams implementation supports sign-in-link fallback and six-digit completion.
• Risk: Downstream API consent is separate from Teams bot consent.
  • Mitigation: Docs and examples use separate app registrations and document admin pre-consent for the downstream API.

Rationale And Design Decisions

Keep core generic

Delegated auth is modeled as a generic plugin capability instead of a Teams-specific special case in core. Core owns policy parsing, tool gating, token claim validation, and runtime propagation; the Teams plugin owns Bot Framework SSO behavior and token acquisition.

Make delegated auth explicit and policy-gated

Plugin delegated auth is opt-in through plugins.entries.<pluginId>.auth.delegatedAccess.enabled, with optional provider, audience, scope, user, tenant, chat, and chat-type restrictions.

Keep optional tools least-privilege

Optional plugin factories receive ctx.auth only when the plugin itself, group:plugins, *, or a concrete optional tool name is allowlisted. The resolver also handles implicit optional registrations where names: [] and declaredNames carry the actual tool contract.

Resolve auth per execution for cached descriptors

Cached plugin tool descriptors keep descriptor creation fast, but delegated auth is resolved when the cached tool executes, so a previous message’s auth context is never cached into a future run.

Propagate auth through run plumbing, not prompts

The Teams delegated auth context is passed through hidden runtime/run parameters and plugin tool context, including queued replies, follow-up runs, embedded runner attempts, OpenClaw tools, and Codex app-server tool calls.

Teams owns Bot Framework SSO details

The Teams plugin owns Bot Framework token exchange, verify-state, sign-in resource creation, sign-in-link fallback, six-digit code fallback, and Teams user-id fallback handling.

Keep Graph access server-side in the example

The example plugin calls a local downstream API. The downstream API performs Microsoft Graph OBO using its own app registration and delegated permission grant, which keeps Graph client secrets and broader Graph behavior behind a production-shaped API boundary.

Verification

• pnpm test src/plugins/tools.optional.test.ts
• pnpm tsgo:core --pretty false
• pnpm tsgo:test:src --pretty false
• pnpm test src/plugins/tools.optional.test.ts extensions/msteams/src/delegated-auth.test.ts extensions/msteams/src/monitor-handler.sso.test.ts extensions/msteams/src/monitor-handler/message-handler.delegated-auth.test.ts extensions/codex/src/app-server/run-attempt.test.ts src/agents/pi-embedded-runner/run.delegated-auth-context.test.ts src/auto-reply/reply/followup-runner.test.ts
• pnpm tsgo:extensions --pretty false
• pnpm tsgo:extensions:test --pretty false
• pnpm test src/plugins/tool-descriptor-cache.test.ts src/plugins/tools.optional.test.ts extensions/msteams/src/delegated-auth.test.ts
• pnpm exec oxfmt --check --threads=1 src/plugins/tool-descriptor-cache.ts src/plugins/tool-descriptor-cache.test.ts src/plugins/tools.ts src/plugins/tools.optional.test.ts extensions/msteams/src/delegated-auth.test.ts
• git diff --check
• pnpm dup:check:coverage
• Final review pass: no actionable correctness/security/regression findings in the reviewed diff
• Manual Teams dev setup: consent fallback completed and msteams_whoami returned the signed-in user profile