feat(egress-proxy-block): single-route input + merge-on-apply

Instead of asking the agent to compose and submit a full routes
file, the tool now takes ONE proposed route — host + optional
path_allowlist + optional auth — and the supervisor merges it
into the live routes table at approval time. The agent no longer
needs to fetch / reproduce / extend the existing allowlist; it
just describes the host it wants reachable.

Tool input (new):
  - `host` (required)
  - `path_allowlist` (optional, array of absolute path prefixes)
  - `auth` (optional, {scheme, token_ref})
  - `justification` (required)

Merge semantics (in `egress_proxy_apply._merge_single_route`):
  - Host NOT in current routes → append the proposed route as a
    new entry. If `auth` is set, assign the next EGRESS_PROXY_TOKEN_N
    slot.
  - Host already present → union the proposed `path_allowlist`
    with the existing one (proposed entries appended after
    existing, deduped). Existing `auth_scheme` / `token_env`
    preserved; proposed `auth` ignored (operator-controlled, not
    agent-controlled).
  - Hostname comparison is case-insensitive.

Dashboard wiring: `approve()` on an egress-proxy-block proposal
now calls `add_route(slug, proposed_route_json)` instead of
`apply_routes_change(slug, full_file)`. add_route fetches the
current routes from the running egress-proxy, merges, and calls
apply_routes_change with the merged content — so the
pipelock-mirror + SIGHUP plumbing from chunk 3 still runs
end-to-end. Audit diff still captures the full-file before/after.

Tool description rewritten to make the new shape obvious and to
stop pointing the agent at the routes file. The
`list-egress-proxy-routes` tool stays available for agents that
want to see what's currently allowed.

Tests: 9 new `_merge_single_route` cases (host absent/present,
path-allowlist union+dedup, auth-slot indexing, case-insensitive
match, existing-auth preservation, missing-host rejection,
malformed-current rejection). 407 unit + integration pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

claude_bottle/supervise_server.py

@@ -134,31 +134,61 @@ TOOL_DEFINITIONS: list[dict[str, object]] = [
         "description": (
             "Call when egress-proxy refused your HTTPS request — host "
             "without a matching route, or a path outside the route's "
-            "path_allowlist (typically a 403 from the proxy). First "
-            "call `list-egress-proxy-routes` to see the current route "
-            "table; compose a modified version that adds or relaxes "
-            "the route you need, and pass the full new file plus a "
-            "justification. The operator approves or rejects in the "
-            "supervise TUI. On approval the supervisor writes the "
-            "new routes.yaml on the host, SIGHUPs egress-proxy (the "
-            "addon's reload swaps the route table atomically without "
-            "dropping in-flight connections), and mirrors the route "
-            "hosts onto pipelock's allowlist so the downstream gate "
-            "lets them through too."
+            "path_allowlist (typically a 403 from the proxy). Propose "
+            "a SINGLE route to add: the host you need + (optionally) "
+            "a path_allowlist + (optionally) an auth block. The "
+            "supervisor merges the route into the live table at "
+            "approval time — you do NOT need to see or reproduce the "
+            "existing routes, and you do not pass a full routes file. "
+            "If the host already has a route, the proposed "
+            "path_allowlist entries are unioned with the existing "
+            "ones (host stays single-route). The operator approves "
+            "or rejects in the supervise TUI. On approval the "
+            "supervisor writes the merged routes.yaml, SIGHUPs "
+            "egress-proxy (atomic swap, no dropped connections), and "
+            "mirrors the host onto pipelock's allowlist for the "
+            "downstream gate."
         ),
         "inputSchema": {
             "type": "object",
             "properties": {
-                "routes": {
+                "host": {
                     "type": "string",
-                    "description": "Full proposed routes.yaml file content (JSON text — every JSON document is valid YAML).",
+                    "description": "The hostname to allow (e.g. 'api.github.com'). Case-insensitive on match.",
+                },
+                "path_allowlist": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Optional URL path prefixes the route permits. "
+                        "Each must start with '/'. Omit to allow all "
+                        "paths under this host (bare-pass route)."
+                    ),
+                },
+                "auth": {
+                    "type": "object",
+                    "description": (
+                        "Optional credential injection. {scheme, "
+                        "token_ref}: scheme is 'Bearer' or 'token'; "
+                        "token_ref names the host env var holding the "
+                        "secret value. Omit to add a host without "
+                        "credential injection. Ignored if the host "
+                        "already has a route (operator decides auth "
+                        "changes, not the agent)."
+                    ),
+                    "properties": {
+                        "scheme": {"type": "string"},
+                        "token_ref": {"type": "string"},
+                    },
+                    "required": ["scheme", "token_ref"],
+                    "additionalProperties": False,
                 },
                 "justification": {
                     "type": "string",
-                    "description": "Why this routes change is justified.",
+                    "description": "Why this host needs to be allowed.",
                 },
             },
-            "required": ["routes", "justification"],
+            "required": ["host", "justification"],
         },
     },
     {
@@ -252,15 +282,22 @@ TOOL_DEFINITIONS: list[dict[str, object]] = [
 # tool-specific payload (stored in Proposal.proposed_file as
 # free-form text the apply path interprets per tool).
 #
-#   egress-proxy-block: full proposed routes.yaml
+#   egress-proxy-block: JSON object describing a SINGLE route to
+#                       add — `{host, path_allowlist?, auth?}`. The
+#                       supervisor merges this into the live routes
+#                       file at approval time.
 #   pipelock-block:     the full failed URL (scheme + host + path) —
 #                       supervisor extracts the host, merges into the
 #                       bottle's current allowlist; the path is shown
 #                       to the operator for context (pipelock doesn't
 #                       do path-level matching).
 #   capability-block:   full proposed Dockerfile
+#
+# Egress-proxy-block doesn't use a single "field name" → the JSON
+# payload is constructed from multiple structured input fields in
+# `handle_egress_proxy_block`. The mapping stays one-entry-per-tool
+# so the generic dispatch keeps working for the other two.
 PROPOSED_FILE_FIELD: dict[str, str] = {
-    _sv.TOOL_EGRESS_PROXY_BLOCK: "routes",
     _sv.TOOL_PIPELOCK_BLOCK: "failed_url",
     _sv.TOOL_CAPABILITY_BLOCK: "dockerfile",
 }
@@ -269,26 +306,18 @@ PROPOSED_FILE_FIELD: dict[str, str] = {
 # --- Validation ------------------------------------------------------------
 
 
+# Auth schemes accepted on egress-proxy-block proposals — match the
+# manifest-side EGRESS_PROXY_AUTH_SCHEMES.
+_AUTH_SCHEMES = ("Bearer", "token")
+
+
 def validate_proposed_file(tool: str, content: str) -> None:
     """Syntactic validation. The operator is the real gate; this just
     catches obvious paste-errors / wrong-tool selections before they
     enter the queue."""
     if not content.strip():
         raise _RpcError(ERR_INVALID_PARAMS, f"{tool}: proposed file is empty")
-    if tool == _sv.TOOL_EGRESS_PROXY_BLOCK:
-        try:
-            parsed = json.loads(content)
-        except json.JSONDecodeError as e:
-            raise _RpcError(
-                ERR_INVALID_PARAMS,
-                f"{tool}: proposed routes.yaml is not valid JSON: {e}",
-            ) from e
-        if not isinstance(parsed, dict) or not isinstance(parsed.get("routes"), list):
-            raise _RpcError(
-                ERR_INVALID_PARAMS,
-                f"{tool}: proposed routes.yaml must be an object with a 'routes' array",
-            )
-    elif tool == _sv.TOOL_PIPELOCK_BLOCK:
+    if tool == _sv.TOOL_PIPELOCK_BLOCK:
         # `content` is the full failed URL. Require scheme + host so
         # the supervisor can extract a hostname for the allowlist
         # merge; the path is preserved for operator context.
@@ -312,6 +341,70 @@ def validate_proposed_file(tool: str, content: str) -> None:
         raise _RpcError(ERR_INVALID_PARAMS, f"unknown tool {tool!r}")
 
 
+def _validate_and_bundle_egress_route(
+    args: dict[str, object],
+) -> str:
+    """Validate egress-proxy-block input fields and bundle them into
+    a JSON string that becomes the Proposal.proposed_file. Raises
+    _RpcError on bad input — the agent retries with a fixed shape."""
+    tool = _sv.TOOL_EGRESS_PROXY_BLOCK
+    host = args.get("host")
+    if not isinstance(host, str) or not host.strip():
+        raise _RpcError(
+            ERR_INVALID_PARAMS,
+            f"{tool}: 'host' is required and must be a non-empty string",
+        )
+    payload: dict[str, object] = {"host": host}
+
+    path_allow_raw = args.get("path_allowlist")
+    if path_allow_raw is not None:
+        if not isinstance(path_allow_raw, list):
+            raise _RpcError(
+                ERR_INVALID_PARAMS,
+                f"{tool}: 'path_allowlist' must be an array of strings",
+            )
+        prefixes: list[str] = []
+        for i, p in enumerate(path_allow_raw):
+            if not isinstance(p, str):
+                raise _RpcError(
+                    ERR_INVALID_PARAMS,
+                    f"{tool}: path_allowlist[{i}] must be a string",
+                )
+            if not p.startswith("/"):
+                raise _RpcError(
+                    ERR_INVALID_PARAMS,
+                    f"{tool}: path_allowlist[{i}] {p!r} must start with '/'",
+                )
+            prefixes.append(p)
+        if prefixes:
+            payload["path_allowlist"] = prefixes
+
+    auth_raw = args.get("auth")
+    if auth_raw is not None:
+        if not isinstance(auth_raw, dict):
+            raise _RpcError(
+                ERR_INVALID_PARAMS,
+                f"{tool}: 'auth' must be an object with 'scheme' and 'token_ref'",
+            )
+        scheme = auth_raw.get("scheme")
+        token_ref = auth_raw.get("token_ref")
+        if not isinstance(scheme, str) or scheme not in _AUTH_SCHEMES:
+            raise _RpcError(
+                ERR_INVALID_PARAMS,
+                f"{tool}: auth.scheme must be one of "
+                f"{', '.join(_AUTH_SCHEMES)} (got {scheme!r})",
+            )
+        if not isinstance(token_ref, str) or not token_ref:
+            raise _RpcError(
+                ERR_INVALID_PARAMS,
+                f"{tool}: auth.token_ref must be a non-empty string "
+                f"naming the host env var holding the token",
+            )
+        payload["auth"] = {"scheme": scheme, "token_ref": token_ref}
+
+    return json.dumps(payload, indent=2) + "\n"
+
+
 # --- MCP handlers ----------------------------------------------------------
 
 
@@ -384,27 +477,35 @@ def handle_tools_call(
         raise _RpcError(ERR_INVALID_PARAMS, "tools/call missing 'name'")
     if name == _sv.TOOL_LIST_EGRESS_PROXY_ROUTES:
         return handle_list_egress_proxy_routes(params.get("arguments", {}), config)
-    if name not in PROPOSED_FILE_FIELD:
-        raise _RpcError(ERR_INVALID_PARAMS, f"unknown tool {name!r}")
+
     args_raw = params.get("arguments", {})
     if not isinstance(args_raw, dict):
         raise _RpcError(ERR_INVALID_PARAMS, "tools/call 'arguments' must be an object")
 
-    file_field = PROPOSED_FILE_FIELD[name]
-    proposed_file = args_raw.get(file_field)
     justification = args_raw.get("justification")
-    if not isinstance(proposed_file, str):
-        raise _RpcError(
-            ERR_INVALID_PARAMS,
-            f"{name}: '{file_field}' is required and must be a string",
-        )
     if not isinstance(justification, str) or not justification.strip():
         raise _RpcError(
             ERR_INVALID_PARAMS,
             f"{name}: 'justification' is required and must be a non-empty string",
         )
 
-    validate_proposed_file(name, proposed_file)
+    if name == _sv.TOOL_EGRESS_PROXY_BLOCK:
+        # Structured input → JSON bundle on Proposal.proposed_file.
+        # The dashboard's apply step (egress_proxy_apply.add_route)
+        # parses this JSON, fetches the current routes, merges in
+        # the new one, and writes the merged file.
+        proposed_file = _validate_and_bundle_egress_route(args_raw)
+    elif name in PROPOSED_FILE_FIELD:
+        file_field = PROPOSED_FILE_FIELD[name]
+        proposed_file = args_raw.get(file_field)
+        if not isinstance(proposed_file, str):
+            raise _RpcError(
+                ERR_INVALID_PARAMS,
+                f"{name}: '{file_field}' is required and must be a string",
+            )
+        validate_proposed_file(name, proposed_file)
+    else:
+        raise _RpcError(ERR_INVALID_PARAMS, f"unknown tool {name!r}")
 
     proposal = _sv.Proposal.new(
         bottle_slug=config.bottle_slug,