> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Evaluate Claude Code prompts, commands, and tool results with TrustGuard, and connect the CLI to TrustGate over MCP

Claude Code is Anthropic's coding agent. It can read repositories, edit files,
run shell commands, and call external tools from a developer's terminal.

The TrustGuard plugin evaluates these actions through lifecycle hooks on the
machine where Claude Code runs. TrustGate provides access to the MCP tools
assigned to a consumer. For organization-wide inference hooks or managed MCP
connectors, see [Claude Enterprise](/integrations/claude-enterprise).

## NeuralTrust controls

| Product                                | Scope                                                                                                                                                                     | Controls                                                         |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **[TrustGuard](/trustguard/overview)** | Evaluates prompts, commands, tool calls, and tool results against an organization [policy](/trustguard/concepts/policies).                                                | Monitor · Block · Ask on tool calls                              |
| **[TrustGate](/trustgate/overview)**   | Exposes the MCP registries and tools assigned to a consumer. MCP (Model Context Protocol) connects Claude Code to systems such as trackers, databases, and internal APIs. | Tool availability · identity-based access · per-tool rate limits |

Use the TrustGuard plugin to evaluate individual actions. Add TrustGate when
Claude Code needs controlled access to MCP tools. Each has its own configuration
and credentials.

<Warning>
  TrustGuard uses a `tgk_…` [collector](/trustguard/concepts/collectors) key in
  `claude-code.json`. TrustGate authenticates MCP consumers with OAuth2 or an
  `ag_…` API key. A `tgk_…` key does not authenticate MCP, and the plugin's managed
  settings do not accept an MCP URL.
</Warning>

## Before you start

| Requirement                                                    | Notes                                                                                                                                                                                    |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Egress to `{TRUSTGUARD_BASE_URL}`                              | The console shows the [base URL](/trustguard/api/evaluate#base-url) for your workspace. The plugin calls it from the machine where Claude Code runs.                                     |
| The **Claude Code** collector type                             | **Agent Runtime → Collectors → Catalog → AI assistants & coding agents → Claude Code**. Create its `tgk_…` key on **Auth** and assign the policy on **Policies**. The key is shown once. |
| MDM                                                            | Deploys `claude-code.json`, and optionally `managed-settings.json` and a pinned binary.                                                                                                  |
| Egress to GitHub Releases                                      | On first use the plugin bootstrap downloads the platform `trustguard-claude-code` binary.                                                                                                |
| An [MCP consumer](/trustgate/mcp/overview), if using TrustGate | Bind the required registries, then copy the endpoint from its **Connect** tab.                                                                                                           |

<Note>
  Create the policy in **Observe** mode. Observe records decisions in **Activity**
  without enforcing them. Review the results, then switch the policy to
  **Enforce**. See [Policies](/trustguard/concepts/policies).
</Note>

Developers do not need NeuralTrust accounts to use the TrustGuard plugin.
OAuth-backed MCP consumers require a login against the IdP configured for the
consumer, which may be NeuralTrust.

## TrustGuard plugin

The [Claude Code plugin](https://github.com/NeuralTrust/trustguard-claude-code-plugin)
registers lifecycle hooks on the developer's machine. Before an action runs,
each hook calls [`POST /v1/evaluate`](/trustguard/api/evaluate) with a collector
`tgk_…` key. Unlike the [Enterprise inference
hook](/integrations/claude-enterprise#inference-hook), the plugin receives shell
commands and supports Ask on tool calls.

Hooks fire only when all three pieces are present:

| Piece                               | What                                                                       | If missing                                                 |
| ----------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Plugin** `trustguard@neuraltrust` | Registers `hooks.json`                                                     | Claude Code never calls the bootstrap                      |
| **Binary** `trustguard-claude-code` | MDM `/Library/Application Support/TrustGuard/bin/`, or `~/.trustguard/bin` | Bootstrap fail-opens (`{}`)                                |
| **Collector key** `tgk_…`           | In `claude-code.json`                                                      | Binary runs and allows the action without calling evaluate |

1. **Enable the plugin.** Deploy this through server-managed settings (claude.ai
   **Admin → Claude Code → Managed settings**) or as the file
   `/Library/Application Support/ClaudeCode/managed-settings.json`:

   ```json theme={null}
   {
     "extraKnownMarketplaces": {
       "neuraltrust": {
         "source": {
           "source": "github",
           "repo": "NeuralTrust/trustguard-claude-code-plugin"
         },
         "autoUpdate": true
       }
     },
     "enabledPlugins": {
       "trustguard@neuraltrust": true
     }
   }
   ```

   Do not add `pluginConfigs`, `mcpServers`, or an MCP URL. Organization-wide MCP
   access uses a separate [organization
   connector](/integrations/claude-enterprise#organization-connectors).

2. **Deploy the collector config** with MDM, and optionally pin the binary:

   ```json theme={null}
   {
     "data_url": "https://<your-trustguard-host>",
     "api_key": "tgk_…",
     "fail_mode": "open"
   }
   ```

   | OS      | Config                                                     | Binary (optional pin)                     |
   | ------- | ---------------------------------------------------------- | ----------------------------------------- |
   | macOS   | `/Library/Application Support/TrustGuard/claude-code.json` | `…/TrustGuard/bin/trustguard-claude-code` |
   | Linux   | `/etc/trustguard/claude-code.json`                         | `~/.trustguard/bin/`                      |
   | Windows | `%ProgramData%\TrustGuard\claude-code.json`                | `%ProgramData%\TrustGuard\bin\`           |

3. **Confirm the plugin is enabled.** An installed plugin, including one with
   `Scope: managed`, does not run until its status is `enabled`:

   ```bash theme={null}
   # Inside `claude`: /status  →  Enterprise managed settings: remote  (or file)
   claude plugin list          # Status: enabled
   claude plugin enable trustguard@neuraltrust   # if still disabled
   ```

4. **Start a new Claude Code session** so `hooks.json` loads.

<Warning>
  `enabledPlugins: true` in the admin JSON does not always enable the plugin in
  the CLI. Claude Code skips server-managed settings entirely when
  `ANTHROPIC_BASE_URL` or any `CLAUDE_CODE_USE_*` variable is set. This includes
  sessions pointed at a TrustGate LLM proxy. Deploy the file path instead in
  that case.
</Warning>

## Connect to TrustGate

For centrally managed access, use a [Claude organization
connector](/integrations/claude-enterprise#organization-connectors). Claude Code
loads that connector after the user completes the connection. Confirm in `/mcp`
that TrustGate is the **org** connector, not *"Provided by a plugin"*.

For local testing, add the MCP consumer directly to the CLI. This does not
replace the organization connector. Copy the endpoint from the consumer's
**Connect** tab:

```bash theme={null}
claude mcp add --transport http TrustGate https://<mcp-host>/<consumer-slug>/mcp
```

An API-key consumer sends the key as a header:

```bash theme={null}
claude mcp add --transport http TrustGate https://<mcp-host>/<consumer-slug>/mcp \
  --header "X-AG-API-Key: ag_…"
```

On a private (Hybrid) data plane, add
`--header "X-AG-Gateway-Slug: <gateway-slug>"` as well.

## Verify

### TrustGuard plugin

Check that the binary and collector config are installed, then send a test
lifecycle event:

```bash theme={null}
ls -l "/Library/Application Support/TrustGuard/bin/trustguard-claude-code"
cat "/Library/Application Support/TrustGuard/claude-code.json"   # data_url + tgk_ prefix only

echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"},"session_id":"pilot"}' \
  | trustguard-claude-code hook
```

A manual probe that shows up in **Activity** with
`source.application = claude-code-plugin` means the binary and key work. If
Claude Code still never evaluates, the plugin is disabled or hooks did not
reload.

### TrustGate MCP connection

1. Confirm that `/mcp` lists TrustGate, then call a tool from a bound registry.
2. Confirm the call in TrustGate telemetry. See
   [Metrics](/trustgate/observability/metrics).

## Reference

### Coverage

This table describes the TrustGuard plugin, not the TrustGate MCP connection.

| Surface     | Monitor | Block | Redact |
| ----------- | :-----: | :---: | :----: |
| LLM input   |    ✅    |   ✅   |    ❌   |
| LLM output  |    ➖    |   ➖   |    ➖   |
| Tool call   |    ✅    |   ✅   |    ❌   |
| Tool result |    ✅    |   ✅   |    ❌   |

**Ask.** The plugin honors Ask on tool calls by raising Claude Code's native
permission dialog. The subtitle is the generic TrustGuard sentence
`A TrustGuard policy needs your approval to continue.`; the title is Claude
Code's tool name and the plugin cannot change it. An `ask` on
`UserPromptSubmit` does not stop the prompt. Claude Code has no confirmation
dialog for that event, so it submits the prompt with a warning. Use a **Block**
gate to stop a prompt.

**Limits.** The plugin does not support redaction or evaluate tool declarations.
There is no hook for assistant output, so model responses, system prompts,
token usage, and extended thinking are not evaluated. Route MCP through
TrustGate if you need controls over the available tool set. The plugin does
not run in claude.ai or Desktop; use the [Enterprise inference
hook](/integrations/claude-enterprise#inference-hook) to evaluate model requests
across the organization.

### What is evaluated

The plugin sends one evaluation call per lifecycle hook.

| Claude Code event                  | TrustGuard                                                      | What you can stop                                                                                                                                                                         | Enforcement                                 |
| ---------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `UserPromptSubmit`                 | `protocol: llm`, `direction: input`                             | Jailbreaks ([Prompt Guard](/trustguard/detectors/content-security#prompt-guard--prompt_guard)); secrets and PII pasted into the agent ([DLP](/trustguard/detectors/data-loss-prevention)) | **Block** only                              |
| `PreToolUse` (`Bash` / `Shell`)    | `protocol: all`, `{ "input": "<command>" }`, `direction: input` | Dangerous or out-of-policy shell commands. The full command line is `tool.command`, and `tool.name` is `Bash`                                                                             | **Block** or **Ask**                        |
| `PreToolUse` (MCP and other tools) | `protocol: mcp`, `tools/call`, `direction: input`               | Risky MCP tool calls                                                                                                                                                                      | **Block** or **Ask**                        |
| `PostToolUse`                      | `protocol: mcp`, tool result, `direction: output`               | [Indirect prompt injection](/trustguard/detectors/agent-mcp-security) in MCP or tool output, and sensitive data in results, before the model consumes it                                  | **Block**. Ask gates do not match on output |

`tool.name` is `payload.params.name`: for `mcp__<server>__<tool>` that is the
last segment. Gate on that short name, not the full hook `tool_name`. The
policy's [detectors](/trustguard/concepts/detectors) decide the verdict.

### Configuration

**Managed settings (plugin enablement only).** `managed-settings.json` carries
`extraKnownMarketplaces` and `enabledPlugins`. It does not hold a collector key
or an MCP URL.

**`claude-code.json` (TrustGuard collector only).** Keys: `data_url`, `api_key`,
`fail_mode`. When the managed file contains `api_key`, that key plus `data_url`
and `fail_mode` are locked. A user file cannot replace them.
`fail_mode: open` plus an empty hook body `{}` means allow; that is also the
response when evaluate returns `allow`.

**Binary discovery.** The MDM path is checked first, then `~/.trustguard/bin`.
The user path is not required when the MDM binary exists. On a private
fork of the plugin repository, an unauthenticated GitHub Releases request may
return `404`. Set `TRUSTGUARD_GITHUB_TOKEN` and pin the release version. If the
download fails, the bootstrap fails open.

**Remote sessions.** Over SSH or WSL, the hooks run on the remote host. An
MDM-deployed binary on the Mac does not cover that session. The config and
binary must exist where the agent runs.

**MCP auth.** The CLI accepts OAuth2 or an `ag_…` consumer key as
`X-AG-API-Key`. A private data plane needs `X-AG-Gateway-Slug` unless the MCP
host already scopes the [gateway](/trustgate/concepts/gateways). Which IdP backs
the OAuth login is configured on the consumer. See
[Auth](/trustgate/concepts/auth). Authenticating to TrustGate is separate from
authenticating to the upstream servers; a registry using OAuth (forwarded)
returns a connect link on the first call for a user without a stored credential.

**Deployment ownership.** IT manages plugin enablement through
`managed-settings.json` or server-managed settings, and deploys the organization
collector key in `claude-code.json` through MDM. An Anthropic organization owner
manages [organization connectors](/integrations/claude-enterprise#organization-connectors).

Configure the consumer's available tools under **Routing** in the NeuralTrust
console, or through a [role](/trustgate/concepts/roles) for Identity-based consumers.
To limit MCP tool calls, attach the [Per-Tool Rate
Limiter](/trustgate/policies/tool-governance) policy.

### Attributes

The plugin stamps `source.application = claude-code-plugin` and a
per-developer `consumer_id`. These values provide per-developer attribution in
**Activity**.

A gate on `claude-code` does not match the plugin. That value identifies Claude
Code requests seen server-side by the Enterprise inference hook. Use a
collector and default policy for each integration path, and configure their
gates separately.

To target the plugin, create a [gate](/trustguard/concepts/policies#gates) with
`source.application` **eq** `claude-code-plugin`, then choose **Ask** or **Block**
as appropriate for the event. The field is under **Policies → Gates → Source
application**. Gates run before detectors. In **Observe** mode, Block is recorded
but not enforced. Test the condition on the policy **Test** tab with Extra
parameter **Source application** set to `claude-code-plugin`.

### Troubleshooting

| Symptom                                                 | Cause                                                                                                                                                    |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| An `ask` gate on a prompt did not stop it               | There is no confirmation dialog at `UserPromptSubmit`. Use a **Block** gate                                                                              |
| A gate on `claude-code` never fires for the plugin      | The plugin stamps `claude-code-plugin`. `claude-code` is Claude Code seen server-side                                                                    |
| `claude plugin list` shows the plugin, no hooks fire    | Status is `installed`, not `enabled`. Run `claude plugin enable trustguard@neuraltrust`, then start a new session                                        |
| Managed settings ignored                                | `ANTHROPIC_BASE_URL` or a `CLAUDE_CODE_USE_*` variable is set, so Claude Code skips server-managed settings. Deploy the file instead                     |
| Hooks fire but nothing reaches **Activity**             | `claude-code.json` has no `tgk_…` key, so the binary allows without calling evaluate, or `data_url` is incorrect                                         |
| Hooks work locally but not over SSH / WSL               | Hooks run on the remote host. The binary and config have to be there                                                                                     |
| Bootstrap returns `{}` without running the binary       | An unauthenticated GitHub Releases request can return `404` for a private fork. Set `TRUSTGUARD_GITHUB_TOKEN`; otherwise the bootstrap allows the action |
| The plugin evaluates nothing in claude.ai or Desktop    | Those surfaces have no lifecycle hooks. Use [Claude Enterprise](/integrations/claude-enterprise)                                                         |
| Claude Code shows TrustGate as *"Provided by a plugin"* | This is a local `claude mcp add` entry, not the organization connector. Confirm in `/mcp`                                                                |
| MCP connects, no tools                                  | Consumer has no bound registries, tool restrictions exclude everything, or the upstream connect link was never authorized                                |
| `401` / repeated login on MCP                           | Wrong plane URL, revoked `ag_…` key, or `X-AG-Gateway-Slug` missing on Hybrid                                                                            |

## Related

* [Claude Enterprise](/integrations/claude-enterprise): organization inference hooks and managed MCP connectors
* [Policies: Gates](/trustguard/concepts/policies#gates): Ask and Block configuration, including `source.application` values
* [Evaluate API](/trustguard/api/evaluate): requests sent by the plugin hooks
* [Collectors](/trustguard/concepts/collectors): collector types and keys
* [MCP overview](/trustgate/mcp/overview): consumers, catalog merging, and upstream authentication
* [TrustGate authentication](/trustgate/concepts/auth): API key and OAuth2 authentication for MCP consumers
* [How TrustGuard works](/trustguard/how-it-works): evaluation and enforcement across integrations
* [Plugin repository](https://github.com/NeuralTrust/trustguard-claude-code-plugin): source, releases, and the hook contract