feat(pip): add PolicyClient for RFC-005 PDP integration (Option B)

[beonde]

Summary

Adds the Python-side Policy Integration Point (PIP) module for RFC-005, implementing Option B architecture where all PDP decision logic is delegated to the Go core's EvaluatePolicyDecision gRPC RPC.

Depends on: capiscio-core#43 (Go-side EvaluatePolicyDecision RPC)

Architecture

┌─────────────────────────┐
│   Python SDK (this PR)  │
│                         │
│  PolicyClient.evaluate()│──gRPC──▶ Go Core
│  ┌───────────────────┐  │         EvaluatePolicyDecision()
│  │ Obligation exec   │  │         ┌─────────────────────┐
│  │ (rate_limit, etc) │  │         │ PDP query + timeout │
│  │ Response propagate│  │         │ Decision cache      │
│  └───────────────────┘  │         │ Break-glass         │
└─────────────────────────┘         │ Enforcement modes   │
                                    └─────────────────────┘

New Files

capiscio_mcp/pip.py

• PolicyClient — thin gRPC caller that builds PolicyDecisionRequest, sends to core, parses PolicyDecisionResponse
• PIPConfig — PDP endpoint, timeout, enforcement mode, PEP ID, workspace, break-glass key path
• PolicyResult — decision + obligations + metadata, with convenience properties (allowed, denied, pdp_error)
• Obligation — parsed obligation with typed params dict
• PolicyResult.execute_obligations() — dispatches obligations to registered async handlers

tests/test_pip.py — 23 tests

• PolicyResult properties (allowed/denied/pdp_error for ALLOW, DENY, ALLOW_OBSERVE)
• Obligation and PIPConfig dataclasses
• Obligation execution: handler dispatch, unknown types skipped, exceptions logged
• PolicyClient gRPC integration (mock): allow, deny, observe+unavailable, obligations parsed, bad JSON fallback, cache hit, break-glass override, badge-only mode, request field fidelity

Proto Updates

• Regenerated gen/ stubs from capiscio-core feature/rfc005-pdp-rpc proto
• Adds EvaluatePolicyDecision RPC + 6 new message types (PolicyDecisionRequest/Response, PolicySubject, PolicyAction, PolicyResource, PolicyConfig, MCPObligation)
• Updated hand-written stubs with matching dataclasses for IDE support

Test Results

• 373/373 tests pass (including 23 new PIP tests)
• No regressions

[github-actions]

✅ Integration tests passed! capiscio-core gRPC tests working.

[Copilot]

Pull request overview

Adds the Python Policy Integration Point (PIP) for RFC-005 by introducing a thin PolicyClient that delegates policy decisions to capiscio-core’s new EvaluatePolicyDecision gRPC RPC, returning a PolicyResult with obligations for the SDK to execute.

Changes:

• Added capiscio_mcp.pip with PolicyClient, PIPConfig, PolicyResult, and obligation execution support.
• Added a new tests/test_pip.py suite covering PolicyResult behavior, obligation handling, and mocked gRPC evaluation.
• Regenerated/updated proto stubs to include the EvaluatePolicyDecision RPC and related message types.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
capiscio_mcp/pip.py	New PIP client module that builds a PolicyDecisionRequest, calls core via gRPC, parses obligations, and exposes PolicyResult.
tests/test_pip.py	New test suite for PIP behavior, obligation execution, and request/response parsing.
capiscio_mcp/_proto/gen/capiscio/v1/mcp_pb2_grpc.py	Generated gRPC stub updated with EvaluatePolicyDecision and version gating logic.
capiscio_mcp/_proto/gen/capiscio/v1/mcp_pb2.py	Generated protobuf definitions updated to include RFC-005 messages and RPC.
capiscio_mcp/_proto/capiscio/v1/mcp_pb2_grpc.py	Hand-written async stub placeholder updated with EvaluatePolicyDecision method signature.
capiscio_mcp/_proto/capiscio/v1/mcp_pb2.py	Hand-written placeholder message definitions extended with RFC-005 dataclasses.

[github-actions]

✅ Integration tests passed! capiscio-core gRPC tests working.

[github-actions]

✅ Integration tests passed! capiscio-core gRPC tests working.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

[Copilot]

trust_level is typed as str and passed directly into PolicySubject.trust_level (a proto string field). Most callers in this codebase represent trust levels as ints/TrustLevel (e.g., GuardResult.trust_level), so passing an int here would raise a TypeError when constructing the protobuf message. Consider accepting int | str (and/or TrustLevel) and normalizing via str(trust_level) before building the request.

[Copilot]

The generated protobuf module enforces Protobuf Python Version: 6.31.1 via ValidateProtobufRuntimeVersion(...), which will raise at import time if the runtime protobuf major version is < 6. This is incompatible with the declared dependency floor (protobuf>=4.25.0), so installs that satisfy pyproject.toml can still break at runtime. Either bump the dependency to protobuf>=6.31.1 (or >=6.x) or regenerate the stubs with a protoc/protobuf version that matches the supported protobuf range.