
agent-callable
PreToolUse hook — validates Bash commands through agent-callable deny-by-default policy before execution
- version
- 0.17.0
- GitHub stars
- 5
Install
/plugin install agent-callable@agent-callableRun it inside Claude Code after adding the marketplace with /plugin marketplace add Evaneos/agent-callable.
Contents
Discovered from sourceSkills 1
agent-callable — configuration helper
Quick reference
Config dir: ~/.config/agent-callable/
Global config: ~/.config/agent-callable/config.toml
Tool configs: ~/.config/agent-callable/tools.d/*.toml
agent-callable --list-tools # registered tools (built-in + config)
agent-callable --help-config # full TOML format documentation
agent-callable --audit <tool> [args] # dry-run: would this command be allowed?
agent-callable --audit --sh '<expr>' # dry-run for shell expressions (pipes, &&)
agent-callable --init-config # interactive: generate default configs
Built-in tools
docker, gcloud, gh, git, kubectl, npm, pulumi (+ wrappers: nice, timeout, xargs).
Builtins have richer logic (flag inspection, secret filtering, auto-injected env). They are toggled in config.toml:
[builtins]
kubectl = true
git = true
TOML config format (tools.d/)
All args allowed:
[mytool]
allowed = ["*"]
Subcommand allowlist:
[systemctl]
allowed = ["is-active", "is-enabled", "list-units", "status"]
Write-safety (only checks destination when a write flag is present):
[sed]
allowed = ["*"]
write_flags = ["-i", "--in-place"]
write_target = "last"
flags_with_value = ["-e", "-f", "--expression", "--file"]
Nested subcommands:
[nmcli]
allowed = ["g", "general", "c", "connection"]
flags_with_value = ["-f", "--fields"]
[nmcli.subcommands]
g = ["status", "hostname"]
general = ["status", "hostname"]
Environment overrides:
[git]
allowed = ["status", "log", "diff"]
[git.env]
GIT_TERMINAL_PROMPT = "0"
Fields reference
mode—"replace"(default) or"extend". See Extend mode below.allowed(required for replace) —["*"]for unrestricted, or["sub1", "sub2"]for allowlistflags_with_value— flags that consume the next arg (prevents confusing a flag value with a subcommand)write_target— destination args checked againstwritable_dirs."last"(cp, mv, sed -i),"all"(mkdir, touch, tee), or"after_first"(xxd in [out]: first positional is read-only input, rest are destinations)write_flags— only enforcewrite_targetwhen one of these flags is present (e.g.-ifor sed)denied_flags— block execution outright when any listed flag appears in args, regardless ofallowed = ["*"]. Exact match (no short-flag prefix). Used to carve out dangerous knobs likefind -exec/-deleteorcurl -Ostrip_version_suffix— strip a trailing@version(npm package-spec syntax, e.g.prettier@3) from the first token before matchingallowed. Leaves a scoped package's own leading@alone, and leaves the whole token untouched (so it fails the allowlist match) when the part after@contains:or/— that's an npm alias/file/git-URL reference, not a version, and stripping it would let an arbitrary package run under an allowed name[tool.env]— env vars applied when the command is allowed[tool.subcommands]— second-level subcommand allowlists (keys must be a subset ofallowed)
Extend mode (extending builtins)
Builtins (git, kubectl, gh, docker, npm, pulumi, gcloud) have rich Go logic — flag inspection, secret filtering, actionable deny messages. A plain TOML config for the same tool name would replace the builtin entirely, losing all that logic.
mode = "extend" solves this: the builtin runs first. If it allows, done. If it denies, the TOML fallback is consulted. This is a "sandwich" — keep the builtin's safety net, add specific exceptions via TOML.
# Allow git push (builtin blocks it) without losing git's other protections:
[git]
mode = "extend"
allowed = ["push"]
# Allow gh pr create while keeping gh's api write-method detection:
[gh]
mode = "extend"
allowed = ["pr"]
[gh.subcommands]
pr = ["create"]
# Allow kubectl apply for a specific workflow:
[kubectl]
mode = "extend"
allowed = ["apply"]
When to use extend vs replace:
- The tool is a builtin and you want to unlock specific subcommands →
extend - The tool is a builtin and you want full control over its policy →
replace(you lose the builtin logic) - The tool is not a builtin (config-only) →
replace(default, extend would warn)
When unsure: ask the user. Typical question: "git push est bloqué par le builtin. Voulez-vous l'autoriser via extend (conserve la logique de sécurité git pour le reste) ou remplacer le builtin entièrement ?"
Global config (config.toml)
writable_dirs = ["/tmp"]
allow_on_any = ["--version", "--help"] # universal short-circuit: these flags are allowed on ANY tool (registered or not)
[audit]
file = "~/.local/share/agent-callable/audit.log"
mode = "blocked" # "none" | "blocked" | "allowed" | "all"
max_entries = 10000 # ignored when daily_files = true
daily_files = false # one file per day (audit-YYYY-MM-DD.log), kept until removed
mask_secrets = true
[builtins]
# git = true
# kubectl = true
Workflow: add a new tool
agent-callable --list-tools— check if already registered- If it shows
[built-in]and you need to unlock specific subcommands → use extend mode - If it shows
[config]→ edit the existing TOML - If not listed → create new TOML config
- If it shows
- Research the tool's CLI surface before writing config:
- Use context7 MCP (
resolve-library-idthenquery-docs) if available - Otherwise
<tool> --helpand web search for the official docs - Identify: all subcommands (including aliases), dangerous operations (write/delete/push/apply), flags that take a value argument
- This step matters — CLIs have flags and subcommands you don't expect, and missing a
flags_with_valueentry causes subtle parsing bugs
- Use context7 MCP (
- Create or edit a
.tomlin~/.config/agent-callable/tools.d/ - Verify:
agent-callable --audit <tool> <expected-args>(should pass) - Verify:
agent-callable --audit <tool> <dangerous-args>(should block)
Workflow: command unexpectedly blocked
agent-callable --audit <tool> <args>— shows the deny reasonagent-callable --audit --sh '<full expression>'— for pipes/shellagent-callable --list-tools | grep <tool>— is the tool registered?- If missing → research the tool's docs (context7 MCP or web), then add TOML config
- If
[built-in]and a specific subcommand is blocked → usemode = "extend"to add it as a TOML fallback (keeps the builtin's safety logic for everything else) - If
[config]but wrong → edit the relevant.tomlintools.d/ - Ask the user before extending a builtin — extending unlocks a command the builtin intentionally blocks (e.g.
git push,kubectl apply). Confirm this is desired.
Installation (if binary not found)
which agent-callable || {
gh release download --repo Evaneos/agent-callable --pattern '*_linux_amd64.tar.gz' -D /tmp
tar xzf /tmp/agent-callable_*_linux_amd64.tar.gz -C /tmp
echo "Move /tmp/agent-callable to a directory in your PATH"
}
agent-callable --init-config # generate default configs
Design principles for writing configs
- Deny-by-default: if not explicitly allowed, it's blocked. Prefer blocking too much over too little.
- Read the tool's
--helpbefore writing a config — CLIs have flags you don't expect. - Use
write_target/write_flagsfor any tool that can write files (sed -i, eslint --fix, gofmt -w). - Declare
flags_with_valueso the parser doesn't confuse flag values with subcommands.
Hooks 1
Sponsors
Details
- Marketplace
- Evaneos/agent-callable
- Source
- plugins/agent-callable
- Author
- Platform Team
- Category
- Community