connect
  ├─ endpoint reachable
  │    ├─ project resolved → expose tools
  │    └─ project missing  → idea ctx.cwd → retry → expose or fail
  └─ endpoint unreachable
       └─ idea ctx.cwd → retry saved URL → expose or stale warning

# IntelliJ extension plan

## Goal

Provide explicit, session-local access to IntelliJ's integrated MCP server.
Starting Pi performs no IntelliJ work and exposes no IntelliJ tools.

## Invariants

- `/intellij connect` is the only normal activation path.
- Disconnected means no IntelliJ tools are active or visible to the agent.
- Every MCP tool call carries `projectPath = ctx.cwd` when supported.
- IntelliJ's Exposed Tools configuration is the sole tool allowlist.
- The extension persists only the last validated URL.
- Never silently replace a saved URL.
- Never close an IntelliJ project automatically.
- Startup and reload perform no network, filesystem scan, or subprocess work.

## Settings

Store the machine-wide endpoint under `intellij.url` in Pi's global `settings.json`.
Preserve unrelated settings and write updates atomically.
Do not store launchers, projects, credentials, headers, or tool selections.

## Commands

### `/intellij connect <url>`

1. Normalize and validate the loopback Streamable HTTP URL.
2. Connect and complete MCP initialization.
3. Verify the endpoint identifies as a JetBrains MCP server.
4. Ensure `ctx.cwd` is open, using the IntelliJ launcher when necessary.
5. List IntelliJ's exposed tools.
6. Register missing Pi tool adapters and add the current catalog to Pi's active tools.
7. Persist the URL only after the complete connection succeeds.

### `/intellij connect`

1. Read `intellij.url` from trusted project settings, else user settings; explain `/intellij connect <url>` when absent.
2. Try the saved endpoint first.
3. If reachable but `ctx.cwd` is unavailable, launch `idea <ctx.cwd>` and retry project resolution.
4. If unreachable, launch `idea <ctx.cwd>` and retry the same URL for a bounded period.
5. On success, expose the current catalog.
6. On failure, keep all IntelliJ tools inactive and report the saved URL as stale.
7. Give the exact JetBrains Copy HTTP Stream Config recovery step and replacement command.

The JetBrains launcher decides whether to reuse an open IntelliJ process or start a fresh one.
Find platform-appropriate `idea` launchers through native `PATH` inspection without spawning a probe.
When absent, explain how to create the JetBrains command-line launcher.

### `/intellij disconnect`

Close the MCP client, remove every IntelliJ tool from Pi's active tools, preserve all other active tools, and retain the saved URL.

### `/intellij reconnect`

Disconnect, reconnect the saved URL, refresh the remote catalog, and reactivate only live tools.
Do not launch IntelliJ or discover another URL.

### `/intellij status`

Show disconnected, connecting, connected, or failed state; endpoint; project path; and active tool count.
Never initiate connection or process work.

### `/intellij tools`

Show IntelliJ's last fetched exposed-tool catalog and current liveness.
Never maintain a second allowlist.

All subcommands provide argument completion.

## Tool bridge

- Prefix remote names with `intellij_` and resolve collisions deterministically.
- Convert MCP JSON Schema to Pi-compatible schemas without weakening required fields.
- Hide bridge-owned `projectPath` parameters from the agent schema and inject exact `ctx.cwd` where the remote schema accepts them.
- Preserve text, image, structured, and legacy result content; serialize unsupported MCP content as bounded text.
- Forward progress and cancellation when supported by the pinned SDK.
- Allow each remote operation's requested timeout plus transport grace.
- Turn remote protocol errors and unsuccessful structured results into contextual, actionable Pi tool errors.
- Reject calls while disconnected, stale, or routed outside `ctx.cwd`.
- Keep removed tools registered but inactive because Pi cannot unregister tools.
- Add and remove only extension-owned names from Pi's active-tool set.
- Refresh tool descriptions and schemas only after explicit connect or reconnect.

## Presentation

- Show a verified IntelliJ Nerd Font icon plus connecting, healthy, or failed state in the footer; never show tool counts there.
- Give every tool its normalized JetBrains description plus explicit session-project routing context.
- Add one shared prompt guide for choosing IntelliJ semantic operations and validating edits without duplicating guidance across all tools.
- Keep collapsed tool rows compact: operation, primary target, outcome, and bounded counts only.
- Show readable paths, diagnostics, matches, lists, structured JSON, patches, and image placeholders only when expanded.
- Reuse Pi's configured tool-expansion key hint.

## Connection and project opening

```text
connect
  ├─ endpoint reachable
  │    ├─ project resolved → expose tools
  │    └─ project missing  → idea ctx.cwd → retry → expose or fail
  └─ endpoint unreachable
       └─ idea ctx.cwd → retry saved URL → expose or stale warning
```

Use bounded retries with cancellation and no blocking startup hook.
Concurrent Pi sessions may share one IntelliJ endpoint because each call is pinned to its session cwd.
Explicit URLs remain authoritative when multiple IDE instances exist.

## Safety

- Accept only loopback HTTP endpoints.
- Never send MCP traffic to arbitrary hosts.
- Validate every advertised tool name and schema before registration.
- Treat MCP results as untrusted tool output.
- Preserve IntelliJ command-confirmation behavior, including brave-mode ownership in IntelliJ.
- Prefer executable launchers and pass `ctx.cwd` as one argument.
- Invoke script launchers only through their explicit platform host with fixed arguments and no command interpolation.
- Do not probe Git, scan projects, trust directories, or modify IntelliJ settings.

## Implementation slices

1. **Scaffold:** package, no-op entry point, README, plan, real-runtime load test.
2. **State:** URL validation, atomic global-settings update, disconnected-by-default lifecycle.
3. **Transport:** pinned MCP SDK, lazy Streamable HTTP client, initialization, close, cancellation, compatibility fixtures.
4. **Bridge:** schema conversion, namespaced registration, active-tool restoration, result mapping.
5. **Commands:** connect, disconnect, reconnect, status, tools, completion.
6. **Project sync:** native PATH lookup, shell-free launcher, cwd verification, bounded retry, stale-URL guidance.
7. **Integration:** controlled fake MCP server and fake launcher through the real extension path on Windows, macOS, and Linux.

Each slice must leave `mise run build -- intellij` and targeted tests passing.

## Required tests

- Real Pi runtime loads with zero active IntelliJ tools and no startup I/O.
- URL validation accepts loopback Streamable HTTP and rejects remote or malformed URLs.
- URL persists only after successful connection and preserves unrelated settings.
- Saved URL connects without launching IntelliJ.
- Missing project invokes the fake launcher once with exact cwd and then resolves.
- Closed IntelliJ invokes the fake launcher, retries the saved URL, and connects.
- Stale URL leaves tools inactive and prints actionable replacement instructions.
- Connect exposes only the server-advertised catalog.
- Every compatible call receives exact `ctx.cwd` as `projectPath`.
- Disconnect removes only IntelliJ tools and closes transport.
- Reconnect refreshes added and removed tools without reviving stale tools.
- Text, image, errors, progress, cancellation, collisions, and malformed schemas traverse the real bridge.
- Concurrent clients route two worktree paths without cross-project leakage.
- Fake executable tests exercise native PATH detection and shell-free spawning on every platform.

## Done

- All specified commands and transitions work through the real Pi extension runtime.
- No IntelliJ tool appears before explicit connection.
- No normal successful workflow requires manual project opening or repeated URL entry.
- `mise run ci` passes.