#22835: feat: add tools.nodes.notifyOnExit config flag
gateway
size: S
Cluster:
Tool Execution and Error Handling
Add a new config option `tools.nodes.notifyOnExit` (default: true) that controls whether node exec events (`exec.started`, `exec.finished`, `exec.denied`) enqueue system events and trigger heartbeats.
When set to `false`, these events are silently dropped. This prevents duplicate notifications when the agent already received results inline from `nodes.run`.
## Problem
Node `exec.finished` events always enqueue a system event + request heartbeat via `server-node-events`, regardless of config. `tools.exec.notifyOnExit: false` exists for gateway-local exec but there was no equivalent for node events.
This causes duplicate token-burning notifications:
1. Agent calls `nodes.run` → gets result inline
2. Node sends `exec.finished` event → gateway enqueues system event
3. Agent responds to both, doubling token usage
## Changes
- **Config schema** (`zod-schema.agent-runtime.ts`): Added `tools.nodes` object with `notifyOnExit` boolean
- **Config types** (`types.tools.ts`): Added `nodes` type with JSDoc
- **Config labels** (`schema.labels.ts`): Added UI label
- **Config help** (`schema.help.ts`): Added help text
- **Event handler** (`server-node-events.ts`): Early return when flag is `false`
- **Tests** (`server-node-events.test.ts`): Added suppression test with mocked config
## Usage
```json
{
"tools": {
"nodes": {
"notifyOnExit": false
}
}
}
```
Fixes #22823
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds `tools.nodes.notifyOnExit` config flag to prevent duplicate notifications when node exec results are already received inline via `nodes.run`. Implementation correctly handles config schema, types, labels, help text, and event suppression logic in `server-node-events.ts`.
**Key changes:**
- Config flag defaults to `true` (preserves existing behavior)
- Early return in event handler when flag is `false` suppresses both system event enqueueing and heartbeat requests
- Test coverage validates the suppression behavior
**Minor improvements suggested:**
- Moving config check earlier would improve performance when notifications are disabled
- Test could verify both `enqueueSystemEvent` and `requestHeartbeatNow` suppression
- Test coverage could include all three event types (`exec.started`, `exec.finished`, `exec.denied`)
<h3>Confidence Score: 4/5</h3>
- Safe to merge with minor optimization opportunities
- Implementation is correct and well-tested. Config schema, types, and event handling logic are properly integrated. Suggested improvements are non-critical optimizations (earlier config check, enhanced test assertions) that don't affect correctness
- No files require special attention - all changes follow established patterns
<sub>Last reviewed commit: 7885803</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
#20209: fix(node): respect tools.exec.notifyOnExit for node exec events
by zerone0x · 2026-02-18
85.2%
#14395: feat: add gateway.nodes.execEvents config to control exec completio...
by dan3093 · 2026-02-12
84.2%
#18708: feat(messages): add suppressToolErrorWarnings config option
by codexGW · 2026-02-17
73.6%
#11300: feat(exec): make shell configurable via tools.exec.shell
by imjszhang · 2026-02-07
73.0%
#8464: feat: make exec approval timeout configurable
by fabioaraujopt · 2026-02-04
72.9%
#19632: fix: suppressToolErrors now suppresses exec tool failure notifications
by Gitjay11 · 2026-02-18
72.9%
#9511: feat: add tool error fallback toggle
by bolismauro · 2026-02-05
72.8%
#18934: fix(agents): suppress exec tool output from channel delivery
by BinHPdev · 2026-02-17
71.7%
#11854: fix: resolve per-agent tools.exec config in pi-tools
by Yida-Dev · 2026-02-08
71.7%
#7382: fix: remove config.schema from agent gateway tool
by kakuteki · 2026-02-02
71.7%