[codex] Add tool governance middleware by Telli · Pull Request #105 · clawdotnet/openclaw.net

Telli · 2026-05-11T21:07:35Z

Summary

Adds an optional central tool-execution governance gate to OpenClaw.NET. Governance is enforced in the runtime tool executor instead of individual tools, with OpenClaw-owned abstractions and an AOT-safe HTTP sidecar adapter.

Changes

Adds governance config, models, decisions, descriptors, noop service, and HTTP sidecar service in OpenClaw.Core.
Wires governance through gateway composition and native/MAF runtime factory creation.
Runs governance in OpenClawToolExecutor after unknown-tool and preset checks, before approval, sandbox routing, and execution.
Merges require-approval decisions into the existing approval callback path, blocks denied calls, supports audit-only/allow/redaction behavior, and records governance metadata in traces/audit/session tool invocations.
Adds a central descriptor catalog for built-in/native tools plus fallback descriptors for dynamic/plugin tools.
Adds governance unit tests, docs, and Kubernetes sidecar deployment examples.

Validation

dotnet restore OpenClaw.Net.slnx
dotnet build OpenClaw.Net.slnx -c Debug --no-restore
dotnet test src/OpenClaw.Tests/OpenClaw.Tests.csproj -c Debug --no-build
dotnet test src/OpenClaw.Tests/OpenClaw.Tests.csproj -c Debug --no-build --filter FullyQualifiedName~ToolGovernanceTests
dotnet publish src/OpenClaw.Gateway/OpenClaw.Gateway.csproj -c Release -r osx-arm64 --self-contained true -o /tmp/openclaw-gateway-aot-governance
OpenClaw__Tooling__EnableBrowserTool=false /tmp/openclaw-gateway-aot-governance/OpenClaw.Gateway --doctor

AOT publish emitted macOS linker/module-cache warnings only; the published gateway doctor found no failed checks.

augmentcode · 2026-05-11T21:23:20Z

🤖 Augment PR Summary

Summary: This PR introduces an optional, centralized tool-governance gate for OpenClaw.NET, enforced in OpenClawToolExecutor and backed by a configurable HTTP sidecar adapter.

Changes:

Added governance configuration and models (actions, decisions, descriptors, audit payloads) in OpenClaw.Core.
Introduced IToolGovernanceService plus a no-op implementation and an AOT-safe HTTP sidecar implementation.
Wired governance through gateway composition and runtime factories (native + MAF adapters).
Integrated governance evaluation into tool execution flow: block/allow/require-approval/redact/audit-only, and attach metadata to traces and persisted tool invocations.
Added a built-in tool descriptor catalog (plus conservative fallback descriptors for unknown/plugin tools).
Added unit tests for sidecar allow/deny/require-approval flows and fail-open/fail-closed behavior.
Added docs and Kubernetes sidecar deployment examples for the governance pattern.

Technical Notes: Sidecar calls are time-bounded via cancellation tokens; on failure, behavior is controlled by FailClosed / FailOpenReadOnlyLowRisk and high-risk tool classification.

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-05-11T21:23:21Z

+
+        Read("profile_read", "profile", ["profile.read"]),
+        Write("profile_write", "profile", ToolGovernanceRiskLevel.Medium, ["profile.write"]),
+        Read("todo", "productivity", ["todo.read", "todo.write"]),


todo is registered via Read(...) (which sets ReadOnly=true and RiskLevel=Low) even though the tool supports mutating actions (add/update/complete/remove/clear); this can incorrectly treat it as “low-risk read-only” for fail-open behavior when the sidecar is unavailable. Other locations where this applies: src/OpenClaw.Core/Governance/ToolGovernanceDescriptorCatalog.cs:82, src/OpenClaw.Core/Governance/ToolGovernanceDescriptorCatalog.cs:95.

Severity: high

Other Locations

src/OpenClaw.Core/Governance/ToolGovernanceDescriptorCatalog.cs:82

src/OpenClaw.Core/Governance/ToolGovernanceDescriptorCatalog.cs:95

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-05-11T21:23:21Z

+                deniedByGovernance,
+                callId: callId,
+                resultStatus: ToolResultStatuses.Blocked,
+                failureCode: ToolFailureCodes.GovernanceDenied,


This path uses ToolFailureCodes.GovernanceDenied even when the underlying reason is sidecar timeout/unavailability (from BuildUnavailableDecision), which makes outages indistinguishable from policy denials. It looks like ToolFailureCodes.GovernanceUnavailable was added for this distinction but isn’t used here.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

Copilot

Pull request overview

Adds an optional, centralized tool-governance gate to OpenClaw.NET by introducing IToolGovernanceService and wiring it through gateway composition and both native/MAF runtime factories so governance decisions can allow/deny/require-approval/redact/audit tool calls from within OpenClawToolExecutor (including audit/trace enrichment).

Changes:

Introduces governance config + models, a built-in tool descriptor catalog, and two governance service implementations (noop + HTTP sidecar).
Wires governance through gateway composition and agent runtime factory creation (native + Microsoft Agent Framework).
Enriches tool invocations/audit entries with governance metadata; adds docs + K8s sidecar deployment example and unit tests.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/OpenClaw.Tests/ToolGovernanceTests.cs	Adds unit tests covering allow/deny/require-approval, timeout fail-closed/fail-open, and descriptor catalog coverage.
src/OpenClaw.MicrosoftAgentFrameworkAdapter/MafAgentRuntimeFactory.cs	Passes governance service through delegated and direct MAF runtime factory context/config.
src/OpenClaw.MicrosoftAgentFrameworkAdapter/MafAgentRuntime.cs	Wires governance into the runtime construction path.
src/OpenClaw.Gateway/Composition/RuntimeInitializationExtensions.RuntimeFactories.cs	Resolves `IToolGovernanceService` from DI and supplies it to agent runtimes.
src/OpenClaw.Gateway/Composition/CoreServicesExtensions.cs	Registers governance config and chooses/noops the governance provider; constructs HTTP sidecar adapter.
src/OpenClaw.Core/Observability/ToolAuditLog.cs	Extends audit entry schema with governance decision fields.
src/OpenClaw.Core/Models/ToolGovernanceModels.cs	Adds governance config, decision models, descriptors, and sidecar request/response payload types.
src/OpenClaw.Core/Models/Session.cs	Persists governance metadata on `ToolInvocation` and adds JSON source-gen registrations for new models.
src/OpenClaw.Core/Models/OperatorGovernanceModels.cs	Adds governance-related tool failure codes.
src/OpenClaw.Core/Models/GatewayConfig.cs	Adds `GatewayConfig.Governance` config section.
src/OpenClaw.Core/Governance/ToolGovernanceDescriptorCatalog.cs	Provides built-in tool descriptors and fallback descriptors for dynamic/plugin tools.
src/OpenClaw.Core/Governance/NoopToolGovernanceService.cs	Implements a default “allow” governance service when disabled/unconfigured.
src/OpenClaw.Core/Governance/HttpSidecarToolGovernanceService.cs	Implements AOT-safe HTTP sidecar decision + optional result-audit adapter.
src/OpenClaw.Core/Abstractions/IToolGovernanceService.cs	Introduces the governance boundary interface used by the runtime executor.
src/OpenClaw.Agent/OpenClawToolExecutor.cs	Executes governance checks centrally (pre-approval/sandbox/exec), applies decisions, and records governance audit/trace metadata.
src/OpenClaw.Agent/NativeAgentRuntimeFactory.cs	Passes governance service into the native runtime creation path.
src/OpenClaw.Agent/IAgentRuntimeFactory.cs	Extends factory context to carry an optional governance service instance.
src/OpenClaw.Agent/AgentRuntime.cs	Wires governance service into the tool executor used by the agent runtime.
docs/SITE_MAP.md	Adds docs entries for the new governance documentation pages.
docs/README.md	Links governance docs from the main documentation index.
docs/governance/sidecar-pattern.md	Documents sidecar flow, configuration, supported actions, and audit fields.
docs/governance/microsoft-agent-governance.md	Documents Microsoft Agent Governance integration approach and deployment cautions.
deploy/kubernetes/governance-sidecar/service.yaml	Adds example service manifest for the governance sidecar deployment pattern.
deploy/kubernetes/governance-sidecar/README.md	Adds deployment instructions and cautions for the sidecar example.
deploy/kubernetes/governance-sidecar/deployment.yaml	Adds example pod spec running OpenClaw.NET with a governance sidecar container.
deploy/kubernetes/governance-sidecar/configmap-policy.yaml	Adds an example policy ConfigMap for the governance sidecar.

+            var allowed = action == GovernanceAction.RequireApproval
+                ? true
+                : sidecar.Allowed ?? action is GovernanceAction.Allow or GovernanceAction.AuditOnly or GovernanceAction.Redact;


+
+        if (!Uri.TryCreate(config.SidecarBaseUrl, UriKind.Absolute, out var baseUri))
+            throw new InvalidOperationException("OpenClaw:Governance:SidecarBaseUrl must be an absolute URL when governance is enabled.");
+


+
+        if (!string.IsNullOrWhiteSpace(governanceDecision.RedactedArgumentsJson))
+        {
+            persistedArgsJson = _redaction.Redact(governanceDecision.RedactedArgumentsJson);


+                callId: callId,
+                resultStatus: ToolResultStatuses.Blocked,
+                failureCode: ToolFailureCodes.GovernanceDenied,
+                failureMessage: deniedByGovernance,
+                nextStep: "Adjust the request or governance policy before retrying.",


Add tool governance middleware

46de4d0

github-code-quality Bot found potential problems May 11, 2026

View reviewed changes

Comment thread src/OpenClaw.Tests/ToolGovernanceTests.cs Fixed

Comment thread src/OpenClaw.Core/Governance/HttpSidecarToolGovernanceService.cs Fixed

Telli marked this pull request as ready for review May 11, 2026 21:18

Copilot AI review requested due to automatic review settings May 11, 2026 21:18

Copilot started reviewing on behalf of Telli May 11, 2026 21:19 View session

augmentcode Bot reviewed May 11, 2026

View reviewed changes

Copilot AI reviewed May 11, 2026

View reviewed changes

Address governance review feedback

fee9e03

github-code-quality Bot found potential problems May 11, 2026

View reviewed changes

Comment thread src/OpenClaw.Tests/ToolGovernanceTests.cs Fixed

Fix governance test response helper

cf9067a

Telli mentioned this pull request May 11, 2026

The OpenClaw.NET process uses Microsoft.AgentGovernance #103

Open

Telli merged commit 028e6d8 into main May 11, 2026
17 checks passed

Telli deleted the codex/tool-governance-middleware branch May 11, 2026 22:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[codex] Add tool governance middleware#105

[codex] Add tool governance middleware#105
Telli merged 3 commits into
mainfrom
codex/tool-governance-middleware

Telli commented May 11, 2026

Uh oh!

Uh oh!

Uh oh!

augmentcode Bot commented May 11, 2026

Uh oh!

augmentcode Bot left a comment

Uh oh!

augmentcode Bot May 11, 2026 •

edited

Loading

Uh oh!

augmentcode Bot May 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		if (!Uri.TryCreate(config.SidecarBaseUrl, UriKind.Absolute, out var baseUri))
		throw new InvalidOperationException("OpenClaw:Governance:SidecarBaseUrl must be an absolute URL when governance is enabled.");

Conversation

Telli commented May 11, 2026

Summary

Changes

Validation

Uh oh!

Uh oh!

Uh oh!

augmentcode Bot commented May 11, 2026

Uh oh!

augmentcode Bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

augmentcode Bot May 11, 2026 •

edited

Loading

augmentcode Bot May 11, 2026 •

edited

Loading