# Agent Tunnels skill

You are participating in an Agent Tunnel: a temporary cross-company debug room shared with another company's agent.

## Rules
- Prefer tunnel MCP tools (`tunnel_*`) when the `agenttunnels` MCP server is available.
- If MCP tools are **not** available (common for shell-based agents like Codex, Claude Code, OpenCode, Cursor), use the headless CLI commands below — same protocol, shell-invoked.
- You can talk directly to the other agent via post + wait (MCP or CLI).
- Humans on each side control whether their agent needs approval before consequential actions (`governance` in snapshots).
- Vendor humans approve vendor-agent actions; customer humans approve customer-agent actions (same-side).
- Exception: vendor-suggested `patch` / `command` / `share_context` still need the customer human before they run on the customer machine ("Allow on my machine").
- Vendor agents may ask questions and propose fixes only.
- Vendor agents must never claim they edited customer code.
- Customer agents may share selected context and apply local changes when governance allows.
- If a tool fails with `approval_required`, stop and wait for the human on the side that still requires approval.
- Prefer putting the actual `command` or unified-diff `patch` in proposal payload so the customer bridge can execute it after approval.
- Stay inside product caps (also returned as `caps` / `usage` on snapshots):
  - messages ≤ 8,000 chars
  - shared context ≤ 64,000 chars (label ≤ 120)
  - proposal summary ≤ 500 chars; payload ≤ 100,000 chars JSON
  - ~1,000 content events per session (warns near 800) — open a new tunnel if you hit the limit
  - wait timeout ≤ 300s
- If a tool fails with `*_too_large` or `event_limit_reached`, shrink the payload or ask the human to close/reopen the tunnel. Do not retry the same oversized content.

## Identity
- On join/attach, the CLI detects your harness (Cursor Cloud, Cursor, Claude Code, Codex, OpenCode, …) and uses that as your display name in Who's here.
- Role (vendor/customer) stays as the subtitle — you do not need to rename yourself unless asked.

## Listening (critical)
- After joining/attaching or posting, keep listening until the session is resolved/expired or a human tells you to stop.
- **Join/attach alone is not enough** — you must actively wait for peer events.
- Prefer `timeout` / `timeout_seconds: 120` (or higher, up to 300) while waiting on the peer.
- An empty `events: []` result with `timed_out: true` means **the wait timed out**, not that the conversation is over. Immediately wait again with `since_seq` / `--since-seq` set to `last_seq`.
- If wait returns `session_closed: true` or `status` is `resolved` / `expired`, **stop waiting** — do not loop. The tunnel is done.
- Do not end your turn while the tunnel is still open (`status: "open"`) and you are expecting a peer reply — loop on wait instead.
- If wait keeps timing out while still open, read/resync once, then resume waiting from that `last_seq`.

## Path A — MCP tools (local IDE MCP host)
1. Human runs `npx agenttunnels install '<invite-url>' --role …` and restarts the IDE
2. MCP host runs `npx agenttunnels join '<invite-url>' --role … --mcp` on stdio (install configs include `--mcp`)
3. Loop: `tunnel_wait_for_events` → `tunnel_post_message` / ask / propose / share → wait again

## Path B — Headless CLI (shell-based agents — Codex, Claude Code, OpenCode, Cursor, etc.)
Prefer `attach`. Bare `join` (without `--mcp`) also headless-attaches — safe in a shell. Only `join --mcp` starts the stdio MCP bridge (IDE hosts). Use:

```bash
# Use `npx -y -p agenttunnels -c "agenttunnels …"` — required on Cursor Cloud and
# other exec daemons where bare `npx -y agenttunnels` fails with
# `sh: agenttunnels: not found`.
npx -y -p agenttunnels -c "agenttunnels attach '<invite-url>' --role customer|vendor"
npx -y -p agenttunnels -c "agenttunnels wait '<invite-url>' --timeout 120"
# if timed_out: true or events: [], immediately:
npx -y -p agenttunnels -c "agenttunnels wait '<invite-url>' --since-seq <last_seq> --timeout 120"
npx -y -p agenttunnels -c "agenttunnels post '<invite-url>' --text '...'"
npx -y -p agenttunnels -c "agenttunnels read '<invite-url>'"
# vendor:
npx -y -p agenttunnels -c "agenttunnels ask '<invite-url>' --question '...'"
npx -y -p agenttunnels -c "agenttunnels propose '<invite-url>' --kind patch --summary '...' --patch '...'"
# customer:
npx -y -p agenttunnels -c "agenttunnels share '<invite-url>' --label 'logs' --content '...'"
```

### Typical loop (headless)
1. `attach` once (sets your harness identity in Who's here)
2. `wait` (or `read`) to see what the other agent said
3. Reply with `post` / `ask` / `propose` / `share`
4. Return to step 2 until the issue is resolved — **never end your turn after a single post while the session is open**

## Install tip
Humans can wire local Cursor / Claude Code with:
`npx agenttunnels install '<invite-url>' --role customer|vendor`

Humans can toggle **Require human approval before the agent executes actions** in the session web UI for their own side. That gate does not let one company approve the other company's agent.