Support auth.md-based capability discovery for agent and MCP clients

[Yashwant00CR7]

Problem

gogcli is explicitly built for coding agents, CI pipelines, and MCP clients. It already has strong foundations for agent-safe execution: named OAuth clients, keyring backends, command allowlists/denylists (--enable-commands-exact), baked safety-profile binaries, and a typed MCP server (gog mcp) that deliberately avoids a generic command bridge.

However, there is currently no structured way for an agent or MCP client to discover:

• which scopes/capabilities are available before invoking tools
• what authentication methods gogcli supports in a given deployment
• how to negotiate a scoped delegated session rather than inheriting full account privileges
• whether the running instance has write access or is in a read-only safety profile

Right now, agents must either be pre-configured out-of-band or probe blindly. This creates friction in autonomous harnesses and multi-agent orchestration where the agent runtime doesn't know what the tool is allowed to do.

---

Proposed Feature

Add optional support for auth.md-based capability discovery, specifically tailored to gogcli's existing agent-safety model.

Building on what already exists:

• gog schema --json exposes the command/flag schema
• --enable-commands-exact defines allowed command surfaces
• safety profiles bake in runtime guards
• gog mcp exposes a typed, read-only-by-default MCP stdio server

The proposal is to extend this with a machine-readable auth and capability document that agent clients can discover at startup.

What gogcli could expose

• available authentication methods (OAuth, ADC, service account, direct access token)
• active account and its authorized scopes (e.g. gmail.modify, drive, calendar)
• current command surface: which commands are allowed/denied for this process
• whether write operations are permitted or blocked (safety profile status)
• token expiry hints so agents can proactively re-authenticate before a long task
• MCP tool availability filtered by current auth scope

Possible interfaces

# Machine-readable auth + capability snapshot
gog agent auth-info --json

# Or exposed as an MCP tool for agent clients
# mcp tool: gog_auth_info -> returns scopes, allowed commands, write status

For HTTP/SSE deployments of the MCP server, this could also be exposed as a well-known endpoint:

GET /.well-known/auth.md
GET /.well-known/capabilities.json

---

Why This Matters for gogcli Specifically

gogcli is increasingly used inside agent runtimes (Claude Code, OpenClaw, Codex, Gemini CLI) via the MCP server. In these environments:

• the agent doesn't know upfront if the gogcli instance has drive write access or is read-only
• the agent can't tell if --gmail-no-send is active without attempting a send
• safety profiles are baked into the binary — there's no way for an agent to introspect them without trying a blocked command and getting an error

Structured capability discovery would let the agent adapt its behavior before calling tools, rather than learning constraints through failures.

---

Suggested Implementation Ideas

Possible architecture (lightweight, non-breaking):

1. New gog agent auth-info subcommand under the existing gog agent group
2. Returns JSON with: active account, authorized scopes, allowed command surface, write status, token expiry
3. MCP tool gog_capabilities registered alongside existing typed tools in gog mcp
4. Optional: /.well-known/capabilities.json for HTTP transport mode

Potential flow for an agent runtime:

1. Agent starts gogcli MCP server
2. Calls gog_capabilities tool immediately
3. Learns: read-only, gmail+drive scopes, no send, token valid for 45 min
4. Adapts tool calls accordingly — no blind 403s, no wasted retries

---

Security Considerations

The implementation should avoid:

• exposing raw refresh tokens or client secrets in the capability document
• returning keyring passwords or ADC key material
• leaking account email in shared/multi-tenant MCP deployments

Prefer:

• scopes and capabilities only — no credential material
• redacted account identity (configurable)
• the same access controls that already gate gog agent commands
• read-only by default, consistent with gog mcp philosophy

---

This would make gogcli a first-class citizen in agentic workflows — not just a tool that agents call, but one that agents can reason about before calling.

---

Reference

Official auth.md specification and format: https://github.com/workos/auth.md

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 3, 2026, 6:27 AM ET / 10:27 UTC.

Summary
This should stay open as a product/security design request: current main has auth inventory, command schema, MCP tool listing, command guards, and safety profiles, but no auth.md-style capability discovery surface for agents or MCP clients.

Reproducibility: not applicable. this is a proposed discovery feature, not a failing current behavior report. Source and docs inspection show the requested combined auth/capability surface is absent from current main.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
This is not a safe autonomous fix candidate until maintainers choose the permanent schema, disclosure policy, and first supported CLI/MCP surface.

Security
Needs attention: The issue itself is security-sensitive because it proposes exposing runtime auth and capability state to agents or MCP clients.

Review details

Best possible solution:

Keep this open for maintainer design review, then implement a minimal JSON capability surface only after the schema, redaction rules, and supported CLI/MCP surfaces are agreed.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a proposed discovery feature, not a failing current behavior report. Source and docs inspection show the requested combined auth/capability surface is absent from current main.

Is this the best way to solve the issue?

No for an immediate fix lane; adding the exact proposed surface before schema and redaction decisions would be premature. A narrower first implementation should follow maintainer agreement on what can be safely exposed through CLI and MCP.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The schema would disclose auth, scope, account, command-safety, and token-expiry state, so maintainers need to decide redaction and access-control policy before implementation.
• The proposed well-known HTTP/SSE endpoints would be a new transport/disclosure surface beyond the current stdio MCP server and need explicit product/security approval.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 096323d506b9.

Label changes

Label justifications:

• P3: This is a speculative but relevant feature/design request rather than a current broken workflow.
• impact:security: The requested surface would disclose auth, scope, identity, and capability state and must avoid credential or account leakage.
• impact:auth-provider: The request centers on auth methods, OAuth scopes, delegated sessions, and MCP/agent capability discovery.

Evidence reviewed

Security concerns:

• [medium] Define capability disclosure and redaction policy
  A capability document could reveal account identity, granted scopes, command/write permissions, and token-expiry hints, so maintainers should decide what is safe to expose and whether identity is redacted before implementation.
  Confidence: 0.88

What I checked:

• Issue request: The issue asks for a new gog agent auth-info --json, MCP capability tool, or well-known capability/auth document covering auth methods, scopes, allowed commands, write status, token expiry, and redaction policy.
• Agent command surface: AgentCmd currently contains only the exit-code helper, so there is no existing gog agent auth-info or equivalent agent discovery command. (internal/cmd/agent.go:3, 096323d506b9)
• MCP list-tools shape: McpCmd has --list-tools, but mcpPrintTools emits only tool name, service, risk, and description; it does not include auth methods, granted scopes, token expiry, account redaction, or command-safety state. (internal/cmd/mcp.go:19, 096323d506b9)
• Auth status scope: auth status --json reports config/keyring/account credential state and service-account preference, but not a full runtime capability snapshot for agents or MCP clients. (internal/cmd/auth_accounts.go:27, 096323d506b9)
• Auth list scope: auth list --json can expose stored account services/scopes and optional token validity checks, but it is account inventory rather than process capability negotiation and includes full email identity by design. (internal/cmd/auth_list_helpers.go:30, 096323d506b9)
• Schema scope: gog schema --json emits command/flag schema and respects baked safety profile visibility, but it is not a runtime auth/capability document. (internal/cmd/schema.go:15, 096323d506b9)

Likely related people:

• auroracapital: The changelog credits the typed, allowlisted gog mcp server with read-only defaults and explicit write opt-in to this contributor, and the issue timeline mentions them for this topic. (role: MCP feature contributor signal; confidence: medium; commits: 2c84d8981dd5; files: CHANGELOG.md, internal/cmd/mcp.go, docs/mcp.md)
• Peter Steinberger: Current shallow blame attributes the MCP, agent, auth status, auth list, and changelog snapshot to the v0.21.0 release commit authored by Peter Steinberger. (role: current release/blame carrier; confidence: medium; commits: 2c84d8981dd5, 096323d506b9; files: internal/cmd/mcp.go, internal/cmd/agent.go, internal/cmd/auth_accounts.go)
• jason-allen-oneal: The requested capability snapshot would need to reflect strict command allowlists, and the changelog credits --enable-commands-exact to this contributor. (role: adjacent command-guard contributor; confidence: medium; commits: 2c84d8981dd5; files: CHANGELOG.md, internal/cmd/enabled_commands.go)
• drewburchfield: The requested write/read-only safety reporting overlaps baked safety profiles, and the changelog credits safer agent binaries and safety-profile hardening to this contributor. (role: adjacent safety-profile contributor; confidence: medium; commits: 2c84d8981dd5; files: CHANGELOG.md, internal/cmd/safety_profile.go, safety-profiles/agent-safe.yaml)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.