Documentation
¶
Overview ¶
Package builtins contains the stock in-process hook implementations shipped with docker-agent.
Available builtins:
- add_date (turn_start) — today's date
- add_environment_info (session_start) — cwd, git, OS, arch
- add_prompt_files (turn_start) — contents of prompt files
- add_git_status (turn_start) — `git status --short --branch`
- add_git_diff (turn_start) — `git diff --stat` (or full)
- add_directory_listing (session_start) — top-level entries of cwd
- add_user_info (session_start) — current OS user and host
- add_recent_commits (session_start) — `git log --oneline -n N`
- max_iterations (before_llm_call) — hard stop after N model calls
- snapshot (session_start, turn_start, turn_end, pre_tool_use, post_tool_use, session_end) — shadow-git snapshots
- redact_secrets (pre_tool_use, before_llm_call, tool_response_transform) — scrub secrets from tool args, outgoing chat content, and tool output. Same builtin, dispatches on event so a single name covers all three legs of the feature.
Reference any of them from a hook YAML entry as `{type: builtin, command: "<name>"}`. The runtime additionally auto-injects add_date / add_environment_info / add_prompt_files / redact_secrets from the matching agent flags, and snapshot from global user config. Setting redact_secrets at the agent level is exactly equivalent to writing the three matching hook entries by hand — ApplyAgentDefaults performs the auto-injection.
turn_start builtins recompute every turn (date, git state). session_start builtins run once per session for context that's stable for its duration. max_iterations is stateful: its per-session counter lives on the State returned by Register; the runtime clears it via State.ClearSession from session_end. snapshot is also stateful: it keeps per-session turn/tool snapshot hashes and undo checkpoints in memory while the shadow git objects live under the data directory. Undo checkpoints intentionally survive the RunStream session_end cleanup so /undo can run after the response stops.
LLM-as-a-judge hooks are NOT shipped here: write `type: model` with `schema: pre_tool_use_decision` instead — see pkg/hooks/shape_pre_tool_use_decision.go and examples/llm_judge.yaml.
Index ¶
Constants ¶
const AddDate = "add_date"
AddDate is the registered name of the add_date builtin.
const AddDirectoryListing = "add_directory_listing"
AddDirectoryListing is the registered name of the add_directory_listing builtin.
const AddEnvironmentInfo = "add_environment_info"
AddEnvironmentInfo is the registered name of the add_environment_info builtin.
const AddGitDiff = "add_git_diff"
AddGitDiff is the registered name of the add_git_diff builtin.
const AddGitStatus = "add_git_status"
AddGitStatus is the registered name of the add_git_status builtin.
const AddPromptFiles = "add_prompt_files"
AddPromptFiles is the registered name of the add_prompt_files builtin.
const AddRecentCommits = "add_recent_commits"
AddRecentCommits is the registered name of the add_recent_commits builtin.
const AddUserInfo = "add_user_info"
AddUserInfo is the registered name of the add_user_info builtin.
const MaxIterations = "max_iterations"
MaxIterations is the registered name of the max_iterations builtin.
const RedactSecrets = "redact_secrets"
RedactSecrets is the registered name of the builtin that scrubs secret material at every leak vector docker-agent has into a third party. The same builtin is registered once and dispatches on hooks.Input.HookEventName so a single name covers all three legs:
- hooks.EventPreToolUse — scrub tool ARGUMENTS before the call leaves the runtime (returns UpdatedInput).
- hooks.EventBeforeLLMCall — scrub outgoing CHAT CONTENT before each model call (returns UpdatedMessages).
- hooks.EventToolResponseTransform — scrub tool OUTPUT before it reaches event consumers, the persisted session, the post_tool_use hook, or the next LLM call (returns UpdatedToolResponse).
The agent-level redact_secrets flag is shorthand for wiring the builtin into all three events at once via ApplyAgentDefaults; the same hook entries can be authored directly in YAML to opt in to individual legs (or all of them) without touching agent flags.
Configured under any other event the builtin returns nil and logs a warning: keeping it lenient avoids surprising failures from typos while still nudging users toward the right event.
const Snapshot = "snapshot"
Snapshot is the registered name of the snapshot builtin.
Variables ¶
This section is empty.
Functions ¶
func ApplyAgentDefaults ¶
func ApplyAgentDefaults(cfg *hooks.Config, d AgentDefaults) *hooks.Config
ApplyAgentDefaults appends the stock builtin hook entries implied by d to cfg. A nil cfg is treated as empty. Returns nil iff no hook (user-configured or auto-injected) is present.
Types ¶
type AgentDefaults ¶
type AgentDefaults struct {
AddDate bool
AddEnvironmentInfo bool
AddPromptFiles []string
// RedactSecrets auto-injects the redact_secrets builtin under
// pre_tool_use, before_llm_call, and tool_response_transform — the
// three legs of the feature. Equivalent to writing those three
// hook entries by hand; the dedup in [hooks.Executor.hooksFor]
// makes the auto-injection idempotent against an explicit YAML
// entry that already names the same builtin.
RedactSecrets bool
// Snapshot auto-injects shadow-git snapshots at
// turn boundaries. session_end is included to garbage-collect the
// shadow repository; undo history remains available after a response stops.
Snapshot bool
}
AgentDefaults captures defaults that map onto stock builtin hook entries. Pass each AgentConfig.AddXxx flag as-is; Snapshot comes from runtime/global config.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State holds the per-runtime state of the stateful builtins. It is returned by Register so callers can clear per-session entries on session_end. Stateless builtins don't appear here.
func Register ¶
Register installs the stock builtin hooks on r and returns a State handle the caller can use for stateful builtin operations.
func (*State) ClearSession ¶
ClearSession drops per-RunStream state that should not survive stream teardown. A nil receiver is a no-op.
Source Files