feat(layer): read_out_of_scope scope gating for read_context via PermissionGate

[jlunder00]

Summary

• A — PermissionGate scope context: Adds optional scope_source_node_id, scope_radius, scope_mode, hop_distance_fn, resolve_node_path_fn to PermissionGate.__init__. All default to None — existing callers are fully backwards-compatible.
• B — Hop distance query: Adds get_node_hop_distance(conn, from_node_id, to_node_id) -> int | None to db/pg_queries/nodes.py. Uses an LCA-based recursive CTE over context_nodes. Returns None when nodes are in separate trees.
• C — read_context scope check: When scope params are set, can_use_tool("read_context", ...) checks all target node_ids (and resolves paths) against the hop distance limit. First offender triggers permission_request(kind="read_out_of_scope") and awaits user approval.

Design decisions

IAL has no DB pool: Scope checking is injected as callables (hop_distance_fn, resolve_node_path_fn) — pre-bound to a DB connection in production wiring, mocked in tests. Same pattern as check_grant_fn/insert_grant_fn.

Path bypass prevention: read_context accepts both node_ids and paths. Both are scope-checked. Unresolvable paths (resolver returns None, or no resolver provided) are treated as out-of-scope to prevent bypass via path arguments.

Distance metric: Undirected tree distance (shortest path via LCA). scope_mode defaults to "tree_distance"; "descendant_only" is reserved for future activation.

Session options keys: scope_source_node_id and scope_radius in session.options. No existing callers set these today — bot dispatcher and frontend session-start will populate them in a follow-on PR when scope gating is wired end-to-end.

Performance note

get_node_hop_distance uses a recursive CTE that scans O(depth) rows per node. For large context trees, consider adding an ltree column or a closure table to reduce this to O(1) lookups. Not an issue at current scale but worth tracking as the tree grows.

Test plan

• 16 new tests/interactive_agent_layer/test_scope_gating.py — no-scope pass-through, in-scope allow, out-of-scope prompt, None-distance prompt, path resolution, path bypass prevention, multi-target first-offender, timeout deny, pending cleanup
• 8 new tests/db/test_node_hop_distance.py — mocked asyncpg, no DATABASE_URL required; covers distance cases 0/1/2/4/None, Decimal coercion, UUID arg contract
• All 165 existing IAL tests pass — zero regressions