#16064: feat: add contact-based tool permissions with verification
docs
gateway
docker
agents
size: XL
Cluster:
Tool and Plugin Enhancements
## Summary\n- Reworked contact-based tool permissions and execution hardening around group/direct behavior.\n- Added guards for missing tool command (prevents empty `exec` fallback paths).\n- Normalized content handling to avoid `Cannot read properties of undefined (reading "some")` in media/group fallback paths.\n- Ensured group chat tool errors are suppressed from fallback responses while preserving callback behavior for direct chats.\n- Added/updated regression tests for these flows.\n\n## Notes\n- Branch is up-to-date with openclaw/main and currently 1 commit ahead.\n- This replaces the closed PR #13551 state from an older head SHA; this PR carries the current branch tip.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR introduces a contact registry system (`contacts.entries` + `contacts.groups`) that enables group-based tool permission policies via `@groupname` references in `toolsBySender` configs. It also adds DM-context tool policies with channel-level identity verification gating, scoped exec command patterns (`exec:command*`), tool error fallback suppression for group chats, and defensive normalization for malformed tool result content.
- **Contact registry & groups**: New `contacts` config block with entries (phone-based) and groups. Groups are expanded in `toolsBySender` via `@groupname` syntax with first-match-wins precedence. Entry-level tools override group-level tools.
- **DM tool policies**: New `resolveChannelDMToolsPolicy` with `verified` flag — unverified channels (e.g., SMS) can only match wildcard policies, preventing identity spoofing from granting tool access.
- **Scoped exec**: `allow: ["exec:gog calendar*"]` restricts exec to specific command prefixes. Two-phase validation: passthrough at tool-list build time, enforcement at execution time via the wrapped exec tool.
- **Hardening**: `normalizeToolResultContent` prevents crashes from non-array/undefined tool result content. `normalizeContentBlocks` in model-scan handles malformed probe responses. Empty exec commands are now rejected before reaching the shell.
- **Group chat suppression**: `suppressToolErrorFallback` prevents tool error messages from being surfaced in group chats where they would be confusing.
- **Comprehensive tests**: 630+ lines of new tests covering contact resolution, DM policies, verification gating, scoped exec patterns, tool result normalization, and error suppression.
<h3>Confidence Score: 4/5</h3>
- This PR is well-structured with strong test coverage and correct security boundaries around identity verification and exec scoping.
- The core logic is sound: verification gating prevents spoofed identities from granting tool access, scoped exec uses two-phase validation, and defensive normalization prevents crashes. Tests cover the key scenarios. The style suggestions found are minor (duplicate function bodies, unnecessary branch). No critical logic bugs identified.
- Pay attention to `src/config/group-policy.ts` (core resolution logic) and `src/agents/pi-tools.policy.ts` (scoped exec and session key parsing) as these contain the security-critical policy evaluation paths.
<sub>Last reviewed commit: 56f7398</sub>
<!-- greptile_other_comments_section -->
<sub>(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#23582: fix(tool-policy): add group:fs and group:runtime to group:openclaw
by arosstale · 2026-02-22
78.9%
#16320: security: harden default tool policies and secure shell execution
by SuccessSoham · 2026-02-14
78.1%
#14222: core: add needsApproval to before_tool_call; move AgentShield to ex...
by Eventedge · 2026-02-11
78.0%
#19094: Fix empty tool_call_id and function names in provider transcript pa...
by yxshee · 2026-02-17
77.9%
#9511: feat: add tool error fallback toggle
by bolismauro · 2026-02-05
77.5%
#15050: fix: transcript corruption resilience — strip aborted tool_use bloc...
by yashchitneni · 2026-02-12
77.3%
#19632: fix: suppressToolErrors now suppresses exec tool failure notifications
by Gitjay11 · 2026-02-18
77.1%
#19399: telegram: fix MEDIA false positives and partial final drop
by HOYALIM · 2026-02-17
76.8%
#21195: fix: suppress orphaned tool_use/tool_result errors after session co...
by ruslansychov-git · 2026-02-19
76.6%
#23743: Auto-reply: enforce tools.allow/tools.deny on deterministic skill t...
by bmendonca3 · 2026-02-22
76.5%