Hooks and privacy: what the agent is blocked from reading, and why blocking is not enough

Article 7/20 in the AgentKit v3 onboarding series. About a 9 minute read.

Hooks are bits of code that run before or after each agent action: before reading a file, before running a shell command, when a session opens, when context is compacted... AgentKit uses hooks for two things: nudging the agent to work with discipline and blocking the agent from touching sensitive things.

This article lists the hooks in the kit, how to turn them on and off, and most importantly: the real limits of this layer of protection.

1/ Hook list ✅

Core kit (installed with every kit)

Added by the Engineer kit

agent-behavior-linter, cook-after-plan-reminder, plan-format-kanban, precompact-capture (records state before context gets compacted), session-init, session-state, subagent-init, team-context-inject, and the usage-* group that tracks usage levels.

2/ Turning hooks on and off ✅

Each hook has a switch in preferences:

ak config prefs set hooks.descriptive-name false
ak config prefs set hooks.descriptive-name true

My advice: do not turn off privacy-block and secret-output-guardrail. The reminder hooks are a matter of taste, and if they annoy you, turn them off.

3/ How the privacy guard works ✅

When the agent is about to read a sensitive file:

1. The hook refuses the first time, with a question for you.

2. You approve (in Claude Code it is a choice box with "Yes, approve access" or "No, skip this file").

3. The agent retries with an APPROVED: marker, and only then can it read.

Version 3.0.0 also patches a few workarounds I actually ran into:

• The first touch of a sensitive file through the shell is blocked too, not only through the Read tool.

• Piped or wrapped commands (like cat .env | grep KEY, bash -c "cat .env") are inspected to catch dotenv reads.

• The PowerShell tool on Windows is covered as well.

4/ .akignore: your own "don't touch" list ✅

The syntax is exactly like .gitignore. ak reads it in this order:

1. <AGENTKIT_HOME>/.akignore (default ~/.agentkit/.akignore) for every project

2. <project>/.akignore

3. <project>/.agentkit/.akignore

Example:

# client contracts
contracts/**
# real data
data/production/**
*.pem

A subtle point: project-level rules need to be trusted before they take effect. ak stores the file's digest in state/akignore-trust/. Why? Because otherwise, a stranger's repo you just cloned could add its own .akignore to loosen the rules. If the file changes, it has to be trusted again.

5/ Real limits: read this part carefully ⚠️

I am writing this bluntly, because security documentation that only brags is more dangerous than no documentation:

The privacy guard is a cooperative layer, not a barrier against a model deliberately trying to break it. It stops an agent that "slips", and stops most naive prompt injections. But a determined enough model with the right to run arbitrary shell commands still has ways around it. For absolute certainty, secrets must not sit on disk as plaintext. That is why the vault exists.

On Codex, the privacy guard does not yet cover MCP and local read tools. Per the v3.0.0 runtime certification table. If you use Codex with an MCP server that has file read access, treat the guard as absent on that path.

Hooks only run when the runtime supports hooks. Each runtime has a different level of support. Claude Code is where hooks are most complete.

So here is the combo I use every day:

1. Secrets in the vault, not in .env.

2. Privacy guard on, to catch the slips.

3. .akignore for each client's sensitive folders.

4. Never let an agent run with broader permissions than needed on a repo holding real data.

6/ Quick check

ak doctor

Doctor reports the status of hooks and related config. If you want the agent to audit on its own:

/ak-security scan this project for leaked secrets and check .akignore

Next article: Decision Layer: System One, Jev, Clef →

Sources

• Hook list in agentkit/kits/core and agentkit/kits/engineer (tag v3.0.0)

• v3.0.0 release note (privacy guard section: deny first sensitive shell access, piped/wrapped dotenv reads, PowerShell tool): https://github.com/bestagentkits/agentkit/releases/tag/v3.0.0

• .akignore and trust digest documentation in the agentkit repo (tag v3.0.0)

• v3.0.0 runtime certification matrix (Codex privacy guard note)