agenticdome-python-sdk 1.2.35__py3-none-any.whl → 1.2.36__py3-none-any.whl

{agenticdome_python_sdk-1.2.35.dist-info → agenticdome_python_sdk-1.2.36.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agenticdome-python-sdk
-Version: 1.2.35
+Version: 1.2.36
 Summary: Official Python SDK for AgenticDome security guardrails, DLP, tool authorization, and multi-agent delegation enforcement.
 Author: AgenticDome
 License-Expression: Apache-2.0
@@ -33,7 +33,7 @@ Requires-Dist: requests>=2.31.0
 Requires-Dist: urllib3>=2.0.0
 Requires-Dist: cryptography>=42.0.0
 Provides-Extra: crewai
-Requires-Dist: crewai<=1.15.22,>=1.15.5; extra == "crewai"
+Requires-Dist: crewai<=1.15.23,>=1.15.5; extra == "crewai"
 Provides-Extra: redis
 Requires-Dist: redis>=4.5.0; extra == "redis"
 Provides-Extra: pop
@@ -46,7 +46,7 @@ Requires-Dist: pydantic-ai<=2.51.0,>=2.16.0; extra == "pydantic"
 Requires-Dist: anyio>=4.0.0; extra == "pydantic"
 Provides-Extra: langgraph
 Requires-Dist: langgraph<=1.2.12,>=1.2.9; extra == "langgraph"
-Requires-Dist: langchain-core<=1.6.5,>=1.5.0; extra == "langgraph"
+Requires-Dist: langchain-core<=1.6.6,>=1.5.0; extra == "langgraph"
 Requires-Dist: langchain-openai==1.3.5; extra == "langgraph"
 Requires-Dist: anyio>=4.0.0; extra == "langgraph"
 Provides-Extra: microsoft
@@ -64,9 +64,9 @@ Requires-Dist: openai-agents<=0.22.3,>=0.18.3; extra == "openai-agents"
 Provides-Extra: mcp
 Requires-Dist: mcp<=2.2.0,>=1.26.0; extra == "mcp"
 Provides-Extra: bedrock
-Requires-Dist: boto3<=1.43.103,>=1.43.54; extra == "bedrock"
+Requires-Dist: boto3<=1.43.105,>=1.43.54; extra == "bedrock"
 Provides-Extra: aws-bedrock
-Requires-Dist: boto3<=1.43.103,>=1.43.54; extra == "aws-bedrock"
+Requires-Dist: boto3<=1.43.105,>=1.43.54; extra == "aws-bedrock"
 Provides-Extra: llamaindex
 Requires-Dist: llama-index<=0.14.25,>=0.14.23; extra == "llamaindex"
 Provides-Extra: llama-index
@@ -76,19 +76,19 @@ Requires-Dist: google-adk<=2.10.0,>=2.5.0; extra == "google-adk"
 Provides-Extra: adk
 Requires-Dist: google-adk<=2.10.0,>=2.5.0; extra == "adk"
 Provides-Extra: claude
-Requires-Dist: claude-agent-sdk<=0.2.160,>=0.2.126; extra == "claude"
+Requires-Dist: claude-agent-sdk<=0.2.162,>=0.2.126; extra == "claude"
 Provides-Extra: claude-agent-sdk
-Requires-Dist: claude-agent-sdk<=0.2.160,>=0.2.126; extra == "claude-agent-sdk"
+Requires-Dist: claude-agent-sdk<=0.2.162,>=0.2.126; extra == "claude-agent-sdk"
 Provides-Extra: smolagents
 Requires-Dist: smolagents==1.26.0; extra == "smolagents"
 Provides-Extra: all
-Requires-Dist: crewai<=1.15.22,>=1.15.5; extra == "all"
+Requires-Dist: crewai<=1.15.23,>=1.15.5; extra == "all"
 Requires-Dist: redis>=4.5.0; extra == "all"
 Requires-Dist: cryptography>=42.0.0; extra == "all"
 Requires-Dist: pydantic-ai<=2.51.0,>=2.16.0; extra == "all"
 Requires-Dist: anyio>=4.0.0; extra == "all"
 Requires-Dist: langgraph<=1.2.12,>=1.2.9; extra == "all"
-Requires-Dist: langchain-core<=1.6.5,>=1.5.0; extra == "all"
+Requires-Dist: langchain-core<=1.6.6,>=1.5.0; extra == "all"
 Requires-Dist: langchain-openai==1.3.5; extra == "all"
 Requires-Dist: autogen-agentchat==0.7.5; extra == "all"
 Requires-Dist: agno<=3.0.11,>=2.8.0; extra == "all"
@@ -96,10 +96,10 @@ Requires-Dist: azure-ai-projects<=2.7.0,>=2.3.0; extra == "all"
 Requires-Dist: azure-identity==1.25.3; extra == "all"
 Requires-Dist: openai-agents<=0.22.3,>=0.18.3; extra == "all"
 Requires-Dist: mcp<=2.2.0,>=1.26.0; extra == "all"
-Requires-Dist: boto3<=1.43.103,>=1.43.54; extra == "all"
+Requires-Dist: boto3<=1.43.105,>=1.43.54; extra == "all"
 Requires-Dist: llama-index<=0.14.25,>=0.14.23; extra == "all"
 Requires-Dist: google-adk<=2.10.0,>=2.5.0; extra == "all"
-Requires-Dist: claude-agent-sdk<=0.2.160,>=0.2.126; extra == "all"
+Requires-Dist: claude-agent-sdk<=0.2.162,>=0.2.126; extra == "all"
 Requires-Dist: smolagents==1.26.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
@@ -177,16 +177,51 @@ agenticdome inspect --output agenticdome-inspection.json
 
 `init` writes the secret-free inspection and local configuration. For the
 certified onboarding path, obtain the assigned sidecar and a dedicated
-`integration_copilot` key, run `agenticdome integrate preview`, review its
+`integration_copilot` key, run `agenticdome integrate preview` and
+`agenticdome integrate status`, review the saved
 local exact diff and change summary, explicitly approve a supported edit or
 attach other boundaries manually, then run
 `agenticdome verify --run-tests --output .agenticdome/verification.json`.
 Preview obtains the private, signed, catalog-bound semantic plan and keeps
 application source on your machine. `agenticdome integrate apply` creates a
 local Git review branch but never commits, pushes or deploys. Existing-source
-automatic edits are currently limited to one exact certified smolagents run
-pattern; all other paths need manual integration. The older `agenticdome plan`
+automatic edits cover unambiguous CrewAI bootstrap, PydanticAI `Agent(...)`,
+LangChain `create_agent(...)`, Google ADK agent construction, Claude options,
+Agno `Agent(...)`, direct LlamaIndex `FunctionTool.from_defaults(...)`, direct
+OpenAI Agents `FunctionTool(...)` handlers, explicit custom-Python tool
+dispatchers, and the exact smolagents run pattern.
+The CLI leaves dynamic construction,
+existing handwritten AgenticDome calls, MCP forwarding and other framework
+paths for explicit review; a patch never proves all routes are intercepted.
+The older `agenticdome plan`
 and `agenticdome scaffold` remain available as advanced review-only commands.
+Preview auto-selects an application or pure-MCP review path and reports
+existing Python SDK call-site candidates, including handwritten local
+wrappers. Discovery uses the versioned framework hook catalog plus documented
+prompt, tool, A2A/delegation, MCP and output API methods; categories may
+overlap and TypeScript call sites are not parsed by this Python checker. Mixed
+application/MCP workloads get a separate MCP review path.
+Each preview rescans the selected workload. If code added a framework after
+`init`, its certified hook contract is included in the new plan and flagged for
+review without changing `.agenticdome/config.json`; a framework still in that
+config but absent from the current scan is flagged for confirmation. Run
+`agenticdome integrate status` for the saved next action and import a fresh
+`agenticdome inspect --output agenticdome-inspection.json` after reviewing it.
+These static observations do not prove interception; the CLI avoids
+overlapping automatic rewrites and requires real blocked-action tests.
+
+For one consequential tool, run your own safe integration test through the
+actual application route with an `ExecutionSpy` around its test handler, then
+correlate the SDK adapter call, live-mode verdict and handler invocation:
+
+```bash
+agenticdome verify-action --tool billing.refund --expect-verdict BLOCKED --expect-executed no -- pytest -q tests/test_blocked_refund.py
+```
+
+The test must call `spy.assert_calls(0)` (or `1` for an allowed test); see the
+[real action-path test guide](docs/customer-onboarding.md#prove-one-real-action-path).
+This opt-in command does not execute a business action itself, and a fixed
+`agenticdome verify` probe is not a substitute for the real-path test.
 
 For an MCP client, host, gateway or server workload, use the focused path:
 
@@ -224,6 +259,7 @@ openclaw plugins install npm:agenticdome-openclaw-security
 openclaw plugins enable agenticdome-security
 openclaw config set plugins.entries.agenticdome-security.hooks.allowConversationAccess true
 openclaw gateway restart
+openclaw gateway status --require-rpc
 agenticdome openclaw protect
 # With AGENTICDOME_API_BASE, AGENTICDOME_TENANT_ID and the dedicated
 # AGENTICDOME_COPILOT_API_KEY set, generate and review the signed plan:
@@ -232,8 +268,11 @@ agenticdome plan
 agenticdome openclaw verify --output .agenticdome/verification.json
 ```
 
-`openclaw protect` fails unless the active OpenClaw runtime reports the loaded
-AgenticDome plugin, explicit consent and the exact certified typed hooks.
+`openclaw protect` checks the AgenticDome plugin, explicit consent and exact
+typed hooks in the inspecting CLI process. `gateway status` checks the serving
+Gateway's RPC reachability; neither proves that this Gateway ran a hook on a
+customer tool call. Exercise a safe tool through the actual Gateway and inspect
+the matching AgenticDome runtime decision before claiming that route is protected.
 The official `openclaw plugins install`, `enable`, `config set` and gateway
 restart commands are the actual runtime configuration change; the Python CLI
 does not apply or undo them. No application source patch is needed for native
@@ -246,7 +285,8 @@ includes the MCP transport rehearsal and both `mcp_verification` and
 `openclaw_verification` in one report. Both sections must be ready before the
 report is imported; `mcp verify` alone is not a combined-workload proof. The
 customer Control Panel separately confirms tenant binding and retained
-telemetry; neither command silently modifies customer source.
+telemetry for its probes; neither command silently modifies customer source or
+proves that every live Gateway tool route was intercepted.
 
 When `.agenticdome/inspection.json` is imported into Developer Integration,
 the Control Panel adds its detected frameworks to the workload. Frameworks,
@@ -1582,6 +1622,13 @@ async def lookup_customer(customer_id: str) -> str:
     )
 ```
 
+If you construct `agents.FunctionTool` directly, its `on_invoke_tool`
+handler receives JSON text. Use `handler_args_format="json"` with
+`wrap_tool_handler` so the approved or sanitized arguments reach the original
+handler in that same format. The guided integration preview offers this edit
+only for a direct, statically named `FunctionTool` with an identifiable
+handler; other tool factories require manual review and a real-route test.
+
 **Delegated specialist tool pattern:**
 
 ```python

{agenticdome_python_sdk-1.2.35.dist-info → agenticdome_python_sdk-1.2.36.dist-info}/RECORD

@@ -1,42 +1,46 @@
-agenticdome_python_sdk-1.2.35.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-agenticdome_python_sdk-1.2.35.dist-info/licenses/NOTICE,sha256=obvKP6kV1Ny5R8_INFOpf0X5um9U2X43LGwQFobO9kg,550
-agenticdome_sdk/__init__.py,sha256=UY__0ppEM4MlsTQoLh8alZ7AoMjtegGKe4j_Sj7CpNk,903
+agenticdome_python_sdk-1.2.36.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+agenticdome_python_sdk-1.2.36.dist-info/licenses/NOTICE,sha256=obvKP6kV1Ny5R8_INFOpf0X5um9U2X43LGwQFobO9kg,550
+agenticdome_sdk/__init__.py,sha256=1JY5ELhtp0zg-82xhgt6NxZ7k5CWL5e_Tm6BrsuCFXc,1102
 agenticdome_sdk/_framework_firewall.py,sha256=W3gy7WsK50scE7ypJrmVJhHUOBsr0zAWQ85rghqaJk4,31963
 agenticdome_sdk/_mode.py,sha256=XvOgh5sW-FG8S39V483h3uLiFh8wSt14OmYXz_6eDO8,1283
+agenticdome_sdk/action_path_proof.py,sha256=5Zlghy7-LNhtRJM0Unb4NPUASzIsAC0LaWNVFR2yzzo,13497
 agenticdome_sdk/agno.py,sha256=L3yfjTBHW47xzT67a1DsjtwmvrAoYBkbxADpsr85Cp0,60766
 agenticdome_sdk/attestation.py,sha256=ij4cMff7nzLaIS0W02d2WURFcyKe72bcUlSz-dYkaLE,10310
 agenticdome_sdk/autogen.py,sha256=KP4qlIcsNXB-4ZT9D7Slc1xWEeWXRIWkc5HGW0U6k2c,29018
 agenticdome_sdk/aws_bedrock.py,sha256=2zD9j7xi0jna0sMeMf-hKZdc3Y4RPwzj6tMVOUGgIDQ,69581
-agenticdome_sdk/catalog_snapshot.json,sha256=fPbiJC7IjrPyp8ORunaNQenLCg11W43XIDHcMlINFEg,951
+agenticdome_sdk/catalog_snapshot.json,sha256=xHntC0Cjzli4pP0fyTxVtbH90LthGgaq7ad6YGmy54Q,951
 agenticdome_sdk/claude.py,sha256=XeY9AUu61SYcJjQVz_AtL_WaN6X4KqP5nprEbbr4Q6A,17456
-agenticdome_sdk/client.py,sha256=2uVKZR1uXDBIvwOS-lpNPCAXl9K5vroPqsPNNYhBWeg,69473
+agenticdome_sdk/client.py,sha256=SQk7BROrcedyHAfubGiwGNNGycq7W7L-Ncjroj1ugBg,69815
 agenticdome_sdk/connect.py,sha256=MY30wXYA6OaZhs__E67KcFXEy7mZMBxMSV06BnlBjRg,18766
 agenticdome_sdk/copilot_ir.py,sha256=zT13tOX8xu11yrOtIPMRFVud8CQ81Gu3WxsXxyQ4XT0,17928
 agenticdome_sdk/copilot_ir_collector.cjs,sha256=oxLY8ByONo7Es4YjYiJuRz_A7IKL65Sy486UXnu-4Rs,9681
 agenticdome_sdk/crewai.py,sha256=sSJQ49O7-8kqOAD2_jrsMtMOmBOcJmFkeOv7S3-ayMs,52490
 agenticdome_sdk/demo.py,sha256=dyfqt2N_cJoyUWKnjPYuQxuw2hb2DrCNUf1jQKeYYoc,8350
+agenticdome_sdk/existing_integration.py,sha256=be6xFqe3P9d98YOydHzDeyRSbuAim4bLBrfafLOJpJM,11465
+agenticdome_sdk/framework_edits.py,sha256=4BgWHxWKEkex8_DMhjVxjovpUVkrMF7TsCZzlS94mpA,23344
+agenticdome_sdk/generic_python.py,sha256=JtXRcYEZ6_Dgxnnv4QgqeMZR8dFVr8EqFDM-XYQ-GMA,6823
 agenticdome_sdk/google_adk.py,sha256=2TA-tUhY0lOnkGcs1BN9CUEz67ebVX4HJ7mnNoRPcZs,57258
-agenticdome_sdk/guided_integration.py,sha256=JQ5THutpsC1J0yV7gEOJWiLHGLQOKhAlPDFTi5SH5OA,36595
-agenticdome_sdk/hook_catalog.py,sha256=0dfFWNDS0KCeP0IozWZb1NkNBWf1omaO2-yZKNVdTf0,29272
+agenticdome_sdk/guided_integration.py,sha256=m7EsgLrPEJhfrVMaVWO2DtjYp6S8PwpCKDYZPNbVZ2o,52259
+agenticdome_sdk/hook_catalog.py,sha256=4cQvWsuPa2nOZdlhp1Ya6SDo2M83aSHHtiLxrM3dkz8,29272
 agenticdome_sdk/identity.py,sha256=mrymGgZSVsKJ9THRde54qGmMT7j_uZHmPJ-HtWk7PXE,4635
 agenticdome_sdk/langgraph.py,sha256=FUvF6DSA5aZP3eoBoNeldgGtPrz-dO5xcVmrPPSBEhI,84312
 agenticdome_sdk/lifecycle.py,sha256=9LvxmUU1LC_tMchb5uVFBnZIkVFUxOv3VH9wG_9gPtA,12855
 agenticdome_sdk/llamaindex.py,sha256=BHplSUIsgMi7k8tBztprzaV9iaOXiljXbdeMRax_2h8,42860
-agenticdome_sdk/mcp_host.py,sha256=bJG0pCfMYkI6ig4tmPvtJKcdFFfDOXNmatLbh_X9lso,63283
-agenticdome_sdk/mcp_http_gateway.py,sha256=j7B_IVhr0QLSPdsE8iVKcH0mCtQN7EE622JKY3d2LHI,13533
+agenticdome_sdk/mcp_host.py,sha256=T9ICAyz8SjOhssuhXaiEuav5fduWriDhuZ4U_e8Jh9w,69389
+agenticdome_sdk/mcp_http_gateway.py,sha256=XrTgj46ZHIKJ9xS3EQPsac2C9OGUZnrOXomcLdkMk_Y,13629
 agenticdome_sdk/mcp_rehearsal_server.py,sha256=cox4XqUTL8d0gaDzqxDZcEALkaz8otjOjOqHvoUeeCo,2118
-agenticdome_sdk/mcp_verification.py,sha256=VqQS5SpPVFI3G7qCwrT90JmG8vFE6pRJEB7PViHjKqw,14235
+agenticdome_sdk/mcp_verification.py,sha256=WtRhAFVPTBqGOcHNf_db1m4jX9_TO0oxP98XWk4_ISY,14551
 agenticdome_sdk/microsoft_agent_framework.py,sha256=GfIIuk0n-VhsZaTyoB7P6ilpz9bFLD95TWuX0rFSWeU,67219
 agenticdome_sdk/microsoft_ai_foundry.py,sha256=YlO968s1dbAYcaEqhqufL92NFR66GuTtngnCv7-1mYc,56911
-agenticdome_sdk/onboarding_cli.py,sha256=1g-wNEzEpAmR1s-oYS6mqCd0TgT3PQuEqNQk9M0hAQc,124440
-agenticdome_sdk/openai_agents.py,sha256=nNM-YcsUDcE23sGv1buLudcYFz0NLju2Mwiw_wrVaJg,57326
+agenticdome_sdk/onboarding_cli.py,sha256=jfc4owNPrvlVkYa5eLaQfATA6sbgXGkhxf4IJfg6gWo,145081
+agenticdome_sdk/openai_agents.py,sha256=0z-7FDBIG4usxnILpan6yjQHF4zXIzm9YLsh3-bW8Lw,57678
 agenticdome_sdk/outcomes.py,sha256=jadWDzQaZXrHNvpPme8lQY0jihYLCoM3s4CihAq0JRo,2507
 agenticdome_sdk/proof.py,sha256=ECKc14xSE0V1HHmcpZjfVz8-Q2H_fooah3BfdblFV8M,2878
 agenticdome_sdk/pydantic.py,sha256=WKb8X0Fgydfid-ep8E-M8Yslz2pWcCP6w7n_aBxt1rI,54961
 agenticdome_sdk/simulation.py,sha256=UCbZy3u9AzfxQCfY38SCV3CxGxhinV9EA4aHMPlK4mc,8426
 agenticdome_sdk/smolagents.py,sha256=wjMA1HVAQ-9wRNM38Jr9wlCpKMhF-9vxtTk6R-kwQhs,19094
-agenticdome_python_sdk-1.2.35.dist-info/METADATA,sha256=Fn0YW1txEeYaaqT9hykQc-38Qe5IkqwLlcoHreKeS2M,141741
-agenticdome_python_sdk-1.2.35.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-agenticdome_python_sdk-1.2.35.dist-info/entry_points.txt,sha256=cRfCphkr5gLrkGIzXJEtL50HdHLajoZLbZtcMLE8NoY,113
-agenticdome_python_sdk-1.2.35.dist-info/top_level.txt,sha256=LZbbjXco5mqDrGwlTJpIKI5Sp6R_njzHHjExxAs9c3s,16
-agenticdome_python_sdk-1.2.35.dist-info/RECORD,,
+agenticdome_python_sdk-1.2.36.dist-info/METADATA,sha256=4gqvhEqeY-7JwahLP92qIULZ8G8-T5eaQsKUL0eqhUk,144718
+agenticdome_python_sdk-1.2.36.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agenticdome_python_sdk-1.2.36.dist-info/entry_points.txt,sha256=cRfCphkr5gLrkGIzXJEtL50HdHLajoZLbZtcMLE8NoY,113
+agenticdome_python_sdk-1.2.36.dist-info/top_level.txt,sha256=LZbbjXco5mqDrGwlTJpIKI5Sp6R_njzHHjExxAs9c3s,16
+agenticdome_python_sdk-1.2.36.dist-info/RECORD,,

agenticdome_sdk/__init__.py

@@ -3,6 +3,8 @@ from .identity import IDENTITY_CONTEXT_VERSION, canonicalize_identity_context, e
 from .proof import create_dpop_proof, generate_rsa_proof_key, jwk_thumbprint
 from ._mode import LIVE_MODE, LOCAL_SIM_MODE, is_local_sim_mode, resolve_mode
 from .lifecycle import VerifiedActionContext, VerifiedActionDenied, VerifiedActionReporter, verified_action
+from .action_path_proof import ExecutionSpy
+from .generic_python import AgenticDomeActionDenied, guarded_tool_executor
 
 __all__ = [
     "AgenticDomeClient",
@@ -22,4 +24,7 @@ __all__ = [
     "VerifiedActionDenied",
     "VerifiedActionReporter",
     "verified_action",
+    "ExecutionSpy",
+    "AgenticDomeActionDenied",
+    "guarded_tool_executor",
 ]

agenticdome_sdk/action_path_proof.py

@@ -0,0 +1,263 @@
+"""Opt-in, source-free evidence for a customer-run action-path test.
+
+The test must install ExecutionSpy around the actual business handler.  A
+sidecar verdict on its own never proves that the handler did or did not run.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+import json
+import os
+import re
+import stat
+import subprocess
+import sys
+import tempfile
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Sequence, Tuple
+
+
+_ADAPTERS = frozenset({
+    "crewai", "pydantic", "langgraph", "microsoft_agent_framework",
+    "autogen", "microsoft_ai_foundry", "openai_agents", "claude",
+    "smolagents", "agno", "google_adk", "llamaindex", "aws_bedrock",
+    "mcp_host", "generic_python", "_framework_firewall",
+})
+
+
+def _hook_frame() -> Tuple[str, str]:
+    frame = sys._getframe(2)
+    generic = ("", "")
+    try:
+        while frame:
+            module = str(frame.f_globals.get("__name__", ""))
+            if module.startswith("agenticdome_sdk.") and module.rsplit(".", 1)[-1] in _ADAPTERS:
+                if module != "agenticdome_sdk._framework_firewall":
+                    return module, frame.f_code.co_name
+                if not generic[0]:
+                    generic = (module, frame.f_code.co_name)
+            frame = frame.f_back
+    finally:
+        del frame
+    return generic
+
+
+def _append_event(event: Dict[str, Any]) -> None:
+    path = os.environ.get("AGENTICDOME_ACTION_PROOF_FILE", "")
+    if not path or not os.path.isabs(path):
+        return
+    event = {"schema": "agenticdome.action-path-event.v1", **event}
+    encoded = (json.dumps(event, sort_keys=True, separators=(",", ":")) + "\n").encode("utf-8")
+    if len(encoded) > 2048:
+        return
+    flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    try:
+        fd = os.open(path, flags, 0o600)
+        try:
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode) or info.st_size > 262144:
+                return
+            os.write(fd, encoded)
+        finally:
+            os.close(fd)
+    except OSError:
+        # Proof is optional instrumentation; it must not change enforcement.
+        return
+
+
+def record_policy_decision(*, tool_name: Optional[str], platform: Optional[str],
+                           direction: str, response: Dict[str, Any], live: bool) -> None:
+    """Record no prompt, arguments, identity, token, or raw response."""
+    if not os.environ.get("AGENTICDOME_ACTION_PROOF_FILE") or not tool_name:
+        return
+    module, function = _hook_frame()
+    envelope = response.get("result") if isinstance(response.get("result"), dict) else response
+    verdict = str(envelope.get("verdict") or envelope.get("decision") or "UNKNOWN").upper()
+    decision_id = str(envelope.get("decision_id") or response.get("decision_id") or "")
+    _append_event({
+        "kind": "policy_decision", "tool_name": str(tool_name)[:160],
+        "platform": str(platform or "")[:80], "direction": str(direction)[:24],
+        "verdict": verdict if verdict in {"ALLOWED", "BLOCKED", "REDACTED"} else "UNKNOWN",
+        "live": bool(live), "hook_module": module, "hook_function": function,
+        "decision_id": decision_id if re.fullmatch(r"[A-Za-z0-9._:-]{1,100}", decision_id) else "",
+    })
+
+
+class ExecutionSpy:
+    """Wrap the real test handler, then assert its invocation count in the test."""
+
+    def __init__(self, tool_name: str):
+        if not tool_name or len(tool_name) > 160:
+            raise ValueError("tool_name must contain 1-160 characters")
+        self.tool_name = tool_name
+        self.calls = 0
+
+    def wrap(self, handler: Callable[..., Any]) -> Callable[..., Any]:
+        if inspect.iscoroutinefunction(handler):
+            @functools.wraps(handler)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                self.calls += 1
+                _append_event({"kind": "handler_attempt", "tool_name": self.tool_name})
+                return await handler(*args, **kwargs)
+            return async_wrapper
+
+        @functools.wraps(handler)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            self.calls += 1
+            _append_event({"kind": "handler_attempt", "tool_name": self.tool_name})
+            return handler(*args, **kwargs)
+        return sync_wrapper
+
+    def assert_calls(self, expected: int) -> None:
+        if not isinstance(expected, int) or expected < 0:
+            raise ValueError("expected must be a non-negative integer")
+        if self.calls != expected:
+            raise AssertionError(f"Expected {expected} handler calls; observed {self.calls}")
+        _append_event({"kind": "handler_assertion", "tool_name": self.tool_name, "calls": self.calls})
+
+
+def run_action_path_test(root: Path, *, tool_name: str, expected_verdict: str,
+                         expected_calls: int, command: Sequence[str],
+                         timeout_seconds: int = 600) -> Tuple[int, Dict[str, Any]]:
+    """Run an explicit customer test command, never a shell, and inspect evidence."""
+    if not tool_name or len(tool_name) > 160:
+        raise ValueError("tool_name must contain 1-160 characters")
+    expected_verdict = expected_verdict.upper()
+    if expected_verdict not in {"ALLOWED", "BLOCKED", "REDACTED"}:
+        raise ValueError("expected_verdict must be ALLOWED, BLOCKED or REDACTED")
+    if expected_calls not in {0, 1}:
+        raise ValueError("expected_calls must be 0 or 1 for an isolated action test")
+    if (expected_verdict == "BLOCKED" and expected_calls != 0) or (expected_verdict != "BLOCKED" and expected_calls != 1):
+        raise ValueError("Blocked actions must not execute; allowed/redacted actions need one observed test-handler call")
+    if not command or command[0] == "--" or any(not item or "\x00" in item for item in command):
+        raise ValueError("Provide one explicit test command after --; a shell is not used")
+    required = ("AGENTICDOME_API_BASE", "AGENTICDOME_API_KEY", "AGENTICDOME_TENANT_ID")
+    missing = [key for key in required if not os.environ.get(key, "").strip()]
+    if missing:
+        raise ValueError("Live action-path proof requires " + ", ".join(missing))
+    if os.environ.get("AGENTICDOME_MODE", "").strip().lower() in {"local_sim", "simulation", "sim"}:
+        raise ValueError("Action-path proof requires a live assigned sidecar, not local simulation")
+    started = time.monotonic()
+    with tempfile.TemporaryDirectory(prefix="agenticdome-action-proof-") as temporary:
+        journal = Path(temporary) / "events.jsonl"
+        environment = os.environ.copy()
+        environment["AGENTICDOME_ACTION_PROOF_FILE"] = str(journal)
+        try:
+            completed = subprocess.run(list(command), cwd=root, env=environment,
+                                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                                       timeout=timeout_seconds, check=False)
+            test_exit = completed.returncode
+            timeout = False
+        except subprocess.TimeoutExpired:
+            test_exit = None
+            timeout = True
+        events = []
+        if journal.exists():
+            for line in journal.read_text(encoding="utf-8").splitlines()[:200]:
+                try:
+                    value = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if isinstance(value, dict) and value.get("schema") == "agenticdome.action-path-event.v1":
+                    events.append(value)
+    decisions = [item for item in events if item.get("kind") == "policy_decision" and item.get("tool_name") == tool_name]
+    attempts = [item for item in events if item.get("kind") == "handler_attempt" and item.get("tool_name") == tool_name]
+    assertions = [item for item in events if item.get("kind") == "handler_assertion" and item.get("tool_name") == tool_name]
+    decision = decisions[0] if len(decisions) == 1 else {}
+    assertion = assertions[0] if len(assertions) == 1 else {}
+    reasons = []
+    if timeout:
+        reasons.append("The customer test timed out")
+    elif test_exit != 0:
+        reasons.append("The customer test did not pass")
+    if len(decisions) != 1:
+        reasons.append("Expected exactly one SDK tool decision for this action")
+    elif not decision.get("live") or decision.get("direction") != "output":
+        reasons.append("The decision was not a live outbound tool decision")
+    elif not decision.get("hook_module"):
+        reasons.append("No certified SDK framework hook was observed; a direct client call is insufficient")
+    elif decision.get("verdict") != expected_verdict:
+        reasons.append("Observed verdict differs from the expected verdict")
+    if len(assertions) != 1 or assertion.get("calls") != expected_calls or len(attempts) != expected_calls:
+        reasons.append("The real-handler spy did not establish the expected execution count")
+    elif len(decisions) == 1:
+        decision_index = events.index(decision)
+        assertion_index = events.index(assertion)
+        if assertion_index <= decision_index or any(events.index(attempt) <= decision_index or events.index(attempt) >= assertion_index for attempt in attempts):
+            reasons.append("Handler evidence was not ordered after the policy decision and before the test assertion")
+    report = {
+        "schema": "agenticdome.action-path-proof.v1", "status": "passed" if not reasons else "incomplete",
+        "tool_name": tool_name, "expected_verdict": expected_verdict,
+        "observed_verdict": decision.get("verdict"),
+        "decision_id": decision.get("decision_id") or None,
+        "hook_module": decision.get("hook_module"), "hook_function": decision.get("hook_function"),
+        "expected_handler_calls": expected_calls,
+        "observed_handler_calls": len(attempts),
+        "handler_assertion_passed": bool(assertion) and assertion.get("calls") == expected_calls,
+        "customer_test_exit_code": test_exit, "timed_out": timeout,
+        "duration_ms": round((time.monotonic() - started) * 1000),
+        "observed_at": datetime.now(timezone.utc).isoformat(),
+        "reasons": reasons,
+        "next_action": (
+            "Run the same safe test command directly to inspect its logs, then check the selected hook and spy placement. No test output was retained."
+            if reasons else
+            "Review the corresponding retained sidecar decision and repeat with an allowed/blocked counterpart before promoting this route."
+        ),
+        "qualification": "The SDK hook and live verdict were observed locally. Handler execution is established by a customer-installed spy around the actual test handler; verify that this test exercises the production route. No business action is run by the CLI itself.",
+    }
+    report["proof_sha256"] = hashlib.sha256(
+        json.dumps(report, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+    return (0 if not reasons else 2), report
+
+
+def load_action_path_proof(root: Path) -> Optional[Dict[str, Any]]:
+    """Load a current, intact customer-run report without trusting free text."""
+    path = root / ".agenticdome" / "action-proof.json"
+    try:
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > 16384:
+            return None
+        report = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(report, dict) or report.get("schema") != "agenticdome.action-path-proof.v1":
+            return None
+        expected = str(report.get("proof_sha256") or "")
+        source = {key: value for key, value in report.items() if key != "proof_sha256"}
+        digest = hashlib.sha256(json.dumps(source, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
+        if digest != expected:
+            return None
+        observed_at = datetime.fromisoformat(str(report.get("observed_at") or ""))
+        age = datetime.now(timezone.utc) - observed_at.astimezone(timezone.utc)
+        if age.total_seconds() < -300 or age.total_seconds() > 7 * 86400:
+            return None
+        if report.get("status") != "passed" or report.get("hook_module") not in {
+            "agenticdome_sdk." + adapter for adapter in _ADAPTERS
+        }:
+            return None
+        if report.get("observed_verdict") not in {"ALLOWED", "BLOCKED", "REDACTED"}:
+            return None
+        if report.get("expected_handler_calls") not in {0, 1} or report.get("observed_handler_calls") != report.get("expected_handler_calls"):
+            return None
+        return {
+            "schema": "agenticdome.action-path-proof.v1", "status": "passed",
+            "tool_name": str(report.get("tool_name") or "")[:160],
+            "observed_verdict": report["observed_verdict"],
+            "decision_id": str(report.get("decision_id") or "")[:100] or None,
+            "hook_module": report["hook_module"],
+            "hook_function": str(report.get("hook_function") or "")[:100],
+            "observed_handler_calls": report["observed_handler_calls"],
+            "observed_at": report["observed_at"],
+            "proof_sha256": expected,
+            "evidence_origin": "customer_test",
+        }
+    except (OSError, ValueError, TypeError, OverflowError, json.JSONDecodeError):
+        return None
+
+
+__all__ = ["ExecutionSpy", "run_action_path_test", "record_policy_decision", "load_action_path_proof"]

agenticdome_sdk/catalog_snapshot.json

@@ -1,13 +1,13 @@
 {
     "schema": "agenticdome.catalog-snapshot.v1",
     "catalog_schema": "agenticdome.hook-catalog.v1",
-    "verified_at": "2026-09-26",
-    "python_sdk_version": "1.2.35",
+    "verified_at": "2026-09-29",
+    "python_sdk_version": "1.2.36",
     "published_packages": {
         "agenticdome-python-sdk": {
             "registry": "pypi",
-            "version": "1.2.35",
-            "url": "https://pypi.org/project/agenticdome-python-sdk/1.2.35/"
+            "version": "1.2.36",
+            "url": "https://pypi.org/project/agenticdome-python-sdk/1.2.36/"
         },
         "agenticdome-sdk": {
             "registry": "npm",

agenticdome_sdk/client.py

@@ -805,6 +805,12 @@ class AgenticDomeClient:
                 raise AgenticDomeError(
                     "AgenticDome execution broker did not return a verified, atomically consumed decision"
                 )
+        if tool_name and os.environ.get("AGENTICDOME_ACTION_PROOF_FILE"):
+            from .action_path_proof import record_policy_decision
+            record_policy_decision(
+                tool_name=tool_name, platform=platform, direction=normalized_direction,
+                response=response, live=not self.is_simulation,
+            )
         return response
 
     @staticmethod