feat: make local dev credential discovery and sandbox projection first-class #1423

Problem Statement

Setting up a sandbox for realistic developer/agent pairing currently has too much credential plumbing before the useful workflow begins.

The agent-driven policy demo shows the desired loop well, but the setup path has to manually discover and inject credentials for tools like GitHub, Codex, and Claude. In practice, this makes demos and dev workflows spend a lot of time on auth setup instead of the actual OpenShell value proposition: scoped sandbox access, policy denies, agent proposals, human approval, and hot reload.

This is especially noticeable for manual policy workflow demos. A developer may already be signed in locally with gh auth login, codex login, or Claude tooling, but openshell sandbox create --auto-providers does not currently turn that local state into a ready-to-use sandbox environment.

Proposed Design

Make local developer credential discovery and sandbox projection first-class provider behavior.

The product flow should be explicit and reviewable, not silent magic. For example:

Found local credentials:
  github: gh auth token
  codex: ~/.codex/auth.json
  claude: ANTHROPIC_API_KEY or local Claude auth

Attach these to sandbox policy-demo-123? [Y/n]

Suggested behavior:

1. Provider plugins discover local credentials from common sources:

   • GitHub: GITHUB_TOKEN, GH_TOKEN, or gh auth token
   • Codex: OPENAI_API_KEY and/or ~/.codex/auth.json
   • Claude: ANTHROPIC_API_KEY, CLAUDE_API_KEY, and possibly Claude local auth if stable and safe

2. The CLI presents discovered credentials before importing or attaching them.

3. Provider plugins know how to project credentials into the sandbox in the form the target tool expects:

   • GitHub token as GITHUB_TOKEN
   • Codex login state as a usable ~/.codex/auth.json or equivalent runtime projection
   • Claude credentials in the expected env/file form

4. --auto-providers should either:

   • grow into this behavior, with clear consent prompts when interactive, or
   • remain narrow but be paired with a more explicit dev workflow flag, such as --dev-access github,codex,claude.

The key UX principle: OpenShell should make the credential bridge visible and intentional, but developers should not have to hand-copy local auth state into provider records or sandbox bootstrap scripts.

Claude support should be part of the initial scope, not a follow-up. Manual pairing needs to work naturally for both Codex and Claude-style agent sessions.

Alternatives Considered

Keep credential setup in demos/scripts.

This works for the current automated policy demo, but it makes each demo reimplement provider discovery and projection logic. It also hides a real product gap: users expect local tool auth to be reusable when creating a developer sandbox.

Require users to create providers manually.

This is explicit, but too much friction for common dev pairing workflows. It also makes --auto-providers feel surprising because it does not currently discover local tool auth unless specific environment variables are already exported.

Silently import all local credentials.

This would be smoother but too opaque. The better UX is explicit discovery with a short review/confirmation step.

Implementation Pointers

The current agent-driven policy demo already prototypes the missing behavior:

• examples/agent-driven-policy-management/demo.sh resolves GitHub owner and token from gh/env:
  • resolve_github_owner
  • resolve_github_token
• examples/agent-driven-policy-management/demo.sh resolves Codex auth from ~/.codex/auth.json:
  • resolve_codex_auth
• examples/agent-driven-policy-management/demo.sh creates generic providers from the discovered values:
  • create_providers
• examples/agent-driven-policy-management/sandbox-agent.sh projects those env vars back into the runtime shape Codex expects:
  • exports GITHUB_TOKEN
  • materializes ~/.codex/auth.json

This demo behavior is a useful spike, but the durable implementation should move into provider discovery/projection rather than staying as example-specific shell glue.

Current code behavior observed during investigation:

• Provider auto-creation is driven by explicit --provider values or command inference.
• Provider discovery currently reads known environment variables.
• GitHub provider discovery checks GITHUB_TOKEN / GH_TOKEN, but not gh auth token.
• Codex provider discovery checks OPENAI_API_KEY, but not ~/.codex/auth.json.
• Claude provider discovery checks ANTHROPIC_API_KEY / CLAUDE_API_KEY; local Claude auth discovery/projection should be evaluated as part of this issue.

Relevant files:

• crates/openshell-cli/src/run.rs
• crates/openshell-providers/src/discovery.rs
• crates/openshell-providers/src/providers/github.rs
• crates/openshell-providers/src/providers/codex.rs
• crates/openshell-providers/src/providers/claude.rs
• examples/agent-driven-policy-management/demo.sh
• examples/agent-driven-policy-management/sandbox-agent.sh

Definition of Done

• GitHub provider can discover credentials from gh auth token when env vars are absent.
• Codex provider can discover local codex login state or clearly document why it cannot.
• Claude provider can discover and project the minimum local auth needed for a Claude agent session, or clearly document any stable/safety limitation.
• Sandbox runtime projection can materialize provider credentials in tool-native forms where needed.
• CLI shows a concise “Found local credentials” review before importing/attaching discovered credentials.
• Manual agent-driven policy workflow setup no longer requires demo-specific credential extraction for GitHub/Codex/Claude.
• Docs explain the difference between provider discovery, provider attachment, and sandbox runtime projection.