Hooks Overview

A hook is a script that runs automatically at a set moment, such as just before Claude uses one of its tools. A rule asks Claude to behave in a certain way, while a hook enforces it, because it runs outside Claude’s reasoning and can stop a tool call outright. AI Business OS uses hooks as its security layer. They stop Claude changing the files that make the workspace work, stop the most destructive terminal commands, and warn you before you commit changes to those files.

The security layer has four hooks. Version 3.0.2 ships three of them, and the fourth, the outbound guard, arrives in a future release.

Hook	Runs	In 3.0.2
Engine guard	Before Claude edits or writes a file	Yes, active from installation
Safety guard	Before Claude runs a terminal command	Yes, active from installation
Pre-commit hook	When you make a git commit	Yes, but only after you install it
Outbound guard	Before an agent runs a command, fetches a web page or searches the web	No, arrives in a future release

The engine guard and safety guard are registered in .claude/settings.json. The pre-commit hook is a git hook, so git runs it, not Claude Code.

Engine Guard

The engine guard protects the critical engine files, the ones that control how AI Business OS behaves, updates itself and enforces safety. The script is Infrastructure/Scripts/engine-guard.sh.

Before every use of Claude’s Edit, Write or MultiEdit tools, the hook reads the target file path and checks it against the critical list in .claude/engine-manifest.json. If the file is on the list, the hook blocks the edit and tells Claude why. The message explains that the file is critical, that any change would be overwritten at the next update, and that a companion file is the way to extend it. Files that are not on the list, and files outside the workspace, pass straight through.

When the guard blocks an edit, Claude tells you and offers the companion file route. For example, to add your own blocked commands, Claude creates .claude/rules/my-blocked-commands.md and leaves blocked-commands.md unchanged. See How Rules Work.

Safety Guard

The safety guard stops terminal commands that can destroy work or change your whole computer. The script is Infrastructure/Scripts/safety-guard.sh.

Before Claude runs any terminal command, the hook checks the command text against these patterns.

Category	Patterns
Destructive operations	rm -rf and rm -fr, git push --force and git push -f, git reset --hard, DROP TABLE, and DELETE FROM with nothing after the table name
Administrator rights	A command that starts with sudo
Running downloaded code	curl or wget piped straight into a shell
Installing software system-wide	brew install, apt install, apt-get install, pip install -g, npm install -g
Global git settings	git config --global

A match blocks the command, and Claude receives a reason that asks it to check with you. The hook blocks the same command every time, so a yes from you does not let it through. If you want the command run, run it yourself in a terminal after reading it. See Blocked Commands for the rule this hook backs up.

Pre-Commit Hook

The pre-commit hook runs when a git commit is made. Unlike the two guards, it is not active when you install AI Business OS. To install it, run this command from the workspace folder.

bash Infrastructure/Scripts/install-hooks.sh

The installer links .git/hooks/pre-commit to Infrastructure/Scripts/pre-commit-hook.sh, so later updates to the script take effect without reinstalling.

When a commit includes a critical engine file, the hook warns you that the file is essential to AI Business OS, that the next update overwrites it, and that a companion file is the better route. In a workspace with no upstream git remote, it then asks Continue anyway? [y/N] and stops the commit unless you answer y. Where it cannot ask, it blocks the commit. In a workspace that has an upstream remote, which /update adds, it prints the warning and lets the commit through.

The hook was written to maintain the AI Business OS template itself, and it does more than warn. When a commit includes any file in an engine folder, it adds new files from those folders to the engine manifest, raises the engineVersion number in .claude/engine-manifest.json, updates the version line in README.md, and offers to write a changelog entry.

Caution

In your own workspace, those extra steps change the engine version your workspace reports and add your own new skills, rules or scripts to the engine’s file list. /update reads that version to find the published copy it merges your files against, so a changed number can leave the update without the right merge base. Weigh this before you install the hook. To commit once without the hook running, use AIBOS_ENGINE_UPDATE=1 git commit.

Limits in Version 3.0.2

• The guards check Claude’s tools only. The engine guard watches the Edit, Write and MultiEdit tools. A file changed by a terminal command, or by you in VS Code, is not checked.
• The safety guard matches text patterns. It catches the forms listed above. Variations, such as sudo placed after another command on the same line, do not match. The Blocked Commands rule still asks Claude to confirm them with you.
• Hooks are registered by relative path. The hook commands in settings.json point to Infrastructure/Scripts/ relative to the folder Claude is working in. If Claude changes into a subfolder during a session, the hooks can no longer find their scripts and stop running without telling you. Ask Claude to return to the workspace folder, or start a new session. The future release below changes the hooks to absolute paths.
• Nothing checks what an agent sends to the web. That is the outbound guard’s job, and it is not in 3.0.2.
• No switch. Version 3.0.2 has no setting to turn the engine guard or the safety guard off.

Coming in a Future Release

Note

The outbound guard and the other additions in this section arrive in a future release. They are not in AI Business OS 3.0.2, and their details may change before release.

The outbound guard exists to stop an agent leaking your data when it searches the web or calls a web service. It runs before every terminal command, web fetch and web search that an agent makes. Your own requests in the main conversation are not checked. As currently prepared, it blocks an agent’s request when it contains any of the following.

• An identifier you have listed as your own, such as your name or email address, including encoded forms.
• Any email address or phone number.
• Something shaped like a password, key or token.
• The path of a file that holds secrets.
• An attempt to disguise the request as a web browser.
• Data pulled in from a file or another command.
• A command over 30,000 characters, or one written in a way that hides what it does.

If the guard itself fails, it lets the call through so your work continues. You can also switch it off for a single run.

The same release, as prepared, also brings these changes.

• Secret files. Rules in settings.json stop Claude reading files such as .env, SSH keys and cloud credentials.
• Your identifiers. A file of your own identifiers, which /setup asks you for.
• Setup scripts. An install script that registers the guard and an uninstall script that reverses it.
• Absolute paths. The engine guard and safety guard registered by absolute path, which closes the gap described above.
• Agent disclosure. A step in the Decomposition rule that shows you each agent’s job, tools and rules before it starts.
• Blocked commands. Two new rows in the Blocked Commands rule.
• A plain-words guide. A setup guide to the whole layer.

As prepared, it does not limit which websites agents may visit, and it does not check web calls that MCP servers make on their own. See Release Notes for what each version contains when it is published.

Adding Your Own Hooks

.claude/settings.json is a critical file, so the engine guard stops Claude editing it. If you want a hook of your own, add it to .claude/settings.local.json. That file stays on your computer, because the workspace .gitignore excludes it. When /update changes settings.json, it merges the file and keeps any hooks and permissions you added to it. See Configuration.