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

# Configuration

> Intercept works without configuration.

Every middleware package includes internal defaults that can be overridden via the constructor, so you can install the package and use the middleware immediately.

<Tip>
  Publishing the config is useful when you want global defaults across your
  application.
</Tip>

## Publish the config

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
php artisan vendor:publish --tag=intercept-config
```

This creates:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
config/intercept.php
```

## Configuration priority

Configuration is resolved in this order:

```mermaid placement="top-right" theme={"theme":{"light":"github-light","dark":"github-dark"}}
   flowchart LR
      A[constructor value] --> B[config value]
      B --> C[middleware default]
```

That means constructor values always win.

This gives you two levels of control:

1. global application defaults in `config/intercept.php`
2. per-agent overrides in middleware constructors

## Configuration examples

### Global config example

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
'injection_guard' => [
    'action' => 'block',
],

'pii_redactor' => [
    'action' => 'redact',
],
```

This sets defaults for every agent that uses these middleware classes.

### Per-agent override example

You can override global config for a specific agent:

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use PromptPHP\Intercept\InjectionGuard\PromptInjectionGuard;
use PromptPHP\Intercept\PIIRedactor\PIIRedactor;

public function middleware(): array
{
    return [
        new PromptInjectionGuard(
            action: 'log',
        ),

        new PIIRedactor(
            action: 'log',
            blockEntities: [],
        ),
    ];
}
```

Even if your config says `block` or `redact`, these constructor values take priority for this agent.

## Middleware configuration options

### Injection Guard options

| Option                    | Type     | Default | Description                                                |
| ------------------------- | -------- | ------- | ---------------------------------------------------------- |
| `action`                  | `string` | `block` | How to handle detected prompt injection attempts.          |
| `patterns`                | `array`  | `[]`    | Custom regex patterns.                                     |
| `merge_patterns`          | `bool`   | `true`  | Whether custom patterns are merged with built-in patterns. |
| `normalise_prompt`        | `bool`   | `true`  | Whether to normalise prompts before scanning.              |
| `log_prompt_preview`      | `bool`   | `false` | Whether logs may include a short prompt preview.           |
| `scan_approval_decisions` | `bool`   | `true`  | Whether to scan tool approval decisions on resumed runs.   |

Supported actions:

1. block
2. log
3. warn
4. sanitize

### PII Redactor options

| Option                    | Type     | Default                | Description                                              |
| ------------------------- | -------- | ---------------------- | -------------------------------------------------------- |
| `action`                  | `string` | `redact`               | How to handle detected PII.                              |
| `entities`                | `array`  | supported entities     | Which entity types to detect.                            |
| `block_entities`          | `array`  | high-risk entities     | Which entities should always block.                      |
| `allowed_emails`          | `array`  | `[]`                   | Email addresses that should not be redacted.             |
| `allowed_domains`         | `array`  | `[]`                   | Email domains that should not be redacted.               |
| `replacement_format`      | `string` | `[{{TYPE}}_{{INDEX}}]` | Placeholder format for redaction.                        |
| `mask_character`          | `string` | `*`                    | Character used when masking values.                      |
| `log_detections`          | `bool`   | `true`                 | Whether detections should be logged.                     |
| `log_preview`             | `bool`   | `false`                | Whether logs may include a short prompt preview.         |
| `scan_approval_decisions` | `bool`   | `true`                 | Whether to scan tool approval decisions on resumed runs. |

Supported actions:

1. redact
2. mask
3. log
4. block

Supported entities:

1. email
2. phone
3. credit\_card
4. ip\_address
5. api\_key
6. bearer\_token
7. mac\_address
8. url

### Tool Approval Guard options

| Option           | Type     | Default            | Description                                              |
| ---------------- | -------- | ------------------ | -------------------------------------------------------- |
| `action`         | `string` | `block`            | How to handle a flagged proposed tool call.              |
| `allowed_tools`  | `array`  | `[]`               | Tools that may be proposed. Empty permits every tool.    |
| `denied_tools`   | `array`  | `[]`               | Tools that may never be proposed.                        |
| `scan_pii`       | `bool`   | `true`             | Whether to scan proposed arguments for secret-like data. |
| `scan_injection` | `bool`   | `false`            | Whether to scan proposed arguments for injection.        |
| `entities`       | `array`  | high-risk entities | Which entity types to detect in arguments.               |
| `block_entities` | `array`  | high-risk entities | Which entities always block.                             |
| `log_preview`    | `bool`   | `false`            | Whether logs may include a short argument preview.       |

Supported actions:

1. block
2. log

Unlike the PII Redactor, `entities` defaults to only the high-risk set — `credit_card`, `api_key` and `bearer_token`. Contact data and locators are supported but opt-in, because in a proposed tool argument they are usually the tool's own parameters rather than an exfiltration signal. `scan_injection` is off by default for the same reason. See the [Tool Approval Guard guide](/middleware/tool-approval-guard#secret-like-data).

Note that `block_entities` stops the run whatever `action` is set to, so `action: 'log'` is only observe-only if you also set `block_entities` to `[]`.

This middleware acts on the response rather than the prompt, because the tool calls it guards are proposed by the model. It has no mutating action, since a proposed tool call belongs to the paused turn the provider recorded.

## Tool approval resumes

When an agent pauses for tool approval and is resumed with `Decisions`, the prompt text is empty. The new content is whatever a human supplied while resolving the pending tool calls: edited tool arguments and rejection results.

Intercept scans that content by default. Resumed prompts cannot be rewritten, so actions that modify the prompt degrade to logging on this path:

| Middleware      | Degrades to logging | Still blocks                      |
| --------------- | ------------------- | --------------------------------- |
| Injection Guard | `sanitize`, `warn`  | `block`                           |
| PII Redactor    | `redact`, `mask`    | `block`, and any `block_entities` |

Set `scan_approval_decisions` to `false` on either middleware to opt out.

## Recommended config

In my opinion, a good production default would be:

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
return [
    'middleware' => [
        'injection_guard' => [
            'action' => 'block',
            'log_prompt_preview' => false,
        ],

        'pii_redactor' => [
            'action' => 'redact',
            'block_entities' => [
                'credit_card',
                'api_key',
                'bearer_token',
            ],
            'log_detections' => true,
            'log_preview' => false,
        ],
    ],
];
```

This blocks prompt injection attempts, redacts common structured PII, blocks high-risk secrets, and avoids logging prompt previews.

## Config caching

After changing config in production, clear and rebuild your application cache as needed.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
php artisan optimize:clear
```

If your deployment process caches config, run:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
php artisan config:cache
```

## Next step

Explore the available [middleware collection](/middleware) to see which ones you need.

<Card title="Middleware collection" icon="shield" href="/middleware">
  Learn about the different middleware options available in Intercept.
</Card>