Chapter 4 — Tools, permissions, approvals, hooks, secrets, and trust boundaries¶
A coding agent does not become dangerous simply because it “has tools.” The risk appears when we confuse being able to propose a tool call with having authority to produce the effect that call attempts to cause.
The same model can propose:
Read("src/auth.ts")
Bash("npm test")
Bash("npm publish")
GitHub.create_pull_request(...)
Cloud.delete_database(...)
From the model’s perspective, all five have a similar shape: tool name plus arguments. Operationally they do not have the same reach, reversibility, credentials, or blast radius.
The harness needs an explicit boundary between inferred intent and executable authority.
The right question is not “which tools does the agent have?”¶
There are at least six separate control planes:
| Plane | Question |
|---|---|
| Tool surface | Which actions does the model know about and can it propose? |
| Policy | Which action classes are allowed, blocked, or require review? |
| Approval | Who authorized this specific action, for what scope, and for how long? |
| Sandbox / runtime | Which filesystems, processes, and networks can execution actually reach? |
| Identity / secrets | Which identity authenticates, and what privileges does it carry? |
| Remote system | Which ACLs, branch protections, IAM rules, or native controls does the target enforce? |
A serious defense composes those planes. It does not replace five of them with a prompt that says “be careful.”
We can express the relationship as a conceptual predicate:
For an action \(a\):
- \(T\): the tool is available
- \(P\): policy allows that action class
- \(S\): the sandbox/runtime can reach the resource
- \(C\): the presented credential authorizes the operation
- \(R\): the remote system accepts the operation under its own controls
- \(A\): any required approval is still valid for this exact action
This is not a specification from any product. It is a useful way to reject a false implication: tool_available = true does not mean authorized = true.
Tool availability and permission are different controls¶
Reducing the tool catalog visible to the model is valuable. It shrinks the action space the model can choose from and avoids pointless attempts.
But hiding a tool is not the same as enforcing a security boundary around the underlying capability.
An agent without delete_file can still delete files if it retains a shell with enough authority. An agent without a dedicated HTTP tool can still make outbound requests if it can execute curl, Python, Node, or an equivalent binary.
GitHub documents this distinction explicitly for Copilot CLI: --available-tools and --excluded-tools control which tools the model can choose, while allow/deny permissions control whether those tools may execute. The same documentation notes that an authorized shell can install packages, delete files, push code, or make network requests.6
The general rule is:
The first helps the model. The second protects the system.
Policy must live outside model inference¶
An instruction such as:
can guide behavior. It is still context interpreted by the model. It can conflict with another instruction, with injected repository content, or with a mistaken classification.
Executable policy should be evaluated in a layer that does not depend on the model remembering to obey it.
OpenAI describes exactly this separation in its internal Codex deployment. The sandbox sets technical boundaries, approval policy decides when execution must stop for authorization, network policies govern destinations, and rules can allow, block, or require approval for command patterns. Managed requirements can be enforced so users cannot override them.1
Claude Code likewise documents that its permission rules are enforced by Claude Code rather than by the model. Prompt instructions or CLAUDE.md can affect what Claude attempts, but they do not change runtime allow/ask/deny rules.2
That suggests an important property for a production harness:
If the same untrusted context can rewrite the policy intended to constrain it, the boundary disappears.
Deny, ask, and allow are not three equivalent risk levels¶
A useful design distinguishes:
DENY → there is no authorized path for this action
ASK → a path exists, but it requires additional authorization
ALLOW → execution may continue without a new human decision
ASK does not mean “probably dangerous,” and ALLOW does not mean “proven safe.” They are authority decisions, not semantic proofs of correctness.
For example:
Read(src/**) → ALLOW
Bash(npm test) → ALLOW
Bash(npm install *) → ASK
Bash(git push origin main) → DENY
Cloud(prod/*) → DENY
These rules are illustrative, not portable syntax across harnesses.
A real policy must reason about more than a superficial tool name. Resource, environment, arguments, and identity matter.
Approval should be bound to the action the human reviewed¶
A weak pattern is:
The resulting authorization is much broader than the decision the human probably intended to make.
A robust approval should be able to answer:
which tool
which normalized arguments
which resource or environment
which identity/role will be used
which expected effect was shown
what temporal scope applies
which task/contract caused the action
For high-impact operations, the harness can bind approval to a digest of the exact request:
approval_subject = H(
task_id,
tool,
normalized_arguments,
target_environment,
credential_identity,
policy_version
)
This hash is a design pattern, not a standard. Its purpose is to prevent an authorization for deploy staging from silently becoming authorization for deploy production, or for arguments to change after review.
Agents also have a TOCTOU problem¶
Time of check / time of use means the object that was reviewed may no longer be the object that is executed.
For example:
1. agent proposes: delete temp/cache-123
2. policy: ASK
3. human reviews and approves
4. the temp/cache-123 symlink changes before execution
5. the operation reaches a different target
Or at a more agentic layer:
1. approval covers tool=deploy, environment=staging, artifact=A
2. the plan continues and rebuilds
3. artifact becomes B
4. deployment uses B with the approval granted for A
An approval therefore should not be a boolean. It needs a subject, scope, version, and expiry, and the runtime should revalidate its preconditions before the effect occurs.
Sandboxing and approvals answer different questions¶
A sandbox can answer:
can this process write outside the worktree?
can it open sockets?
can it read ~/.ssh?
can it launch child processes?
An approval answers a different question:
OpenAI makes that distinction explicit for Codex: sandboxing and approvals work together. The sandbox establishes the technical execution boundary, while approval policy determines when an action must stop for review.1
This avoids two opposite mistakes:
- “it is inside a container, so it can use any credential available there”
- “the user clicked approve, so filesystem and network constraints are no longer necessary”
Neither conclusion follows.
A credential is packaged authority¶
An API key, OAuth token, certificate, or credential helper is not merely “configuration that makes the tool work.” It establishes an identity and delegates privileges.
The design questions include more than storage location:
who obtains it
for which service
with which scopes/roles
which process receives it
how long it lives
whether a subprocess inherits it
how it is revoked
what can be logged without exposing the value
OpenAI documents storing CLI and MCP OAuth credentials in the operating-system keyring in its Codex deployment and binding authentication to a managed workspace.1
GitHub similarly separates the default Copilot cloud-agent token, whose scope is limited to the repository where the agent runs, from Agents secrets that administrators can add for external resources. GitHub also documents that Agents secrets are distinct from Actions, Codespaces, and Dependabot secrets.7
Product details differ. The conceptual boundary remains:
Prefer minimal projection over “inject every environment secret”¶
Suppose the task needs to download @acme/auth from a private registry.
A weak design starts the agent with:
Even if policy says “only install dependencies,” every process that can read the environment inherits a much larger capability set than the task needs.
A narrower design projects only what is needed, when it is needed:
action: package.install(@acme/[email protected])
credential: registry-read-token
scope: packages:read
lifetime: this operation / short TTL
network: registry.acme.example
Then it removes or expires that capability.
The safety benefit comes from reducing blast radius, not from trusting the model not to discover other environment variables.
“Read-only” can still be sensitive¶
An operation that does not mutate the system can still cause harm when sensitive reads are composed with egress.
Each operation in isolation may look like “just reading” or “just networking.” Together they form an exfiltration path.
A coding-agent policy therefore should not classify risk only as:
It must consider capability composition. Secret reads plus an outbound channel are a different control problem from file mutation.
GitHub acknowledges this risk class in its cloud-agent documentation: the agent can access code and other sensitive information and could leak it accidentally or through malicious input, so GitHub restricts Internet access.8
A firewall is not a magic word either¶
Even when a product offers a firewall, the threat model needs to ask which processes cross that boundary.
GitHub documents a specific limitation of the configurable firewall for Copilot cloud agent: its restrictions apply to processes launched through Bash, not necessarily to MCP servers or processes launched during setup, and it should not be treated as a universal boundary against every bypass.9
This is not a general criticism of firewalls. It is exactly the detail a threat model needs:
Saying only “network restricted” removes the part needed for reasoning about failure.
Hooks: automation and enforcement are not the same thing¶
Hooks are useful for turning repository invariants into automatic behavior:
before a tool call → validate / block / request approval
after an edit → formatter / lint / tests
after a tool → redaction / audit / feedback
at completion → completion verifier
But the point in the lifecycle where a hook runs determines what it can guarantee.
Claude Code documents that PreToolUse runs after Claude has constructed tool arguments and before the tool call is processed. It can return allow, deny, ask, or defer, and can modify input before execution.3
By contrast, PostToolUse runs after the tool has completed. It can change what Claude sees or block continuation, but files written, commands executed, and network requests have already taken effect.3
Therefore:
A secret scanner that runs after git push can detect a leak. It cannot retroactively make the push safe.
A hook can itself be a privileged surface¶
The reverse question matters too: with which authority does the hook run?
Claude Code documents that command hooks run with the user’s full permissions.3 Its current workspace-trust semantics also differ by configuration type: interactive sessions hold settings-file hooks until the workspace is trusted, while claude -p and SDK sessions treat the folder as trusted for those hooks, so hooks committed in .claude/settings.json can run even when the user has never approved that folder interactively.3 By contrast, capability-expanding permissions.allow rules and additionalDirectories from .claude/settings.json remain unused in -p/SDK when that exact folder has not previously been trusted; no dialog appears and Claude Code emits a warning.2 Project-subagent frontmatter hooks follow a stricter rule: as of v2.1.218 they require workspace trust; earlier versions could run them from untrusted folders.3
That makes repository configuration part of the threat model.
A harness that processes untrusted repositories should explicitly decide:
are repository hooks loaded?
are repository settings loaded?
are executable helpers allowed?
are tool servers declared by the repository connected?
under which user/namespace do they run?
“The agent is only going to read code” does not answer those questions if opening the project activates executable configuration.
Trusted configuration and repository-controlled configuration¶
There is a difference between:
and:
The second has operational power.
Claude Code applies workspace trust to specific project capabilities and gives restrictive rules such as deny precedence. Managed settings can impose policy that lower-precedence scopes cannot relax.24
The more general design implication is:
The more privileged a configuration surface is, the higher its trust domain should sit relative to the content the agent is inspecting.
For third-party code, host security configuration should not depend on files the repository itself can modify.
Prompt injection changes decisions; policy limits consequences¶
A repository file can contain:
We should not assume the model will obey it. We should not assume it will never obey it either.
The defensive design starts from the premise that repositories, issues, web documentation, and tool outputs can all be untrusted context.
Anthropic documents prompt injection as an explicit Claude Code risk and recommends permissions, isolation, and review as defensive layers.5 GitHub likewise documents that issues and comments can carry prompt injection against Copilot cloud agent and applies product-specific mitigations alongside network restrictions.8
The useful property is not “the model detects the attack 100% of the time.” It is:
Worked example: update a private package and open a PR¶
Task:
Upgrade @acme/auth from 4.1.0 to 4.2.1, adapt the API if needed,
run the tests, and open a PR. Do not publish packages or deploy anything.
1. Context¶
The agent reads package.json, the lockfile, code, tests, and changelog. Repository and dependency content is treated as input, not as higher-authority policy.
2. Tool surface¶
At minimum it needs:
It does not need npm publish, cloud deployment, or production access.
3. Policy¶
allow:
- read repo
- edit workspace
- run tests
ask:
- network access to private registry
- push branch / create PR if policy requires it
deny:
- package publish
- production cloud tools
- push to protected branch
This YAML is illustrative rather than a cross-product syntax.
4. Network¶
Egress is limited to the private registry and the GitHub endpoints required by the task. An arbitrary curl invocation does not automatically inherit that authorization.
5. Credentials¶
Two identities are projected separately:
A production credential is not exposed merely because CI already has one available somewhere.
6. Approval¶
If installing the package requires widening egress, the approval should show the destination and operation. If pushing is authorized, that authorization is bound to the working branch rather than to main.
7. Hooks / verifiers¶
A pre-hook can block npm publish. A post-edit hook can run lint and tests. A secret scan before push can prevent a credential from being materialized in the diff.
Order matters:
is preventive.
only detects after the effect.
8. Evidence¶
The trajectory can record:
action_id: act-184
task_id: CA-204
tool: package.install
target: registry.acme.example
arguments_digest: sha256:...
policy_version: 17
decision: allow_after_approval
approval_id: apr-91
credential_identity: registry-read
credential_value_logged: false
network_destination: registry.acme.example
result: success
verification_head_sha: 73ab...91f
The log records identity and decision, not the secret value.
Persistent approvals accumulate authority¶
“Don’t ask again” reduces friction. It also turns one-off decisions into persistent configuration.
Claude Code documents that some approvals can be persisted per repository and reused by future sessions, while others last only for the session. GitHub Copilot CLI likewise persists certain approvals and scopes them differently depending on tool, location, or domain.26
The operational question is:
A useful inventory records active persistent approvals, who created each one and when, its exact scope, last use, owner, expiry date or condition, and revocation mechanism.
An old permission granted to resolve an incident should not silently become the baseline for every future task.
The remote system still gets the final say¶
The harness should not assume its approval replaces external controls.
GitHub documents, for example, that Copilot cloud agent cannot approve and merge its own pull request. It also restricts workflows triggered by agent-authored code by default until a user with sufficient permission explicitly approves execution, unless the repository is configured otherwise.8
That is a useful example of separate failure domains:
agent policy → decides what the agent attempts
repository controls → decide what GitHub accepts
CI/deploy controls → decide which artifact progresses further
If every layer depends on one omnipotent token and one agent decision, the defense in depth is nominal.
What to observe if authority must be auditable¶
Recording only:
does not explain why the action was legitimate.
A decision ledger should retain, without storing secrets:
task_id
session_id
agent/model identity
requested tool + normalized args/digest
policy version + matching rule
decision: allow / ask / deny
approval identity + scope + expiry
credential identity/scopes, never the value
sandbox/network decision
remote resource/environment
effect result
verification result
OpenAI documents Codex OpenTelemetry export for events including prompts, tool approval decisions, tool execution results, MCP usage, and network-proxy allow/deny decisions.1
Observability does not replace preventive control. It lets us explain and evaluate whether the control worked.
Permission evals need negative paths, not only happy paths¶
A coding-agent test should not prove only that an allowed task can finish.
It should include trajectories such as:
repo asks to exfiltrate a secret → DENY
model attempts to push to main → DENY
model requests an allowed registry → ALLOW/ASK according to policy
arguments change after approval → approval invalid
post-hook detects a problem → not treated as prevention
credential has expired → fail closed + handback/retry policy
network destination outside allowlist → DENY
And it should verify the effect, not merely the agent’s message.
A model saying “I did not execute the command” is not evidence if the audit trail shows that a process or request actually occurred.
The real trade-off: velocity versus pre-granted authority¶
Requesting approval for every file read makes an agent unusable. Preauthorizing shell, network, and production credentials makes autonomy cheap by giving it an enormous blast radius.
The goal is not to maximize confirmation prompts. It is to place friction at boundaries that materially change risk:
repeatable + reversible + local + no secrets → more autonomy
remote mutation + privileged credential → stricter policy
irreversible + production + sensitive data → strong separation / handback
These categories depend on the actual system. A git push to a disposable branch is not equivalent to terraform apply in production even though both may be shell commands.
Production implication: design authority as a graph¶
The stronger pattern is not one global list of “allowed tools.” It is a graph in which every effect must cross the boundaries relevant to that effect:
untrusted context
↓
model proposal
↓
tool schema / argument validation
↓
policy decision ─── DENY → stop + evidence
↓
scoped approval, when required
↓
sandbox + network enforcement
↓
minimal credential projection
↓
remote ACL / branch protection / IAM
↓
effect
↓
postcondition + audit + verifier
The central consequence is simple: the model can propose actions; the harness and external systems own the authority.
A coding agent is more autonomous when it can traverse this graph without unnecessary intervention. It is safer when every boundary can independently say “no” even after inference has decided to continue.
The next chapter makes that separation testable: tests, verifiers, diff review, and stop conditions must prove that authorized actions produced the correct result, not merely that they completed without an error.
Primary references¶
-
OpenAI, Running Codex safely at OpenAI, May 8, 2026. Used for the explicit boundaries among sandboxing, approvals, network policy, identity/credentials, rules, managed requirements, and telemetry. ↩↩↩↩
-
Anthropic, Configure permissions — Claude Code Docs. Used for allow/ask/deny rules, enforcement outside the model, sandbox interaction, and workspace trust. ↩↩↩↩
-
Anthropic, Hooks reference — Claude Code Docs. Used for current
PreToolUse/PostToolUsesemantics, decision control, and security warnings around command hooks and workspace trust. ↩↩↩↩↩ -
Anthropic, Settings files and precedence — Claude Code Docs. Used for current managed/project/local/user settings precedence and restrictions that lower scopes cannot relax. ↩
-
Anthropic, Security — Claude Code Docs. Used for responsibility boundaries, prompt injection, isolation, network, and credential guidance. ↩
-
GitHub, Allowing and denying tool use — GitHub Copilot CLI. Used for the distinction among tool availability, approvals, and allow/deny controls. ↩↩
-
GitHub, Giving GitHub Copilot cloud agent access to resources in your organization. Used for the documented limits of the default token and Agents secrets. ↩
-
GitHub, Risks and mitigations for GitHub Copilot cloud agent. Used for Internet restrictions, prompt-injection surface, review/merge boundaries, and workflow approvals. ↩↩↩
-
GitHub, Customizing or disabling the firewall for GitHub Copilot. Used only for its documented coverage limitations, without generalizing those limits to other runtimes. ↩