Hooks
Hooks are a safety net that runs beside the agent. Before certain actions happen, a hook looks at what is about to be done and can stop it.
They exist because the builder can only vouch for its own work. It cannot see a command the agent decides to run on its own, a file it edits by hand, or something pasted into the chat. Hooks watch exactly those three places, and they watch for one thing: Nuvei account details ending up somewhere they should never be.
They are optional. The setup step (nuvei-mcp-builder-init) installs them unless it
is given --no-hooks, and re-running it is safe.
What each hook watches
| Hook | Watches | Stops |
|---|---|---|
| Credentials guard | Commands the agent runs | Anything that would carry account details through the agent, read them out of the system keychain, or read them out of device logs |
| Files guard | Files the agent writes | A secret written into a file, and payment-signing code placed inside the app instead of the backend |
| Prompt guard | What the user types or pastes | An account secret pasted into the chat |
Each one is described below.
Credentials guard
Nuvei account details live in the computer's keychain, and the builder puts them where they need to go without ever showing them to the agent. This hook makes sure nothing goes around that.
It stops the agent from:
- starting the app with the credentials passed in by hand - the builder's own launch step does this properly, straight from the keychain;
- running the credential setup itself, rather than opening the separate terminal window where the values are typed in privately;
- searching device logs for secret values;
- reading the keychain entry, or printing out the environment to find a secret.
Files guard
Two things are never allowed to be written, anywhere in the project.
A payment signature inside the app. Signing a payment order needs the merchant secret key, and that key belongs on the server. Code that tries to produce the signature in the app is blocked. The app's own unrelated checksum code is not affected - only the combination of signing and a merchant secret.
A secret saved to a file. A file that is obviously a credential dump, or a secret written out with a real value next to it. Mentioning the name of a credential field is fine, which is why the generated code, full of field names, is never caught by this.
A .env file is not blocked just for existing - apps and servers legitimately have
one. If a real Nuvei secret is inside it, the builder still catches it the next time
it writes payment code or launches the app.
Prompt guard
This one catches the case nothing else can see: a secret pasted into the chat.
It is deliberately cautious. It reacts only when something clearly looks like a real secret value, never when a field is simply mentioned by name. If it does stop something, it says on screen what happened and points at the proper way to enter credentials - a separate terminal window that the agent cannot read.
The log
Every time a hook makes a decision, it writes one line to .nuvei/hooks.log: when
it happened, which hook it was, and what it decided. No secret is ever written
there. It is simply a record that can be looked at later, without having to
reproduce a session.
If something goes wrong
When a hook does stop something, the reason is handed back to the agent, so it can explain what happened and take the supported route instead.