Skip to content

Event guards ​

These events fire on a round count, a truncation size, a call budget, or a memory cap. The two token events, auto-compact and fold, stay on Reactive LLM events.

Round-count events ​

The same {name, on, run} shape covers the stuck-loop and task-budget guards. They fire on a count of rounds, not tokens, so on: uses rounds::

yaml
# ~/.kdeps/events/identical-tool-calls.yaml
name: identical-tool-calls
on:
  rounds: 3   # how many times in a row the model may issue the exact same tool call
run: force_answer
EventFires afterAction
identical-tool-callsthe model issues the exact same tool call and gets the exact same result this many times in a row. Tools with a per-turn budget (web, bash, file, code) ignore this number and use their budget event insteadends the turn as a stuck loop
convergence-blockthis many consecutive rounds end in a convergence-blocked tool call (the model kept trying once a web/bash/file/code budget ran out)strips every tool and forces a text answer
judge-max-roundsa single judge's review spends this many tool roundsends that judge's review and forces its verdict
agent-max-roundsan agent-loop turn spends this many tool rounds (200) when the loop sets no round capforces a text answer
chat-max-roundsa workflow chat with no tools.maxRounds (or auto) spends this many tool rounds (25)forces a text answer
chat-retriesa workflow chat's model call fails with a transient error (rate limit, 5xx, dropped connection)retries this many times (3) with doubling backoff; model.retries overrides
subagent-max-roundsone subagent task spends this many tool rounds (20)ends the subagent and forces its report
judge-iterationsthe revise-and-rejudge loop retries this many times after a judge rejectionaccepts the last response regardless of outcome -- a judge panel must never block a turn indefinitely

A sensible floor of 1 ​

Each has a built-in floor of 1. An override with no rounds:, or a corrupted override, never becomes 0. A value of 0 starts the event on the first round.

Truncation events ​

The same shape covers the loop's token-economy limits -- these fire on a measured byte length, so their on: clause uses bytes: instead:

yaml
# ~/.kdeps/events/tool-result-truncate.yaml
name: tool-result-truncate
on:
  bytes: 8192   # any single tool result past this size keeps its start and end
run: truncate
EventFires whenAction
tool-result-truncatea single tool result fed back to the LLM exceeds this sizekeeps its start and end on line boundaries, marks the cut
tool-error-truncatea tool's failure text exceeds this sizetruncates before display and before feeding it back to the LLM
force-answer-digestthe gathered-output digest inlined into a forced answer exceeds this sizetruncates the digest
history-window-trimthe in-flight tool-loop message array exceeds this sizedrops the oldest complete tool round-trips
history-window-old-resulta tool result older than the two most recent steps of the turn exceeds this sizecuts it to its start, notes how much was dropped
file-read-limita file a builtin tool is about to read (or write_file's own content) exceeds this sizerejects the call with an error instead of reading/writing it

Each also falls back to its built-in default if the registry is unavailable. An override that omits bytes: never means "truncate to nothing" or "reject every file".

Call-budget events ​

The four built-in call budgets are events whose tools: list names the tools they count. They fire on a distinct-call count per turn, so their on: clause uses distinctCalls:. A repeat call with the same arguments never counts twice and reuses the earlier answer.

yaml
# ~/.kdeps/events/web-call-budget.yaml - replaces the shipped event outright
name: web-call-budget
tools: [web_search, wikipedia, web_scraper, exa_search, wolfram_alpha]  # add or remove a tool here
on:
  distinctCalls: 20   # DISTINCT calls to the tools above this turn -- they share one budget
run: block
EventCounts (shipped tools: list)Default
web-call-budgetweb_search, wikipedia, web_scraper, exa_search, wolfram_alpha20
bash-call-budgetbash_exec commands50
file-call-budgetread_file windows (path plus offset/limit) and list_files paths80
code-call-budgetsearch_local queries30

If you remove a tool from a list, the tool runs with no budget and does not use earlier answers again. If you add a tool to a list, kdeps counts it by its arguments. These four events must keep a tools: list. kdeps rejects an override file without this list when it loads. The shipped event then stays active.

The system prompt states the enforced limit. Identical repeated calls (same call, same result) stop after as many rounds as the tool's budget. Tools without a budget use the identical-tool-calls threshold.

Workflow chats read the same events: each chat call counts its own distinct calls, and a repeated call reuses its first result (see tool loop behavior).

Your own tool budgets ​

An event with a tools: list is a budget defined only in YAML. In one turn, the model can make a maximum of on.distinctCalls different calls to those tools. A repeated call does not count again. After the limit, kdeps blocks a new call, as for the built-in budgets. The model then answers with the data that it has.

yaml
# ~/.kdeps/events/search-budget.yaml - loaded at start, no registry entry needed
name: search-budget
tools: [web_search, web_scraper, wikipedia]   # the tools this budget counts together
on:
  distinctCalls: 6      # at most 6 distinct calls to these tools per turn
run: block              # the only action a tools: event takes

disabled: true turns it off like any other event. kdeps rejects a tools: event without on.distinctCalls or with a different run: when it loads.

Memory events ​

The persistent memory injection and traversal caps are events too. memory-prompt-limit fires on a token measurement like auto-compact and fold. The rest are plain counts that always apply, so they set items: instead of on::

yaml
# ~/.kdeps/events/memory-focus-max.yaml
name: memory-focus-max
items: 5   # how many prompt-relevant entries are force-kept when memory is truncated
run: cap
EventCapsDefault
memory-prompt-limittokens of memory content injected into the system preamble each turn500
memory-keys-limitkey names listed in the <memory-keys> preamble block25
memory-focus-maxprompt-relevant entries force-kept when memory is truncated5
memory-chain-maxentries the active task chain force-keeps (its nearest ancestors)8
rel-memory-limitbase memory rows fed into a memory_query join, bounding its worst case500
memory-search-limitmatches memory_search shows (best first; the rest are counted)20
memory-value-limit (on: bytes)bytes of one value memory_search shows, and of a summary section captured into memory500
memory-capture-limit (on: bytes)bytes of a tool result or thinking text captured into memory automatically300
memory-tool-results-limitautomatic captures kept per tool (oldest dropped)20
memory-thinking-limitreasoning (thinking) entries kept (oldest dropped)20
memory-low-signal-limitentries of the low-signal types (low_signal: in memory rules) kept (oldest dropped)50
memory-status-limittool-call status entries (status:<tool>:<n>) kept (oldest dropped)60
memory-key-chars (on: bytes)characters of a memory key, and of a memory note's file name made from it80
memory-tool-line-chars (on: bytes)characters of a tool result's first line used to name its entry40
memory-derived-key-chars (on: bytes)characters of a key made from a tool name and its result30
memory-summary-chars (on: bytes)characters of a memory note's summary line (longer is cut with ...)120
memory-focus-min-wordthe shortest prompt word that counts when the prompt is matched to memory3
memory-format-tokenstokens of memory put in a prompt when the caller sets no budget2000
memory-query-rows-maxrows memory_query returns for a relation, for all limit values (keeps the result under the tool result cap)500

Two agent loop budgets are events of the same kind, read only when the config leaves them unset:

EventWhat it capsDefault
tool-allocation-incrementtool rounds added each time auto tool allocation raises the budget100
preamble-token-limittokens of the system preamble kept when neither the compact token budget nor the auto-compact threshold is set40000
yaml
# ~/.kdeps/events/memory-value-limit.yaml
name: memory-value-limit
on:
  bytes: 1000   # memory_search shows up to 1000 bytes of each value, then "..."
run: truncate

Thinking budgets ​

Each thinking mode's reasoning token budget is an event: thinking-budget-<mode>, an items: count. The model can use a maximum of that number of tokens to reason before it answers. Models that do not reason ignore it. A workflow chat's thinking: mode with no budgetTokens uses the same event. A missing or disabled budget event uses 10000.

Eventthinking: modeDefault
thinking-budget-minimalminimal512
thinking-budget-lowlow2048
thinking-budget-mediummedium8192
thinking-budget-highhigh16000
thinking-budget-xhighxhigh32000
thinking-budget-autoauto (the default mode)10000
yaml
# ~/.kdeps/events/thinking-budget-high.yaml
name: thinking-budget-high
items: 24000   # thinking: high lets the model reason for up to 24000 tokens
run: cap

kdeps has the Apache 2.0 License.