Hooks

FlareCode ships with guardrails that hold — branch protection, a per-task cost cap, an egress denylist, secret-scrubbed logs. Hooks let you add your own policy on top, enforced at the points every agent has to pass through.

Where hooks run

Your agents reach models, MCP servers, and your repo through FlareCode's servers — that's how your API keys and secrets stay out of the sandbox. Hooks run at those same chokepoints, so an agent can't bypass them from inside the box. A hook fires on one of these moments:

• On a prompt — before a prompt reaches the agent's container.
• On an MCP call — before the agent calls a connected MCP server (matched by server).
• On a model call — before an inference request goes out (matched by model).
• On a goal finishing — when a goal reaches a terminal state (great for webhooks).

What a hook can do

• A builtin guardrail:
  • Egress denylist — block a prompt that references a denied host (SSRF / exfiltration).
  • Secret scan — block a prompt that contains an API key or secret.
  • Branch name — enforce your branch-naming convention.
  • Context inject — add a standing instruction to every model call.
• A webhook — POST the event to your own HTTPS endpoint and (optionally) let it decide allow/deny. The endpoint must be a public host (internal and cloud-metadata addresses are refused). Any bearer token you provide is encrypted at rest and only used server-side.

Add a hook

Go to Settings → Hooks, choose when it fires and what it does, and save. It takes effect immediately. A hook does nothing until you add it — with no hooks configured, agents behave exactly as before.

Security builtins (egress, secret scan, branch name) fail closed: if the check can't run, the action is blocked rather than allowed. Notification and enrichment hooks fail open so a flaky endpoint never stalls your agents, and a hook that keeps erroring is automatically skipped.

Worked examples

• Block exfiltration to a host you don't trust. Add an Egress denylist hook on the prompt event. Any prompt that references a denied host is rejected before it reaches the container.
• Stop secrets ending up in a prompt. Add a Secret scan hook on the prompt event. A prompt containing something that looks like an API key or token is blocked.
• Enforce your branch convention. Add a Branch name hook with a glob like feature/* so a goal that tries to land on an off-convention branch is stopped. (FlareCode already pins agents to flarecode/task-*; this is for teams with a stricter rule.)
• Add a standing instruction to every model call. Add a Context inject hook on the model event — e.g. "Always use our internal logger, never console.log." It's appended to the system context of each inference request.
• Notify your own system when a goal finishes. Add a Webhook hook on the goal finishing event pointed at your HTTPS endpoint.

You can scope any hook to a single agent or apply it across your whole account, and matchers narrow it further (a specific MCP server, a model id).

Your webhook contract

A webhook hook POSTs JSON to your endpoint. The body identifies what fired, never the raw prompt or any secret material:

{
  "event": "pre_tool_use",
  "hookName": "notify-finance-mcp",
  "userId": "...",
  "agentId": "..." ,
  "goalId": "...",
  "toolName": null,
  "model": null
}

If you set a bearer secret on the hook, it's sent as Authorization: Bearer <secret> (encrypted at rest, only used server-side). Your endpoint controls the outcome with its JSON response:

• { "ok": false, "reason": "..." } — block the action (returns 403 to the agent).
• { "systemContext": "..." } — inject that text into the model call.
• anything else (or ok: true) — allow.

Your endpoint must be a public HTTPS host — internal and cloud-metadata addresses are refused. The call has a short timeout and fails open: a slow or non-2xx response lets the action through, so a flaky endpoint never stalls your agents. Notification hooks are fire-and-forget and can never block.

Test before it blocks

A security builtin fails closed, so test a new rule before you rely on it: add it scoped to a single throwaway agent, run a task that should trip it, and confirm the action is blocked (you'll see a 403 in the agent's activity). For a webhook, start with an endpoint that always returns { "ok": true } to confirm delivery, then add your decision logic. A hook that errors repeatedly is auto-skipped, so a misconfigured endpoint won't wedge your fleet — but it also won't be enforcing anything until you fix it.

A note on local tool calls

Hooks gate the calls that leave the sandbox (prompts, model calls, MCP calls) and the goal lifecycle. They do not intercept the agent's individual in-container file edits or shell commands before they run — the underlying agent runtime doesn't expose that. The platform guardrails (branch protection, cost cap, egress, log scrubbing) still bound what those local actions can ultimately do.

Related

• Security model — the built-in guardrails hooks build on.
• Recurring workflows — hooks apply to loop iterations too.