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