setup · git:20261011.9360690 · 2026-10-11 · sha256 ea0763eee4c07abc

setup git:20261011.9360690A

Immutable. This exact content never changes and is served at /api/v1/blob/ea0763eee4c07abc.

# Set Up the Bridge

## Bootstrap and plan

- Treat a plain invocation as `action=all target=peer scope=auto live=prompt`.
- Loaded Claude plugin, Claude trust, Claude authentication, and current session are external bootstrap prerequisites. Never replace or restart current invocation surface.
- Reject a model-supplied workspace; use Claude's launch workspace — the working directory of the current Claude Code session, never a path named in conversation or task text.
- Run `python --version` first; stop if unavailable or older than Python 3.10; report the interpreter found, or its absence, and the 3.10 minimum.
- Parse only documented `key=value` grammar plus one-release compatibility forms `--live` and `--direction codex|claude`; reject ambiguous or unknown arguments.

For one resolved target, invoke:

```bash
python "${CLAUDE_PLUGIN_ROOT}/bin/bridge_setup.py" --current-host claude --workspace "<launch-workspace>" --action "<action>" --target "<target>" --scope "<scope>" --live "<live>"
```

Deterministic planner performs credential-free inspection, returns setup result JSON defined by `schemas/setup-result.schema.json`.

## Check and approved changes

For `check`, report the result and stop. For `all`, `configure`, or `repair`:

1. If the planned `operations` list is empty, report nothing to configure and stop under `configure` or `repair`; under `all`, continue to the stages below without requesting approval.
2. Carry every planned `operations` entry and the approval digest in the step-3 question (every option's `preview`) before mutation — never only as reply text before it, which can arrive as an empty progress update. Preview cap: ≤2000 chars and ≤12 lines per preview, every line counted (Claude Code withholds a longer preview and clips a taller one, no scroll). Over it: Write every `operations` entry and the digest to `.temp/bridge-setup/operations-<first 12 digest chars>.md` first, make every option's `preview` the operation count, the approval digest and `→ full operations: <path>`, and name that path in the step-3 question text — never ask approval for operations the user could not see.
3. Obtain explicit approval for exactly that digest via the `AskUserQuestion` tool — never a plain-text question. State:
- action and purpose;
- exact native argv and resolved target/scope;
- external capability;
- credential behavior;
- filesystem and host-configuration effects;
- rollback evidence;
- retry policy; and
- safe denial outcome.
4. After approval, rerun the identical command with `--approve "<approval_digest>"`.

> Host-held HMAC makes digest tamper-evident but does not grant consent; explicit operator or host approval remains required. The digest is action-bound, expires, and is consumed by its first execution attempt. Never substitute `--approve` without its digest. Denial, changed or expired digest, replay, unsupported capability, failed probe, or failed native operation stops without retry.

## Authentication

When authentication remains:

1. Re-plan the provider-owned interactive login with identical host, workspace, target, scope, and live values but `--action authenticate`.
2. Obtain separate approval for that action's digest via the `AskUserQuestion` tool and state exact `authentication_argv` may open a browser and use network and account state.
3. Give operator identical authenticate command plus `--approve "<authentication_digest>"` to run in their own terminal.

> Sensitive phase: never run through model-controlled Bash or another captured tool stream. Bridge then launches only native login command with terminal inherited. Never accept, request, pipe, echo, inspect, or store a token, API key, browser code, device code, email, or raw login output. Process exit means `auth-flow-launched`; only a later redacted status probe may establish `host-authenticated`.

## Live verification

When `live=prompt` or `live=required` and `remaining` still lists `live-verification`:

1. Re-plan with identical host, workspace, target, and scope but `--action verify-live`.
2. Obtain a third approval for that action's digest via the `AskUserQuestion` tool and one paid provider call.
3. State network, installed-CLI-managed credential, quota/cost, workspace, and point-in-time semantics.
4. Rerun that same verify-live command with `--approve "<live_digest>"`.

> Never invoke the lower-level live doctor outside this approval path. Successful live CLI result remains partial until the applicable `bridge_status` session/workspace evidence named under Completion boundary is also present. `live=skip` remains `inference-unverified`; never call it ready. Denial under `live=required` is non-ready.

## Completion boundary

For Codex-to-Claude repository transfer consent, continue in a fresh Codex session with `$bridge:setup`; its [provider-consent stage](../../rules/provider-consent.md) records an explicit operator-approved policy. Installing either half does not grant that consent. Do not write Codex policy from this Claude setup flow or reuse a configuration/authentication/live-check approval for it. This stage governs the reverse Codex-to-Claude route, not Claude-to-Codex authorization.

- Setup always owns one resolved peer target.
- To prepare both integrations, finish peer lifecycle from Claude, start any required fresh session, then run `$bridge:setup` from Codex for its peer; no digest, state claim, or readiness result is shared between hosts.
- Loaded-host branch is check/bootstrap-only, never mutates its current invocation surface.
- `bridge_status` evidence belongs to a fresh Codex session. An unbound reverse backend is loaded but has no selected project; use `bridge_bind_workspace` there with the known absolute folder as untrusted `proposed_workspace` and exact canonical native confirmation; empty arguments retain manual selection plus confirmation. Require its current `binding_id` and intended workspace before claiming reverse MCP session/workspace ready or passing executable calls; binding grants no runtime permission or paid-call consent.
- Report strongest verified level, exact remaining action, confidence, and limits.

> Never equate static readiness, process exit, host authentication, session readiness, workspace readiness, or live verification.