tools

Documentation

Index

• type BehaviorPreset
  • func BehaviorPresetFrom(s string) (BehaviorPreset, error)
• type FinalizeConfigViolation
• type FinalizeErrorCode
  • func (c FinalizeErrorCode) String() string
• type FinalizeResult
  • func (r FinalizeResult) Ok() bool
• type ToolCall
• type ToolMeta
• type ToolNamespace
  • func ToolNamespaceFrom(s string) (ToolNamespace, error)
  • func (n ToolNamespace) String() string
• type ToolResult
• type VersionWarning

Types

type BehaviorPreset

type BehaviorPreset string

BehaviorPreset selects a back-compat behavior contract for tool execution. FinalizeToolConfigRequest.behavior_version carries one of these presets so a single locked configuration can keep older clients working without the server having to special-case version strings.

const (
	// BehaviorPresetUnspecified is the zero value; a finalize call SHOULD reject
	// it and require an explicit choice.
	BehaviorPresetUnspecified BehaviorPreset = ""
	// BehaviorPresetCurrent is the actively-supported behavior contract.
	BehaviorPresetCurrent BehaviorPreset = "current"
	// BehaviorPresetLegacy selects the prior behavior contract for back-compat
	// with clients that haven't adopted BehaviorPresetCurrent.
	BehaviorPresetLegacy BehaviorPreset = "legacy"
)

func BehaviorPresetFrom

func BehaviorPresetFrom(s string) (BehaviorPreset, error)

BehaviorPresetFrom parses a behavior_version string into a BehaviorPreset. Returns an error for any unrecognized value — an empty or unknown preset is invalid, not silently defaulted (matches the closed-enum forward-safety rule applied to ToolNamespace).

type FinalizeConfigViolation

type FinalizeConfigViolation struct {
	Code    FinalizeErrorCode `json:"code"`
	ToolID  string            `json:"tool_id"`
	Message string            `json:"message"`
}

FinalizeConfigViolation is a fatal, deterministic problem that prevents finalize from succeeding.

type FinalizeErrorCode

type FinalizeErrorCode int

FinalizeErrorCode classifies a finalize warning or violation, mirroring the FINALIZE_ERROR_CODE enum in proto/hawk/contracts/v1/tool.proto.

const (
	FinalizeErrorCodeUnspecified         FinalizeErrorCode = iota // unspecified
	FinalizeErrorCodeUnknownTool                                  // unknown tool id
	FinalizeErrorCodeIncompatibleVersion                          // behavior_version incompatible with enabled_tools
	FinalizeErrorCodeDeprecatedReplaced                           // tool deprecated/replaced
	FinalizeErrorCodeInvalidParams                                // invalid tool parameters
)

func (FinalizeErrorCode) String

func (c FinalizeErrorCode) String() string

type FinalizeResult

type FinalizeResult struct {
	BehaviorVersion string                    `json:"behavior_version"`
	Warnings        []VersionWarning          `json:"warnings,omitempty"`
	Violations      []FinalizeConfigViolation `json:"violations,omitempty"`
	Finalized       bool                      `json:"finalized"`
}

FinalizeResult is the decoded outcome of a FinalizeToolConfig call.

func (FinalizeResult) Ok

func (r FinalizeResult) Ok() bool

Ok reports whether finalize succeeded and the tool set is safe to call: Finalized must be true AND there must be no fatal violations. Warnings alone do not make Ok return false.

type ToolCall

type ToolCall struct {
	ID        string                 `json:"id,omitempty"`
	Name      string                 `json:"name"`
	Arguments map[string]interface{} `json:"arguments"`
}

ToolCall represents a provider-neutral tool invocation contract.

type ToolMeta

type ToolMeta struct {
	Version   string        `json:"version"`
	Name      string        `json:"name"`
	Kind      string        `json:"kind"`
	Namespace ToolNamespace `json:"namespace"`
	Label     string        `json:"label,omitempty"`
	ReadOnly  bool          `json:"read_only"`
}

ToolMeta is the canonical identity envelope attached to tool-call events, mirroring the ToolMeta message in proto/hawk/contracts/v1/tool.proto. version is an additive-only bump: new additive fields do NOT change it.

type ToolNamespace

type ToolNamespace string

ToolNamespace is a CLOSED enum identifying the harness that owns a tool, mirroring the ToolNamespace enum in proto/hawk/contracts/v1/tool.proto. A new unknown namespace is a wire-breaking change that intentionally fails ToolNamespaceFrom (forward-safety): a deploy that rolls the contract forward before the consumer code cannot silently mis-route a tool it doesn't understand. ToolNamespaceAcp is reserved for the forthcoming hawk-acp repo.

const (
	ToolNamespaceUnspecified      ToolNamespace = ""           // unspecified
	ToolNamespaceHawkBuild        ToolNamespace = "hawk_build" // hawk
	ToolNamespaceHawkBuildConcise ToolNamespace = "hawk_build_concise"
	ToolNamespaceCodex            ToolNamespace = "codex"    // codex harness
	ToolNamespaceOpencode         ToolNamespace = "opencode" // opencode harness
	ToolNamespaceMcp              ToolNamespace = "mcp"      // MCP servers (falcon)
	ToolNamespaceAcp              ToolNamespace = "acp"      // reserved: hawk-acp
)

func ToolNamespaceFrom

func ToolNamespaceFrom(s string) (ToolNamespace, error)

ToolNamespaceFrom parses a namespace string into a ToolNamespace. The set is closed: an unrecognized value returns an error rather than silently mapping to ToolNamespaceUnspecified, so a new namespace on the wire fails strict typed deserialization (see the closed-enum forward-safety rule above).

func (ToolNamespace) String

func (n ToolNamespace) String() string

String returns the namespace string as-is, mapping the unspecified zero value to "unspecified" so log output and JSON stay unambiguous.

type ToolResult

type ToolResult struct {
	ToolUseID string `json:"tool_use_id"`
	Content   string `json:"content"`
	IsError   bool   `json:"is_error,omitempty"`
}

ToolResult represents a provider-neutral tool execution result contract.

type VersionWarning

type VersionWarning struct {
	Code          FinalizeErrorCode `json:"code"`
	Message       string            `json:"message"`
	AffectedTools []string          `json:"affected_tools,omitempty"`
}

VersionWarning is a non-fatal, behavior-version drift reported by finalize.