From 69275d035baff53795aa55c438d78d9a33982662 Mon Sep 17 00:00:00 2001
From: chaodu-agent <pahudev@gmail.com>
Date: Sat, 26 Sep 2026 21:27:58 -0400
Subject: [PATCH] =?UTF-8?q?docs(contract):=20=C2=A79.3=20=E2=80=94=20how?=
 =?UTF-8?q?=20to=20wire=20the=20tools=20URL=20into=20the=20CLI,=20and=20th?=
 =?UTF-8?q?e=20key-rotation=20caveat?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Records the two manual steps a session needs today to use a lent Mac (kiro-cli mcp
add; agent allowedTools for @<server>/<tool> trust) and that the per-generation key
in OPENAB_TOOLS_MCP_URL rotates on restart/re-lend, so hard-coded configs go stale.
Points at #39 (runtime injects + refreshes this at spawn) as the fix.
---
 runtime/CLIENT-CONTRACT.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/runtime/CLIENT-CONTRACT.md b/runtime/CLIENT-CONTRACT.md
index e1d734c..294c987 100644
--- a/runtime/CLIENT-CONTRACT.md
+++ b/runtime/CLIENT-CONTRACT.md
@@ -399,6 +399,40 @@ edit any CLI's config; whatever installs the CLI does that. Properties:
   refuses to start otherwise — but it **is** reachable from the tailnet through
   the sidecar like every other loopback port, which is why the key exists.
 
+#### Wiring the URL into the coding CLI
+
+The runtime sets the env var; it does **not** edit the CLI's config. Whatever owns
+the session's workspace does that. For `kiro-cli` (2.13+), inside the session shell:
+
+```sh
+kiro-cli mcp add --name mac --url "$OPENAB_TOOLS_MCP_URL" --scope global
+```
+
+`mcp add` registers the server but does not trust its tools, so each call prompts.
+To pre-trust them, list them in the agent config's `allowedTools` under the
+`@<server>/<tool>` naming — for the `mac` server, `@mac/screenshot`,
+`@mac/browser_navigate`, … A `~/.kiro/agents/<agent>.json` with both the server and
+the allowlist means the agent starts with the Mac's tools already usable:
+
+```json
+{
+  "name": "kiro_default",
+  "mcpServers": { "mac": { "url": "http://127.0.0.1:<port>/mcp/<session>/<key>" } },
+  "allowedTools": ["@mac/screenshot", "@mac/mouse", "@mac/key", "@mac/osascript",
+                   "@mac/browser_navigate", "@mac/browser_snapshot", "@mac/browser_evaluate", "…"]
+}
+```
+
+Alternatively, per invocation: `kiro-cli chat --trust-tools=@mac/screenshot,@mac/browser_navigate,…`.
+Other CLIs use their own MCP config shape; the URL is the same plain loopback URL.
+
+**Caveat — the key rotates.** The `<key>` in `$OPENAB_TOOLS_MCP_URL` is per session
+*generation*: a restart-in-place, or tearing down and re-lending a Mac, mints a new
+URL, and any config that hard-codes the old one (both `mcp.json` and the agent's
+`allowedTools` server entry) must be updated. Re-run `mcp add`, or read
+`$OPENAB_TOOLS_MCP_URL` again, after each re-lend. Injecting and refreshing this
+automatically at session spawn is [tracked as #39](https://github.com/openabdev/openab-pty/issues/39); until then it is a documented manual step.
+
 ### 9.4 Minimum viable lender
 
 1. Operator: `POST /admin/sessions/{s}/tools-attach`, hand `secret` to the Mac.