Skip to content

Permissions

The permission gate is the central chokepoint consulted before every tool call. It enforces three things in order:

  1. A built-in bash denylist — best-effort defense-in-depth, not a security boundary (see below). It catches the laziest rm -rf /-class mistakes even in yolo mode, but is trivially evadable.
  2. A path scope check for file tools — out-of-scope reads/writes either prompt the user or fail.
  3. The mode + allow/deny patterns from .agents/config.json.

ModeBehavior
ask (default)Allowlisted calls pass automatically; everything else prompts the user via the configured Prompter. With no Prompter, prompts fail closed with a clear error.
autoask with an approver model in front of the person. Outward-facing calls such as git push or gh pr create are allowed only when your own message asks for or permits them (“commit and push the branch”, “you have my permission to create the PR”). A destructive call such as a force-push is never allowed outright: it comes back to you if you explicitly asked for it, and is denied otherwise (#1175). For calls on its permissions.auto.eligible list (or eligible_bundles), the approver may allow the call once, deny it, or pass it to the person’s ordinary prompt with its reason quoted. Everything else, and anything the approver passes on, prompts as in ask, unless permissions.auto.escalation is refuse: then it is refused at once, and the agent is told why, for example that a piped or chained command never matches an eligible pattern. Needs permissions.auto and permissions.approval_timeout. See Configuration → permissions.auto.
allowOnly allowlisted calls pass. Everything else is rejected without prompting — useful for headless / automated runs.
yoloAll in-scope calls pass except those caught by the bash denylist, a deny-pattern, or the default-on workspace write sandbox (safety.sandbox, see below). Use with care; intended for trusted local dev.
planAll tool execution is disabled — read-and-think sessions. The TUI’s permission chip cycles out of it (Shift+Tab).
acceptEditsFile writes inside the workspace scope (or path_scope / safety.sandbox.writable_paths) auto-allow without prompting; out-of-scope and protected host credential/startup paths are refused by default unless --no-sandbox (safety.sandbox.mode: "off") is set. Bash and every other tool kind still prompt as in ask. Used by the TUI’s “acceptEdits” chip to stream a refactor without a diff modal per file.

In mode auto, the approver decides only the calls permissions.auto.eligible list (or eligible_bundles)s. permissions.auto.eligible_bundles adds named presets to that list (#1252):

BundlePatterns it makes eligible
codingwrite_file:*, edit_file:*, bash:go test, bash:go test *, bash:go vet, bash:go vet *, bash:go build, bash:go build *, bash:go mod tidy, bash:gofmt *, bash:make test, bash:make build, bash:make lint, bash:npm test, bash:npm run build, bash:npm run lint, bash:pytest, bash:pytest *, bash:cargo test, bash:cargo test *, bash:cargo build, bash:cargo build *, bash:git add *, bash:git commit *, bash:git checkout -b *, bash:git switch -c *
githubbash:git push *, bash:gh pr create, bash:gh pr create *, bash:gh pr view *, bash:gh pr list, bash:gh pr list *, bash:gh pr checks *, bash:gh pr comment *, bash:gh issue create, bash:gh issue create *, bash:gh issue view *, bash:gh issue list, bash:gh issue list *, bash:gh issue comment *
k8s_readbash:kubectl get *, bash:kubectl describe *, bash:kubectl logs *, bash:kubectl top *, bash:kubectl explain *, bash:kubectl api-resources, bash:kubectl api-resources *, bash:kubectl version, bash:kubectl version *, bash:kubectl auth can-i *, bash:kubectl config current-context

What a bundle does and doesn’t do:

  • It makes calls eligible; it allows nothing. The approver still judges each call against your request. It’s the only check on an eligible call: it sees the whole command line, so flags like git commit --amend or go test -exec are in front of it, but it never sees the code a test or build runs.
  • Prefix patterns never match a chained, piped or redirected command, and never one that starts with an environment assignment (CGO_ENABLED=0 go build). Those go to a person.
  • coding runs code from the workspace. Its test and build commands execute code the agent may have written, and some fetch from the network. The repository and container boundary contain that, not the list.
  • k8s_read can read Secret data (kubectl get secret -o yaml, kubectl get --raw …); the approver judges whether your request needs it.
  • github reaches outside the workspace. The approver allows a call only when your own words ask for or permit it, and never a force-push or a branch deletion, which git push * also matches. Merging is in no bundle.

No mode — not even yolo or acceptEdits — auto-approves a write to a control-plane file (see below).

The mode can change while a session runs. In the TUI, Shift+Tab cycles ask → auto → acceptEdits → plan → yolo; auto is in the cycle only for a session that can enter it, meaning one with an approver configured and approval_timeout set. An attached core-agent-tui has the same chip, and it is backed by POST /perms/mode, which only the session owner or a daemon admin may call. Either way, on a session with a durable eventlog, each change writes an attach-perm-mode row. allow isn’t on the chip; it is set in config only, and a session moved out of it can’t be moved back without a restart. A restarted session comes back in its configured mode.

Set via .agents/config.json:

{
"permissions": {
"mode": "ask",
"allow": ["bash:git status", "bash:git log*"],
"deny": ["bash:sudo *"]
}
}

Or programmatically when constructing the gate:

gate := permissions.New(permissions.Options{
Mode: permissions.ModeAllow,
Policy: policy,
Scope: scope,
Prompter: nil, // headless
})

Patterns appear in permissions.allow and permissions.deny. Two forms:

<tool>:<glob> applies only when the request is for <tool>
<glob> applies to any tool (matched against the request key)

The <glob> uses path/filepath.Match semantics, so it understands *, ?, and character classes. Two convenience extensions:

  • Exact match comes first: a pattern with no wildcards matches the literal key only (so bash:git status matches the literal command, not git statusabc).
  • Open prefix for trailing *: bash:git diff* matches git diff, git diff main..HEAD, etc.

For bash, an open-prefix allow rule only auto-allows a command that is exactly one simple command with a fully literal argv. The command string is parsed with a real shell parser; any of the following disqualifies it from matching a <verb> *-style rule and sends it to the normal prompt flow instead:

  • Chaining or composition: ;, &&, ||, pipes, background &, subshells.
  • Redirections of any kind (>, >>, <, 2>&1, heredocs).
  • Any expansion: $VAR, $(...), backticks, arithmetic, process substitution.

So bash:cat * auto-allows cat notes.txt but not cat notes.txt; rm -rf ~ or cat f > /etc/passwd. Plain quoting of literal text is fine (find . -name '*.go' matches bash:find *). Leading KEY=VAL environment assignments are skipped when computing the argv only when KEY is in the harmless build/locale allowlist (CGO_ENABLED, GOOS, GOARCH, GOAMD64, GOARM, GOEXPERIMENT, GO111MODULE, GOWORK, TZ, LANG, LC_ALL, LC_CTYPE, NO_COLOR, TERM), so CGO_ENABLED=0 go build rides a go verb grant while LD_PRELOAD=/tmp/x.so cat f and GIT_EXTERNAL_DIFF=sh git diff re-prompt.

A small set of verb profiles additionally withholds auto-allow when a dangerous predicate or mutating flag appears in the argv of an otherwise read-only verb:

  • find: -exec, -execdir, -ok, -okdir, -delete, -fls, -fprint, -fprint0, -fprintf
  • sort: -o, --output, --compress-program
  • uniq: -o, --output, or two positional operands (uniq IN OUT)
  • tree: -o, --output
  • rg: --pre, --pre-glob
  • git: top-level -c, --config-env, --exec-path, plus --output and --ext-diff
  • go: -vettool, -toolexec, and go env -w / go env -u

A profile hit never hard-denies — it only removes the auto-allow. Grant prompts for git, go, make, and npm also warn that granting the verb for the session is close to granting a shell.

Exact-match rules are exempt from both guards: if you allowlist the literal string bash:make build && make test, that exact string passes. Deny rules are also unaffected — they stay as broad as written.

Examples:

PatternMatches
bash:git statusexactly git status
bash:git *any bash command starting with git
read_file:internal/**any read_file call with a key starting with internal/
mcp:filesystem_read_filethe namespaced MCP filesystem read tool
skill:jira-triageinvocation of the jira-triage skill
*foo*anything (any tool) whose key contains foo

Deny always wins. A deny pattern matched anywhere kills the call, even if an allow pattern also matches.

The “key” of a request is tool-specific:

  • For bash: the trimmed command string.
  • For file tools (read_file, write_file, edit_file, list_dir): the resolved absolute path.
  • For MCP / skill calls: <tool_name> <json-args> (truncated at 200 chars).

The bash, read_file, write_file, edit_file, list_dir, and todo tool names refer to the built-in tools that ship with core-agent and are enabled by default in the bundled CLI. Use the same names in allow/deny patterns whether you keep the defaults or supply your own implementations under those names.


File tools may touch paths inside the project root (read-write), the user-home root ~/.core-agent (read-only), or any explicit pattern in path_scope.allow. Out-of-scope access either prompts (in ask mode with a Prompter) or fails (everywhere else).

{
"path_scope": {
"allow": [
"/etc/myapp/...",
"/var/log/myapp.log",
"~/scratch/*.json"
]
}
}

Pattern syntax:

FormMeaning
Exact absolute pathOnly that file.
Directory tree ending /...Anything at or under that root.
Standard path/filepath.Match globGlob match against absolute paths.
Leading ~ or ~/Expanded to os.UserHomeDir().

Symlinks are resolved (filepath.EvalSymlinks) before every scope check, with no opt-out. The file tools follow symlinks at the OS level, so a symlink inside the project root pointing at /etc, ~/.ssh, or ~/.aws/credentials is classified by its real target, not its in-scope name — it prompts (in ask mode) or is denied like any other out-of-scope path. New-file writes into a not-yet-existing path are classified by the deepest existing ancestor directory’s real location; any resolution failure fails closed (treated as out-of-scope).

path_scope.allow_paths is the typed form of allow — each entry carries an explicit access mode:

{
"path_scope": {
"allow_paths": [
{ "path": "/home/me/sibling-repo/...", "mode": "rw" },
{ "path": "/var/log/myapp.log", "mode": "r" }
]
}
}

mode is one of r / w / rw (long forms read / write / readwrite also accepted). Read-only entries allow reads but still prompt on writes; write-only is uncommon but supported for tools that only append. Composes with the plain allow list (which grants both r+w unconditionally, matching the legacy shape).

The --allow-path PATH:MODE CLI flag adds one entry inline without touching config.json:

Terminal window
core-agent --allow-path /home/me/sibling-repo:rw --allow-path /var/log/myapp.log:r

Repeatable; entries are merged with anything in path_scope.allow_paths. Useful for one-off sessions (a sibling checkout, a scratch dir) where you don’t want to commit the grant.


A small set of patterns are rejected for any bash call, in any mode, regardless of allow/deny config. These cover the most reliably destructive shell forms:

  • rm -r -f (in any flag-order combination) targeting /, ~, $HOME, etc.
  • dd if=… of=/dev/…
  • mkfs.*, shred …, wipefs …
  • chmod -R <mode> / and chown -R <user> /
  • curl|wget … | sh|bash|zsh|ash|dash (download-and-execute)
  • The classic fork bomb :(){ :|: & };:

Hardened posture: allowlist-based execution

Section titled “Hardened posture: allowlist-based execution”

For a real bash boundary, don’t lean on the denylist — allowlist the commands you intend. Run in allow mode (or ask with a Prompter) and grant only specific commands via permissions.allow. Prefix allow rules (bash:git *) are guarded so they only auto-allow single literal simple commands — chaining, pipes, redirections, and command substitution fall through to prompting (see Safe-command guard). An allowlist is an enumerated set of permitted actions; a denylist is a guess at the set of dangerous ones. The former is a boundary, the latter is a seatbelt.


Execution sandboxing (--sandbox, safety.sandbox)

Section titled “Execution sandboxing (--sandbox, safety.sandbox)”

safety.sandbox (#651) layers workspace write containment and optional OS/container command sandboxing on top of the permission gate:

  • Default-on policy boundary (mode: "auto", default):
    • Blocks write_file / edit_file / delete_file and bash output redirections or mutating shell commands (rm, mv, cp, chmod, chown, ln, touch, mkdir, rmdir, truncate, install, tee, sed -i, dd) targeting protected host credential and startup paths (~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.config/gcloud, ~/.config/systemd, ~/.docker, ~/.netrc, ~/.npmrc, ~/.pypirc, ~/.git-credentials, ~/.bashrc, ~/.bash_profile, ~/.bash_login, ~/.zshrc, ~/.zprofile, ~/.zshenv, ~/.zlogin, ~/.profile, /etc/cron*, /etc/crontab, /var/spool/cron, /etc/systemd, /etc/sudoers, /etc/passwd, /etc/shadow) in yolo, acceptEdits, headless runs, or mode: "enforce".
    • Enforces the workspace write boundary (PathScope project root + path_scope.allow / allow_paths + safety.sandbox.writable_paths + /tmp) even in yolo and acceptEdits modes so unprompted modes cannot silently overwrite files outside the workspace.
  • OS and container command sandboxing (mode: "enforce" or --sandbox):
    • Wraps every bash command execution in an OS-level or container sandbox according to safety.sandbox.driver:
      • bwrap (Linux bubblewrap): mounts / read-only (--ro-bind / /), bind-mounts the workspace and writable_paths read-write, mounts /dev and /proc, masks protected credential directories (~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.config/gcloud) with empty tmpfs, and passes --unshare-net when safety.sandbox.network is "none".
      • seatbelt (macOS sandbox-exec): applies a Seatbelt profile that denies file-write* outside the workspace, /tmp, /private/tmp, /dev, and writable_paths, denies file-read* on ~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, and ~/.config/gcloud, and denies network* when safety.sandbox.network is "none".
      • container (docker / podman): runs commands inside docker run --rm -i --read-only (or podman) with writable directories mounted via --mount type=bind,src=...,dst=...,rw, --tmpfs /tmp:rw,noexec,nosuid, and --network=none when safety.sandbox.network is "none".
      • auto (default): selects container when container_image is set, bwrap on Linux when bwrap is usable, seatbelt on macOS when sandbox-exec is on PATH, and in mode: "auto" falls back to policy otherwise (or fails closed with ErrSandboxUnavailable in mode: "enforce").
  • Escape hatch (--no-sandbox or mode: "off"): Disables sandbox containment and emits a visible core-agent: warning: sandbox disabled line to stderr.

Writes to any file the boot path loads — or that steers the host’s git toolchain on the human’s next git command — belong to the control-plane write tier:

  • .git/** (.git/config, .git/hooks/*, worktree .git pointers).
  • Every boot-loaded mcp.json (.agents/mcp.json, ~/.agents/mcp.json, ~/.core-agent/mcp.json, and rooted declarative subagents’ <root>/mcp.json).
  • .agents/ boot files and subtrees: config.json, env.yaml / env.yml / env.json, pricing.json, agent-card.json, and .agents/{skills,subagents,providers,AGENTS.d}/**. Runtime output directories (.agents/plans/, .agents/sessions/) stay normally writable.
  • Instruction files: AGENTS.md, CLAUDE.md, GEMINI.md, and AGENTS.d/** (project, rooted subagent, ~/.agents/, and ~/.core-agent/).
  • User-global ~/.core-agent/** (including ~/.core-agent/pricing.json and ~/.core-agent/AGENTS.md), which is also read-only (AccessRead) in PathScope.

Writes to control-plane files require an elevated interactive approval (PromptKindControlPlaneWrite). This approval is never satisfied by yolo/acceptEdits mode, a session/verb/tool grant, an allowlist entry, or a built-in bundle — only an explicit prompt approval passes. With no interactive prompter available (headless), the write is denied with ErrControlPlaneWrite. Classification runs on the symlink-resolved path, so a symlink pointing at a control-plane file is caught too. Each elevated approval authorizes exactly one write; it is not remembered.

Config-driven hooks (see Hooks) run shell commands on event boundaries. Because .agents/config.json is writable by the model, hook commands are routed through the permission gate (a bash-kind check: the built-in denylist, the configured mode, and any deny patterns apply) before they execute. A hook the gate refuses does not run. If the dispatcher has no gate wired, it fails closed and runs nothing.

When ask mode prompts the user, the Prompter returns one of:

DecisionEffect
DecisionDenyReject this call.
DecisionAllowOnceAllow this call; prompt again next time the same call is made.
DecisionAllowSessionAllow this exact request for the rest of the session — same (tool, key) pair won’t re-prompt.
DecisionAllowSessionToolTrust the specific tool for the rest of the session — every call to it passes regardless of args. For namespaced toolsets (MCP, skills) the grant is scoped per underlying tool (mcp/<tool>), so approving one MCP tool does not trust every tool from every server.
DecisionAllowAlwaysAllow + the gate installs a permanent grant: non-path prompts become a live "<tool>:<key>" policy pattern, path prompts a subtree-expanded scope entry. When a GrantStore is wired (permissions.Options.GrantStore / Gate.SetGrantStore) the grant is also persisted — the bundled CLI wires the config-backed store, which writes permissions.allow patterns and typed path_scope.allow_paths entries (carrying the grant’s r/rw access) into .agents/config.json. Persist failures surface to the gated call rather than silently downgrading to session-only. Without a store, the grant lasts the process lifetime.

DecisionAllowSessionTool suppresses the mode prompt for in-scope operations, but it does not drop the path boundary: an out-of-scope read or write still escalates via the path-scope prompt every time, even for a session-trusted file tool. Trusting read_file for the session silences repeat prompts for files inside your scope; it does not grant the tool the whole filesystem.

DecisionDeny has a scope of its own, and it is the turn. A denial — and an unanswered prompt that hit approval_timeout — is remembered for the rest of the turn against that exact (tool, key) pair, so an agent that re-issues the same call is refused without a second prompt reaching anybody, with a message saying it is a repeat. Nothing else arms it: an approval is not remembered this way, and a different request still prompts. It clears at the next turn boundary. This is the second half of the fix for a live-cluster failure where one denial became five identical calls and a halted session (#1074).

Three suppressed repeats end the turn (v3.0, #1081). Not asking twice is cheaper than asking twice, but it is not an answer to a model that keeps going: re-running the rig above cost five fewer prompts and zero fewer calls, and the loop still ran until the watchdog counted to five and halted the session for the rest of its life. So after the gate has refused three calls in a turn without asking anybody, the turn ends. Three rather than the watchdog’s five because the evidence is of a different quality — a repeated tool name cannot tell a loop from a sweep, whereas a suppressed repeat means the operator refused this exact request, the model was told so in a tool result, and it asked again — and counted across requests, so alternating between two already-refused calls is the same thing. What ends is only the turn: nothing is tripped, there is nothing to reset, and the next turn runs with the refusals in the model’s history where they belong. The cut also takes those calls off the watchdog’s books (#1086), because the watchdog is reading the same tool stream and its run length is not scoped to a turn — without that, the next turn’s first identical call would be the fifth in a row and would halt the session, which is the outcome this exists to prevent, one turn later. That is safe rather than a hole: three suppressed repeats is a tighter bound than the watchdog’s five, so a model looping through the gate is always stopped sooner than the watchdog would have stopped it, and a loop on a tool the gate never sees never reaches this arm at all. The cut appends an eventlog row (Author=gate/refusal-storm, carrying the count) and labels the turn’s metric refusal_storm; it emits no guardrail-trip, because a client told about one would offer a reset for a guardrail that does not exist. It does write a refusal_storm guardrail cut the turn in flight line to the daemon log (#1131) — not a reversal of the previous sentence, since a log line has no reset vocabulary to misuse, and this is the one in-turn arm that reaches no live client at all, so before v2.10 an operator watching a gated run saw the turn die with a bare context canceled and nothing anywhere but the eventlog said why. See Without an attach listener, the cut is in the log. There is no flag to switch it off: the other in-turn guardrails are opt-in because they act on inference, and this one acts on a decision the operator already made.


Background subagents and the gate (v1.2.0+)

Section titled “Background subagents and the gate (v1.2.0+)”

When agent.WithBackgroundManager is wired, every spawned background subagent inherits the parent’s gate by reference. That has three consequences worth knowing:

The spawn itself is gated too (v2.9+). spawn_agent and spawn_remote_agent call the gate before anything launches, so plan-first, the allow/deny policy, and the ask prompt all apply to creating a subagent — not just to what it does afterwards. Before v2.9 the gate governed only the second half, which under plan_mode: "required" meant a parent with no plan recorded was told spawn_agent would be denied, called it, and it ran.

The key a rule matches is the subagent being launched, not the goal (a goal is fresh prose every call, so no rule could match it twice):

spawn_agent:cluster one preconfigured subagent
spawn_agent:ad-hoc:* any inline-persona spawn, whatever the model names it
spawn_agent:* all delegation

One rule covers both doors. A declarative subagent is reachable two ways — spawn_agent {agent: "cluster"} and, because agent.WithSubagents also registers it as a parent tool, a direct cluster(request: …) call. Both are matched under the spawn_agent bucket, so deny: ["spawn_agent:cluster"] means cluster does not run, not that it does not run asynchronously. (Library callers wiring agent.NewSubagentTool themselves pass the gate via SubagentOptions.Gate; agent.WithSubagents fills it in from agent.WithGate.)

stop_agent is deliberately not gated in any mode. It cancels, so every denial of it leaves running exactly what the model was trying to halt. To hand a subagent delegation without cancellation — or neither — withhold the tools rather than gating them (subagents[].tools, which already withholds both by default).

  1. Session-level approvals apply tree-wide. If you approve DecisionAllowSessionTool for bash while a subagent is asking, every subagent (including future siblings) gets the same grant for the rest of the session. The gate has no per-subagent allow-state today; the whole tree shares one map.

  2. Prompts include source attribution. permissions.PromptRequest carries a Source field that StdinPrompter renders in the heading: [<subagent-name>] bash wants to run: .... So when a subagent triggers a prompt, you know which one is asking. Empty Source (the parent’s own tool calls) renders unchanged. The gate populates Source from a context value permissions.WithSubagentSource(ctx, name) that the spawn machinery stamps on every subagent’s ctx.

  3. Concurrent prompts serialize. Multiple background subagents racing for os.Stdin would deadlock or interleave garbage. Wrap any interactive prompter in permissions.Serialize(...) before handing it to the gate:

    prompter := permissions.Serialize(permissions.StdinPrompter(os.Stdin, os.Stderr))
    gate := permissions.New(permissions.Options{Prompter: prompter, Mode: permissions.ModeAsk})

    The bundled CLI does this automatically. Library callers using their own gate construction with background subagents should too.

Deferred (v1.3+): bounded permission subsets where the spawner grants the subagent only part of its own permissions and the spawner’s model arbitrates out-of-subset requests via an injected synthetic prompt. Today, “inherit the parent’s gate” is the only mode.


After a session in ask mode, the gate exposes an audit log of every approval. permissions.Recommend(approvals) turns that log into a prioritized list of suggested permanent allowlist entries:

recs := permissions.Recommend(gate.Approvals())
permissions.SortRecommendations(recs)
for _, r := range recs {
fmt.Printf("%-40s %s\n", r.Pattern, r.Reason)
}

Heuristics built in:

  • A single approval becomes an exact pattern (bash:git status).
  • Multiple bash approvals sharing a leading verb collapse to a verb-glob (bash:git *).
  • Multiple file approvals sharing a directory prefix collapse to a directory glob (read_file:internal/tui/**).
  • Otherwise, a tool-wide suggestion (bash:*) is offered as a fallback the user can opt out of.

SortRecommendations puts non-wildcard patterns above wildcards so the safer recommendations surface first.


Hosts that can interact with the user implement the Prompter interface:

type Prompter interface {
AskApproval(ctx context.Context, req PromptRequest) (Decision, error)
}

PromptRequest carries everything needed to render a prompt — kind (bash / file write / path scope / generic), tool name, detail string, and the persistence keys the gate uses to build the grant if the user picks DecisionAllowAlways. A custom Prompter only returns the decision; installing and persisting the grant is the gate’s job (via the wired GrantStore).

In mode auto, a prompt can come from the approver model passing a call on (#1175). ApproverModel is then set, and ApproverReason holds its reason when it gave one. Show the reason quoted as the approver’s words: it is model output that the call’s own arguments can steer. Offer only allow once and deny, because the gate applies any allow on such a prompt as DecisionAllowOnce. The bundled StdinPrompter, the local TUI and core-agent-tui all do.

The bundled cmd/core-agent does not currently ship a Prompter — ask mode in the REPL fails closed. To use ask mode interactively, embed the library in your own host and supply a Prompter. See Library API → Prompter.

A prompter that knows who answered can say so, by also implementing the optional AttributingPrompter (#830):

type AttributingPrompter interface {
Prompter
AskApprovalAttributed(ctx context.Context, req PromptRequest) (Approval, error)
}
type Approval struct {
Decision Decision
By string // empty when the prompter can't attribute the answer
}

The gate type-asserts for it and falls back to plain AskApproval, so existing Prompters keep compiling and behaving identically. When it is implemented, By lands in ApprovalLog.By — the gate’s answer to “who allowed this”, readable via Gate.Approvals() and over the daemon’s GET /perms.

Two rules make that field worth trusting:

  • By is only ever an identity the answering host verified. Never a name lifted from a request body, and never a placeholder for an unknown answerer — a placeholder in an audit line is indistinguishable from a real attribution. The attach daemon follows this: it names the caller its auth middleware verified, and records nothing when it verified nobody. See Approval attribution.
  • A wrapper must forward the capability. permissions.Serialize does. If you write your own wrapping Prompter, implement AskApprovalAttributed too — otherwise the type assertion fails on the wrapper and every approval through it is recorded anonymous, silently.

For non-interactive runs (CI, batch jobs), use:

{
"permissions": {
"mode": "allow",
"allow": [
"bash:go test ./...",
"bash:go vet ./...",
"read_file:**"
]
}
}

mode: allow rejects anything not on the allowlist, which is what you want when there’s no human in the loop.

autonomous.Run would deadlock under mode: ask if your tools route through a gate without a Prompter — the model’s first gated tool call would block waiting for human approval that’s never going to arrive. Two options:

  • Use mode: yolo (or mode: allow with an explicit allowlist) for unattended runs.
  • Wire permissions.RefusePrompter so the agent gets a clean refusal instead of blocking, and pass autonomous.WithPermissionsGate(g) to enable the driver’s startup deadlock guard. See Autonomous runs → Permission modes.

Permission gating is bridged to ADK via the tools.GateToolset wrapper. It wraps any adktool.Toolset (an MCP server, a skills bundle, your own custom toolset) so each tool call goes through the gate before execution:

import (
coretools "github.com/go-steer/core-agent/v3/pkg/tools"
"github.com/go-steer/core-agent/v3/pkg/permissions"
)
gated := coretools.GateToolset(myToolset, gate, "my-namespace")

The namespace argument is the policy bucket — it’s what the allow/deny patterns use as the tool name (e.g. mcp:, skill:, or your own).


Every non-deny approval is recorded in the gate’s session log:

for _, a := range gate.Approvals() {
fmt.Printf("%s %s %s %s\n", a.At.Format(time.RFC3339), a.Tool, a.Decision, a.Key)
}

This is the data source for Recommend(). It’s also useful for post-hoc auditing of what tool calls were approved during a run.