feat(pi-ssh): add reviewed agent connection flow

pi-ssh/README.md

@@ -2,6 +2,7 @@
 
 `pi-ssh` keeps Pi and its local tools on the local machine while exposing explicit remote tools over a persistent Node `ssh2` connection:
 
+- `ssh_connect`
 - `ssh_read`
 - `ssh_write`
 - `ssh_edit`
@@ -17,6 +18,8 @@ Runtime connections are pure `ssh2`; the extension does not spawn OpenSSH and do
 
 Hosts must be explicitly imported before use. OpenSSH remains only an import source: the configuration helper runs `ssh -G <alias>` once to resolve the selected alias, then stores the resulting endpoint and authentication data in the pi-ssh vault. Later changes to `~/.ssh/config` require re-importing the host.
 
+Connections are agent-controlled: when the user explicitly names an imported host as part of a concrete remote task, the model calls `ssh_connect`. The connection request enters the normal permission and auto-review chain before any network connection is opened. The extension does not register `/ssh`, `--ssh`, automatic session resume, or remote user-`!` overrides.
+
 ProxyJump and ProxyCommand are intentionally rejected in the first ssh2 release.
 
 ## Configure hosts
@@ -73,29 +76,23 @@ Private-key contents are not copied into the vault.
 
 ## Usage
 
-Connect interactively:
+Ask Pi for a concrete task on an imported host, for example:
 
 ```text
-/ssh
-/ssh packaging-server
-/ssh packaging-server:/absolute/remote/path
-/ssh status
-/ssh off
+Connect to packaging-server, inspect the API logs, and identify the recent 500 errors.
 ```
 
-Or at startup:
+The model first calls:
 
-```sh
-pi --ssh packaging-server
-pi --ssh packaging-server:/absolute/remote/path
+```text
+ssh_connect({ hostId: "packaging-server" })
 ```
 
-Only imported host IDs are accepted. Arbitrary `user@host` targets are rejected.
-
-The active host ID and remote cwd are stored in the Pi session for resume. Credentials are never stored in Pi session entries.
+It may set `remotePath` to an absolute path, `~`, or a path beginning with `~/`. After the reviewed connection succeeds, the model uses the other `ssh_*` tools to complete the requested work. Only imported host IDs are accepted; arbitrary `user@host` targets are rejected. A new connection replaces the previous active connection, and session shutdown disconnects it.
 
 ## Runtime behavior
 
+- `ssh_connect` is the only runtime connection surface; it is agent-callable and permission-reviewed.
 - One persistent `ssh2` client is used for the active host.
 - Each `ssh_bash` call opens an exec channel and runs under `bash -lc` in the selected remote cwd.
 - SFTP provides remote reads and writes.
@@ -128,6 +125,7 @@ The remote host must provide `bash`. SFTP support is required for file tools.
 
 All remote operations enter the bundle's existing permission chain:
 
+- `ssh_connect` starts as `ask`, so AutoReview can verify that the direct user request names the requested imported host;
 - `ssh_read`, `ssh_write`, `ssh_edit`, `ssh_find`, and `ssh_grep` start as `ask`;
 - `ssh_bash` uses the full deterministic Bash policy and `decisionFloor: "ask"`;
 - deterministic hard denies remain denies;
@@ -143,7 +141,7 @@ Permission evidence includes the configured host ID, resolved endpoint, port, re
 - Treat both vault files as secrets even though `hosts.enc` is encrypted.
 - The extension's threat model does not protect credentials from malicious code already running as the same local user.
 - Password keyboard-interactive mode reuses the configured password for the server's prompts; use it only with a trusted pinned host.
-- Remote content reaches the model only through an explicit `ssh_*` call or explicit user `!` command.
+- Remote content reaches the model only through an explicit reviewed `ssh_*` tool call.
 
 ## Development