@@ -201,4 +201,48 @@ When bumping a plugin version, update all of these:
 2. `cpex_<plugin>/plugin-manifest.yaml` — the `version` field.
 3. `Cargo.lock` — updates automatically on the next build.
 
-Tag releases as `<plugin>-v<version>` (e.g., `rate-limiter-v0.0.2`) on `main` to trigger the PyPI publish workflow.
+Tag releases as `<plugin>-v<version>` (e.g., `rate-limiter-v0.0.2`) on `main` to trigger the PyPI publish workflow.
+
+## OpenTelemetry Integration and Trace Context
+
+### Trace-In / Metrics-Out Convention
+
+Plugins can accept and respond to OpenTelemetry trace context through the optional `extensions` parameter on all hook signatures:
+
+**Hook Signature Convention:**
+```python
+def my_hook(
+    self,
+    payload: typing.Any,
+    context: typing.Any,
+    extensions: typing.Any = None
+) -> typing.Any: ...
+```
+
+**Trace Context Input (`extensions` parameter):**
+- The `extensions` parameter carries OpenTelemetry trace context, including `extensions.request.trace_id` for associating operations with the current request trace.
+- Other fields such as `span_id` may be available on the Extensions object but are not currently consumed by the pii_filter plugin.
+- The parameter is optional and defaults to `None` for backward compatibility.
+
+**Metrics Output (`result.metadata` namespacing):**
+- Plugins emit operational metrics and observability data via `result.metadata[<plugin-name>]` using a namespaced key (e.g., `result.metadata["pii_filter"]`).
+- Metrics are **gated on the presence of a valid `trace_id`**: metrics are only populated when OpenTelemetry trace context is available.
+- All metrics must be non-sensitive: they contain only counts, type labels, and status indicators — **never raw sensitive data or personally identifiable information**.
+
+**Example (pii_filter plugin):**
+```python
+result.metadata["pii_filter"] = {
+    "total_detections": 2,       # total number of PII detections in this call
+    "total_masked": 2,           # total number masked/redacted
+    "detection_types": ["email", "ssn"],  # distinct type names, sorted, deduped
+    "stage": "tool_post_invoke", # which hook stage emitted this
+}
+```
+Note: `trace_id` is an input only (read from `extensions.request.trace_id`) and is never emitted as part of the output metrics.
+
+**When Implementing Trace Context Support:**
+1. Update your hook signatures to accept the optional `extensions` parameter.
+2. Read `trace_id` from `extensions` when available.
+3. Emit metrics to `result.metadata[<plugin-name>]` only when a valid `trace_id` is present.
+4. Ensure all emitted data is non-sensitive and aggregated (counts, not individual values).
+5. Document the metadata keys and values in your plugin's README.
@@ -1,6 +1,6 @@
 [package]
 name = "cpex_framework_bridge"
-version = "0.1.1"
+version = "0.1.2"
 edition.workspace = true
 authors.workspace = true
 license.workspace = true
 
@@ -22,6 +22,23 @@ pub fn build_framework_object<'py, const N: usize>(
         .unbind())
 }
 
+/// Sibling of [`build_framework_object`] for callers with a variable kwarg
+/// count (e.g. an optional trailing `metadata` entry). Prefer the fixed-size
+/// array form when `N` is known at the call site; use this when it isn't.
+pub fn build_framework_object_dyn(
+    py: Python<'_>,
+    class_name: &str,
+    kwargs: Vec<(&str, Py<PyAny>)>,
+) -> PyResult<Py<PyAny>> {
+    let kwargs_dict = PyDict::new(py);
+    for (key, value) in kwargs {
+        kwargs_dict.set_item(key, value.bind(py))?;
+    }
+    Ok(framework_class(py, class_name)?
+        .call((), Some(&kwargs_dict))?
+        .unbind())
+}
+
 pub fn default_result(py: Python<'_>, class_name: &str) -> PyResult<Py<PyAny>> {
     framework_class(py, class_name)
         .and_then(|class| class.call0())
@@ -119,4 +136,36 @@ class PluginViolation:
             );
         });
     }
+
+    #[test]
+    fn build_framework_object_dyn_passes_keyword_arguments() {
+        Python::initialize();
+        Python::attach(|py| {
+            install_framework_module(py).unwrap();
+
+            let result = build_framework_object_dyn(
+                py,
+                "PluginViolation",
+                vec![
+                    ("reason", "blocked".into_py_any(py).unwrap()),
+                    ("code", "POLICY".into_py_any(py).unwrap()),
+                ],
+            )
+            .unwrap();
+            let result = result.bind(py);
+
+            assert_eq!(
+                result
+                    .getattr("reason")
+                    .unwrap()
+                    .extract::<String>()
+                    .unwrap(),
+                "blocked"
+            );
+            assert_eq!(
+                result.getattr("code").unwrap().extract::<String>().unwrap(),
+                "POLICY"
+            );
+        });
+    }
 }
@@ -5,8 +5,8 @@
 # pyo3-stub-gen 0.22.1 still pulls rustpython-parser's unmaintained unic-* parser crates.
 # Keep this scoped to the known transitive advisories so new unmaintained dependencies fail CI.
 ignore = [
-    { id = "RUSTSEC-2026-0176", reason = "pyo3-stub-gen blocks PyO3 0.29 until upstream compatibility release; expires 2026-06-29" },
-    { id = "RUSTSEC-2026-0177", reason = "pyo3-stub-gen blocks PyO3 0.29 until upstream compatibility release; expires 2026-06-29" },
+    { id = "RUSTSEC-2026-0176", reason = "pyo3-stub-gen blocks PyO3 0.29 until upstream compatibility release; expires 2026-08-01" },
+    { id = "RUSTSEC-2026-0177", reason = "pyo3-stub-gen blocks PyO3 0.29 until upstream compatibility release; expires 2026-08-01" },
     "RUSTSEC-2025-0075", # unic-char-range via rustpython-parser
     "RUSTSEC-2025-0080", # unic-common via rustpython-parser
     "RUSTSEC-2025-0081", # unic-char-property via rustpython-parser
 
@@ -0,0 +1,117 @@
+# PII Filter Metrics Schema Contract (D1)
+
+## Overview
+
+This document formalizes the contract for metrics emitted by the `pii_filter` CPEX Rust plugin via the `result.metadata` channel when a trace_id is present in the request extensions.
+
+## Namespace
+
+All metrics are emitted under the `pii_filter` namespace key:
+
+```python
+result.metadata = {
+    "pii_filter": { <metrics dict> }
+}
+```
+
+## Allow-List (S2)
+
+The following fields are the **only fields** permitted in the metrics dict. Gateway validation (G1) must reject any deviation:
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `total_detections` | `int` | Total count of PII items detected across all patterns in this hook invocation | `5` |
+| `total_masked` | `int` | Total count of PII items successfully masked (only populated when masking is applied) | `5` |
+| `detection_types` | `list[str]` | Sorted, deduplicated list of PII pattern type names detected. See bounds (S3). | `["email", "ssn"]` |
+| `stage` | `str` | The plugin hook stage that produced this metric | `"tool_post_invoke"` |
+
+### Semantics
+
+- **total_detections**: Incremented for each distinct PII match found, regardless of masking outcome. For `prompt_post_fetch`, which scans messages one at a time and returns as soon as a blocking message is found, a blocked result's `total_detections` covers only the message that triggered the block, not the whole message list (later messages are never scanned). The non-blocking (masked) path always covers every message in the payload.
+- **total_masked**: Set to `total_detections` when PII is masked in-place; set to `0` when detection blocks the payload without masking.
+- **detection_types**: Contains the canonical string name of each pattern type (e.g., `"email"`, `"ssn"`, `"credit_card"`), sorted alphabetically, deduplicated, and bounded to 32 types.
+- **stage**: One of `"prompt_pre_fetch"`, `"prompt_post_fetch"`, `"tool_pre_invoke"`, or `"tool_post_invoke"`.
+
+## Deny-List (S1): Content-Bearing Fields
+
+The following fields **MUST NOT** appear in the metrics dict, even in part. This prevents leakage of sensitive information:
+
+| Field | Reason |
+|-------|--------|
+| Matched PII values | Any field containing the actual detected secret (e.g., email address, SSN, credit card number) |
+| Raw payloads or excerpts | Substrings of the input that contained PII |
+| Masking instructions or patterns | Details of where or how masking was applied that would reveal the original content |
+| Source field names or paths | Full paths to input fields that contained PII (e.g., `user.email.address`) — only the pattern type is safe |
+
+### Validation
+
+- No string dump of the metrics dict may contain any matched value that was input to the detector.
+- No field must include regex patterns, character counts (of masked segments), or other information that could be used to infer the original content.
+
+## Bounds (S3)
+
+### Detection Types List
+
+The `detection_types` list is bounded to **32 entries maximum**. Enforcement:
+
+1. The plugin truncates the sorted, deduplicated type list to the first 32 entries.
+2. If more than 32 distinct types are detected, only the first 32 (alphabetically) are retained.
+3. The gateway validation (G1) must reject any `detection_types` field exceeding 32 entries.
+
+### Field Sizes
+
+- `total_detections` and `total_masked`: standard 64-bit signed integers (no practical upper bound).
+- `detection_types`: each entry is a string ≤ 32 characters; total list is ≤ 32 entries.
+- `stage`: fixed to one of 4 known values (see Semantics).
+
+## Emission Criteria
+
+Metrics are **only emitted** when:
+
+1. A trace_id is present in `extensions.request.trace_id`.
+2. At least one PII detection occurred during the hook invocation.
+
+When trace_id is absent or no detections occur, the `result.metadata` dict is omitted entirely (or does not contain the `pii_filter` key).
+
+## Example
+
+### Input
+
+```
+payload.result = {
+    "user_email": "alice@example.com",
+    "account_id": "acc-123",
+    "ssn": "123-45-6789"
+}
+extensions.request.trace_id = "trace-xyz"
+```
+
+### Detector Output
+
+- Detections: 2 items (email, ssn)
+- Types: ["email", "ssn"]
+- Action: Masked in-place (total_masked = 2)
+
+### Emitted Metrics
+
+```python
+result.metadata = {
+    "pii_filter": {
+        "total_detections": 2,
+        "total_masked": 2,
+        "detection_types": ["email", "ssn"],
+        "stage": "tool_post_invoke"
+    }
+}
+```
+
+**NOT emitted:**
+- `"user_email": "alice@example.com"` (matched value)
+- `"matched_fields": ["user_email", "ssn"]` (field names)
+- `"mask_applied_at": ["user_email"]` (location details)
+
+## References
+
+- **A3**: Implementation of `build_pii_metrics` in Rust plugin (`src/plugin.rs`).
+- **G1**: Gateway validation of metric contracts (cross-repo).
+- **S1, S2, S3**: Security (leakage), structural (allow-list), and scale (bounds) guarantees.