Summary

• Problem: The after_tool_call plugin hook fires twice per tool execution in embedded agent runs. Two independent code paths both dispatch the hook: pi-tool-definition-adapter.ts (the tool adapter wrapper) and handleToolExecutionEnd in pi-embedded-subscribe.handlers.tools.ts (the subscription event handler).
• Why it matters: Plugin authors observing after_tool_call see duplicate events for every tool call, forcing them to implement client-side deduplication workarounds (windowed hash maps, etc.). This is a correctness bug in the hook lifecycle.
• What changed: Removed the after_tool_call dispatch from pi-tool-definition-adapter.ts. The subscription handler (handleToolExecutionEnd) is now the single source of truth — it already has richer context (duration, sanitized result, session info). Added regression tests and an integration test that verifies the hook fires exactly once.
• What did NOT change (scope boundary): before_tool_call behavior is untouched (it was already deduplicated in PR fix(hooks): fire before_tool_call hook exactly once per tool invocation (#15502) #15635). The subscription handler dispatch logic is unchanged. consumeAdjustedParamsForToolCall cleanup remains in the adapter to prevent memory leaks from before_tool_call parameter tracking.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related: fix: dispatch before_tool_call and after_tool_call hooks from both tool execution paths #15012 (PR that introduced hooks in both paths)
• Related: fix(hooks): fire before_tool_call hook exactly once per tool invocation (#15502) #15635 (PR that deduplicated before_tool_call — this PR applies the same fix to after_tool_call)

User-visible / Behavior Changes

Plugins listening on after_tool_call will now receive exactly one event per tool execution instead of two. Plugins with deduplication workarounds will continue to work but the workarounds become unnecessary.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS 15 (darwin 24.6.0)
• Runtime/container: Node 22+, Bun
• Model/provider: Any (hook fires regardless of model)
• Integration/channel (if any): Any plugin using after_tool_call

Steps

1. Install a plugin that logs after_tool_call events
2. Run an embedded agent session (e.g. openclaw agent)
3. Trigger any tool execution (e.g. Read, Bash)

Expected

• Plugin receives exactly 1 after_tool_call event per tool execution

Actual (on main)

• Plugin receives 2 after_tool_call events per tool execution — one from the adapter wrapper, one from the subscription handler

Evidence

• Failing test/log before + passing after
• Trace/log snippets

New integration test (pi-tool-definition-adapter.after-tool-call.fires-once.test.ts): simulates the full embedded runtime flow (adapter execute + subscription handler event) and asserts toHaveBeenCalledTimes(1). This test was verified to fail with toHaveBeenCalledTimes(2) when the bug is reintroduced.

Regression guard test (pi-tool-definition-adapter.after-tool-call.test.ts): updated to assert the adapter does NOT call runAfterToolCall, confirming the hook dispatch was removed from the adapter.

Full test suite: 1417 test files, 11613 tests — all passing (pnpm build && pnpm check && pnpm test).

Human Verification (required)

• Verified scenarios:
  • Ran full test suite (11613 tests pass)
  • Ran the gateway on main with a plugin observing after_tool_call — confirmed 2 events fire per tool call
  • Ran the gateway on this branch with the same plugin — confirmed exactly 1 event fires per tool call
  • Verified the integration test correctly detects the bug: reverting the fix causes the test to fail with count=2
• Edge cases checked:
  • Tool execution errors (hook still fires once with error info via subscription handler)
  • Sequential tool calls (each fires exactly once, no cross-contamination)
  • consumeAdjustedParamsForToolCall cleanup still runs in the adapter to prevent leaks from before_tool_call parameter tracking
• What you did not verify:
  • Non-embedded (standalone CLI) runs — after_tool_call dispatch paths differ there and are not affected by this change

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Revert commit c129a1a74 — it re-adds the after_tool_call dispatch block to pi-tool-definition-adapter.ts
• Files/config to restore: src/agents/pi-tool-definition-adapter.ts
• Known bad symptoms reviewers should watch for: If after_tool_call stops firing entirely (zero times), it means the subscription handler path is not being reached — but that would also break before_tool_call which uses the same handler pattern

Risks and Mitigations

• Risk: The adapter was dispatching after_tool_call with the raw (unsanitized) tool result, while the subscription handler dispatches with the sanitized result. Plugins that depended on seeing the raw result will now only see the sanitized version.
  • Mitigation: The sanitized result is the correct one for plugins to consume (it strips sensitive/internal data). The raw result exposure was unintentional.

AI Disclosure: This PR was built with AI assistance (Cursor + Claude).

• Degree of testing: Fully tested — full test suite (11613 tests), new regression + integration tests, and manual end-to-end verification on both main (bug present) and fix branch (bug resolved).
• Code understanding confirmed: Yes. The root cause was traced through git history to PR fix: dispatch before_tool_call and after_tool_call hooks from both tool execution paths #15012 which added hooks to both tool execution paths. The before_tool_call half was already deduplicated in PR fix(hooks): fire before_tool_call hook exactly once per tool invocation (#15502) #15635; this PR completes the same fix for after_tool_call.

Made with Cursor