feat(sdk/python): @rule, @agent, exception mapping + bridge protocol fixes

[evansibok]

Summary

Python SDK (sdks/python/nanny-sdk)

• @tool(cost=N): sync + async wrappers, /tool/call POST, deny → typed exception, passthrough mode
• @rule("name"): client-side evaluation via _RULES ordered dict; RuleDenied raised before bridge is contacted; _reset_rules autouse fixture keeps tests isolated
• @agent("name"): /agent/enter + /agent/exit with try/finally; AgentNotFound on 404; sync and async both supported
• agent_exit fix: silently ignores ConnectError when bridge closes connection after issuing a stop — prevents cleanup call from masking the real stop reason
• Exception mapping: all StopReason variants map to typed exceptions (BudgetExhausted, MaxStepsReached, RuleDenied, Timeout)
• Passthrough mode: zero-overhead when NANNY_BRIDGE_SOCKET / NANNY_BRIDGE_PORT are unset — decorators are no-ops
• 66 tests across test_tool.py, test_rule.py, test_agent.py, test_exceptions.py, test_passthrough.py
• Python floor raised to >=3.11 — 3.10 EOL is October 2026; ruff target-version and mypy python_version updated to match

Bridge protocol corrections

Found via Rust bridge source audit — the original implementation had drifted from the actual bridge:

• Auth header: X-Nanny-Token → X-Nanny-Session-Token
• /health response: {"status":"ok"} → {"state":"running"}
• /tool/call deny fields: generic "detail" → "tool_name" / "rule_name" as separate fields
• /agent/enter: 404 → AgentNotFound, not {"status":"denied"}
• /agent/exit: request body {} not {"name": name}

Transport fix

The SDK previously only read NANNY_BRIDGE_PORT — silently broken on macOS/Linux where the CLI injects NANNY_BRIDGE_SOCKET (Unix domain socket) instead. NANNY_BRIDGE_PORT is Windows-only.

• _make_client() routes to HTTPTransport(uds=...) on Unix, plain TCP on Windows
• is_passthrough() checks both env vars

dev_assist — LangChain example app (examples/python/dev_assist)

• Single-agent debug assistant: given a stack trace, diagnoses root cause and suggests a fix
• Two execution modes: ReAct (self-controlled Thought/Action/Observation loop) and Plan-and-Execute (structured JSON plan → deterministic execution → synthesis)
• Tools: file_reader, ripgrep, write_file — each decorated with @nanny_tool
• @rule("no_read_loop"): fires if last 5 tool calls are all file_reader
• @nanny_agent("debugger"): activates [limits.debugger] scope for the run
• CLI: uv run dev debug --trace <file> [--mode react|plan]
• nanny.toml demo limits: demo-budget, demo-steps, demo-rule — all three stop reasons verified under nanny run

metrics_crew — CrewAI example app (examples/python/metrics_crew)

• Four-agent sequential pipeline: Ingestion → Analysis → Visualization → Reporter
• Each agent has a designated tool subset; cross-role tool calls result in ToolDenied
• 7 tools: validate_schema, load_metrics, compute_stats, detect_anomalies, correlate_signals, generate_chart, write_report — each decorated with @nanny_tool
• @rule("no_analysis_loop"): fires if last 5 tool calls are all compute_stats
• @nanny_agent("analysis"): activates [limits.analysis] scope for the run
• CLI: uv run metrics-crew analyze --data <csv>
• nanny.toml demo limits: demo-budget, demo-steps, demo-rule — all three stop reasons verified under nanny run
• CrewAI 1.14 compatibility: patches BaseTool.run and Tool.run at import time to re-raise NannyStop as _NannySignal(BaseException), bypassing CrewAI's executor except Exception handlers that would otherwise swallow stop signals

CI

• ci.yml renamed to ci-rust.yml (name: CI — Rust)
• ci-python.yml added (name: CI — Python SDK) — pytest + ruff + mypy, macOS + Linux, Python 3.11 + 3.13, triggers on sdks/python/** changes

Test plan

• uv run pytest -q — 66 tests passing
• uv run mypy nanny_sdk — zero errors
• uv run ruff check . — zero warnings
• cd examples/python/dev_assist && nanny run --limits=demo-budget — BudgetExhausted panel, NDJSON ExecutionStopped on stdout
• cd examples/python/metrics_crew && nanny run --limits=demo-budget — BudgetExhausted panel, NDJSON ExecutionStopped on stdout
• cd examples/python/metrics_crew && nanny run --limits=demo-steps — MaxStepsReached panel
• cd examples/python/metrics_crew && nanny run --limits=demo-rule — RuleDenied panel