@@ -7,14 +7,15 @@ Each skill ships in the open [Agent Skills](https://agentskills.io/) format and
 ## Skills
 
 <details>
-<summary><b>superagent</b>: configure Superagent MCP and signed webhooks safely</summary>
+<summary><b>superagent</b>: configure MCP, context hooks, and signed webhooks safely</summary>
 
-Use it when you want to connect Cursor, Claude Code, Codex CLI, or another MCP client to Superagent, set up signed webhook notifications, troubleshoot the connection, inspect findings and reports, scan context, check Contributor Trust, or manage Runtime Guardrails.
+Use it when you want to connect Cursor, Claude Code, Codex CLI, or another MCP client to Superagent, enforce Context Guardrails through coding-agent hooks, set up signed webhook notifications, troubleshoot the connection, inspect findings and reports, scan context, check Contributor Trust, or manage Runtime Guardrails.
 
-This is an explicit, opt-in remote integration. It never connects, sends data, changes MCP configuration or organization webhooks, spends organization credits, deletes findings, or changes endpoint policy without the user's request and the required confirmation. API keys and webhook signing secrets stay out of tracked configuration.
+This is an explicit, opt-in remote integration. It never connects, sends data, changes MCP or hook configuration or organization webhooks, spends organization credits, deletes findings, or changes endpoint policy without the user's request and the required confirmation. API keys and webhook signing secrets stay out of tracked configuration.
 
 ```
 Connect Cursor to the Superagent MCP server
+Add Context Guardrails to my coding agent's hooks
 Set up a signed webhook for completed finding triage
 List my unresolved high-risk Superagent findings
 Scan this skill with Superagent Context Guardrails
 
@@ -1,21 +1,31 @@
 ---
 name: superagent
-description: Configure and safely use Superagent's remote MCP server and webhooks for findings, security reports, Contributor Trust, Context Guardrails, and Runtime Guardrails. Use when the user asks to install, connect, configure, troubleshoot, operate, or set up webhook notifications for Superagent from Cursor, Claude Code, Codex CLI, or another MCP client.
+description: Set up Superagent Context Guardrails at coding-agent tool boundaries, configure and safely use the remote MCP server, and manage signed webhooks for findings, security reports, Contributor Trust, and Runtime Guardrails. Use when the user asks to enable context scanning before an agent consumes URLs, files, email, skills, or MCP repositories; integrate coding-agent hooks; or install, connect, configure, troubleshoot, or operate Superagent from Cursor, Claude Code, Codex CLI, or another MCP client.
 ---
 
-# Superagent MCP
+# Superagent
 
-Connect a coding agent to Superagent, then use its MCP tools without exposing
-credentials or surprising the user with remote, billable, destructive, or
-policy-changing actions.
+Set up Context Guardrails so external context is checked before a coding agent
+consumes it, connect the agent to Superagent over MCP, or configure signed
+webhooks. Keep credentials protected and avoid surprising the user with remote,
+billable, destructive, or policy-changing actions.
 
 Superagent MCP is an authenticated remote service. Do not connect to it, send
 it data, or change an MCP client configuration unless the user explicitly asks.
 
-## Setup workflow
+Route setup requests by intent:
 
-1. Identify the MCP client and whether the user wants setup, troubleshooting,
-   or an operation on an existing connection.
+- **Context Guardrails setup or coding-agent hooks**: follow
+  [Context Guardrails integration](#context-guardrails-integration). Connecting
+  MCP alone does not enforce pre-consumption checks.
+- **Connect or troubleshoot Superagent MCP**: follow
+  [MCP setup workflow](#mcp-setup-workflow).
+- **Signed event delivery**: follow [Webhook setup](#webhook-setup).
+
+## MCP setup workflow
+
+1. Identify the MCP client and whether the user wants a new connection,
+   troubleshooting, or an operation on an existing connection.
 2. For setup, direct the user to create an organization API key at
    [Superagent Settings](https://www.superagent.sh/app/settings#api-keys).
    Never ask them to paste the key into chat.
@@ -109,6 +119,125 @@ result and preserve identifiers the user needs for a follow-up. For
 asynchronous operations, report the returned status or identifier and avoid
 tight polling.
 
+## Context Guardrails integration
+
+Distinguish a one-off scan from enforcement:
+
+- For "scan/check this URL, file, email, skill, or MCP repository," use the
+  corresponding MCP tool.
+- For "add/enable/integrate Context Guardrails," install a check at the tool
+  boundary before the agent consumes the context. A `SKILL.md`, `AGENTS.md`,
+  rule, or system prompt is guidance, not enforcement.
+
+Use this setup workflow:
+
+1. Ask which context origins to protect, whether the setup is project-local or
+   global, and whether an unavailable scanner should block the action. Recommend
+   fail-closed for security-sensitive workflows and user-level or managed hooks
+   for controls that use an organization API key. Use project hooks only in a
+   trusted repository.
+2. Inspect the client's current hook configuration and supported events. Merge
+   with existing configuration; never replace it wholesale.
+3. Gate the action that introduces context, before consumption: web-fetch and
+   `curl`/`wget` actions for pages, download actions for public files, skill
+   installation for skills, MCP add/install configuration for MCP repositories,
+   and the inbound-message wrapper for email. Do not treat every later MCP tool
+   call as a repository scan.
+4. Map each selected origin to the narrowest client pre-execution boundary:
+   - Cursor: `preToolUse`, `beforeShellExecution`, or `beforeMCPExecution`.
+   - Claude Code: `PreToolUse` matched to `WebFetch`, `Bash`, `Skill`, or the
+     relevant MCP tool.
+   - Codex CLI: `PreToolUse` for supported local and MCP tools. Hosted
+     `WebSearch` is not hookable, so disclose that gap instead of claiming full
+     coverage.
+   - Other clients: their equivalent before-tool hook, wrapper, middleware, or
+     enforced rule plus an approved wrapper.
+5. Show the exact hook, helper, paths, scope, verdict policy, outage behavior,
+   and known coverage gaps. Obtain approval before writing files, changing
+   client configuration, or sending a test target to Superagent.
+6. For enforced hooks, install a small local helper that calls the Context
+   Guardrails REST API with `SUPERAGENT_API_KEY`. Some clients support MCP-backed
+   hook handlers, but a scan tool's result is not automatically a client-specific
+   allow or deny decision, and MCP errors may fail open. Use MCP directly for
+   interactive scans, not as the cross-client enforcement adapter. Keep the key
+   in the environment, never in the helper or hook configuration. Prefer a
+   user-controlled helper outside the repository and reference it by absolute
+   path so repository code cannot silently replace it.
+7. Test one allowed target and one blocked or unresolved target, then restart
+   or reload the client if its hook system requires it. Use the client's hook
+   inspector when available and verify the action itself was blocked, not merely
+   that the helper printed a warning.
+
+The helper must call the matching `/api/v1/context/*` endpoint:
+
+- Web page URL -> `GET /context/web_page/{identifier}`
+- Public text or PDF URL -> `POST /context/file`
+- Raw RFC 822 email -> `POST /context/email`
+- skills.sh or public GitHub skill -> `POST /context/skill`
+- Public GitHub MCP repository -> `POST /context/mcp`
+
+Skill and MCP scans support public GitHub targets only and require an active
+Superagent Security GitHub App installation. Verify that prerequisite before
+claiming those hook paths are enforced. Keep agent lifecycle hooks distinct
+from package, Git, or other install hooks found inside scanned content; the
+latter are threat signals.
+
+Do not upload local private files through the public-URL file scanner, and get
+explicit authorization before sending raw email or other user content. Package
+and general repository scanning are not Context Guardrails origins: use
+Superagent supply-chain scanning for packages and repository reports for source
+repositories. Do not port an old package-install hook and claim that Context
+Guardrails scanned the package.
+
+For an enforcement decision, parse the JSON response rather than relying only
+on score headers. Apply the selected tolerance consistently:
+
+- `safe`: allow.
+- `caution`: require user review unless the user explicitly chose a different
+  policy.
+- `suspicious` or `dangerous`: deny.
+- `pending_deep_scan: true`, unscannable results, malformed responses, and
+  scanner timeouts: treat as unresolved and follow the approved outage policy.
+
+Do not let a preliminary identity score silently allow consumption while the
+deep scan is pending. Either request `mode=full` with a hook timeout long enough
+for completion, or block/ask and tell the agent to retry after the asynchronous
+scan finishes. Exempt the Superagent scanner calls themselves from generic MCP
+gates to avoid recursive checks.
+
+### Hook safety requirements
+
+Follow the installed client's current hook schema rather than copying one
+client's JSON response into another:
+
+- Use narrow, anchored tool matchers and command predicates. Broad hooks add
+  latency and create bypasses or accidental blocks.
+- Parse stdin as structured JSON. Never use `eval`, shell interpolation, or
+  string-built commands with untrusted tool input. URL-encode identifiers and
+  pass values as quoted arguments or request bodies.
+- Emit only the client's documented decision JSON on stdout; send diagnostics
+  to stderr. Treat malformed input and output as a security failure under the
+  chosen outage policy.
+- Use one bounded HTTPS request with explicit connection and total timeouts.
+  Do not log authorization headers, raw email, or response bodies containing
+  user content.
+- Do not let hook configuration auto-approve an action that the client's normal
+  permission system denies. Context Guardrails should only add restrictions.
+
+Apply platform failure behavior explicitly:
+
+- **Cursor:** security hooks fail open on crashes, timeouts, and invalid JSON
+  unless the hook sets `failClosed: true`. Set it for enforced boundaries.
+  `permission: "ask"` is not enforced for `preToolUse`; when review is required,
+  use a boundary that supports asking or deny with a clear review instruction.
+- **Claude Code:** use a `PreToolUse` denial response or exit code `2` for a hard
+  block. A timed-out command, HTTP, or MCP-tool hook continues through normal
+  permission flow, so timeout alone is not fail-closed. Keep normal permission
+  rules in place as defense in depth.
+- **Codex CLI:** use the documented `PreToolUse` denial JSON or exit code `2`
+  with the reason on stderr. Invalid fields and hook failures can continue the
+  tool call. Hosted tools such as `WebSearch` remain outside hook coverage.
+
 ## Webhook setup
 
 Use webhooks when the user wants Superagent events delivered to an agent,
@@ -196,3 +325,7 @@ Tool annotations are hints, not a substitute for this gate.
 - [Findings](https://www.superagent.sh/docs/findings)
 - [Red Team reports](https://www.superagent.sh/docs/red-team)
 - [Context Guardrails](https://www.superagent.sh/docs/context-guardrails)
+- [Context Guardrails API](https://www.superagent.sh/docs/api/context-guardrails)
+- [Cursor hooks](https://cursor.com/docs/hooks)
+- [Claude Code hooks](https://code.claude.com/docs/en/hooks)
+- [Codex CLI hooks](https://developers.openai.com/codex/hooks)