toolguard

Documentation

Overview

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* Package toolguard detects when the agent gets stuck repeatedly FAILING the * same tool, and produces targeted guidance to break the cycle. * * It complements the batch-level stagnation tracker (cli/agent_earlyexit.go), * which halts when an identical batch of tool calls repeats. That tracker is * order/arg-sensitive, so it misses two common failure modes this guard * catches: * * - the same tool failing turn after turn with slightly DIFFERENT args * (argument drift), which never produces an identical batch fingerprint; * - the same exact tool+args failing repeatedly within close succession. * * The guard is advisory by design: Observe() returns a guidance string the * caller injects into history so the model can self-correct. It never removes * or alters existing control flow — it only adds feedback. Hard-halt is * opt-in via Config.HaltAfterSameSig.

Index

• func Signature(tool, args string) string
• type Config
• type Decision
• type Guard
  • func New(cfg Config) *Guard
  • func (g *Guard) Observe(tool, args, errMsg string, failed bool) Decision

Functions

func Signature

func Signature(tool, args string) string

Signature builds a stable identity for a tool call: name plus whitespace-normalized args.

Types

type Config

type Config struct {
	// WarnAfterToolFailures is the number of consecutive failures of the
	// SAME tool (any args) before guidance is emitted. Default 3.
	WarnAfterToolFailures int
	// WarnAfterSameSig is the number of consecutive failures of the EXACT
	// same tool+args before stronger guidance is emitted. Default 2.
	WarnAfterSameSig int
	// HaltAfterSameSig, when > 0, makes Observe set Halt on the decision
	// once an identical tool+args has failed this many times. 0 disables
	// hard halt (advisory only). Default 0.
	HaltAfterSameSig int
}

Config tunes the thresholds. Zero value yields sane defaults via New.

type Decision

type Decision struct {
	// Guidance is non-empty when the model should be nudged to change
	// approach. The caller injects it into history.
	Guidance string
	// Halt is true only when Config.HaltAfterSameSig is set and reached.
	Halt bool
}

Decision is the result of observing a tool outcome.

type Guard

type Guard struct {
	// contains filtered or unexported fields
}

Guard tracks per-tool and per-signature consecutive failures for one agent run. It is safe for concurrent use (parallel sub-tool execution).

func New

func New(cfg Config) *Guard

New returns a Guard with the given config (defaults applied).

func (*Guard) Observe

func (g *Guard) Observe(tool, args, errMsg string, failed bool) Decision

Observe records the outcome of a single tool execution and returns a Decision. failed reports whether the call errored; errMsg is the error text (used to make guidance concrete). A successful call resets the failure streak for that tool.