Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Template-refusal-securityerror · L-260929-75ff75 (#1440)

Louis Choquel03839b2d249d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1d5d9dede..e9c4414f1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [Unreleased]
+
+### Changed
+
+- **`Jinja2TemplateSecurityError` is a `SecurityError` (Breaking)**: the template sandbox's refusal at render time now derives from `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, instead of `ToolError`, so a host catching `SecurityError` catches it too and an `except ToolError` no longer does; it stays a type of its own, apart from `Jinja2TemplateRenderError`, and its `error_type`, title and classification are unchanged.
+
## [v0.89.0] - 2026-10-17
### Added
diff --git a/docs/errors/jinja2-template-security-error.md b/docs/errors/jinja2-template-security-error.md
index 0f80b0d9d..be5cd4879 100644
--- a/docs/errors/jinja2-template-security-error.md
+++ b/docs/errors/jinja2-template-security-error.md
@@ -14,6 +14,6 @@ description: "Reference for the `Jinja2TemplateSecurityError` Pipelex error clas
| `type_uri` | `https://docs.pipelex.com/latest/errors/jinja2-template-security-error/` |
| `error_domain` | _(inherited from parent)_ |
| Defined in | `pipelex.tools.jinja2.exceptions` |
-| Parent class | [`ToolError`](tool-error.md) |
+| Parent class | [`SecurityError`](security-error.md) |
[Back to Error Reference](index.md)
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 16e46ca8e..38d988607 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -486,6 +486,10 @@ Exception
└── PipelexError base_exceptions.py — error_domain, user_action, to_error_report()
├── PipelexConfigError → error_domain = CONFIG
├── PipelexSetupError → error_domain = CONFIG
+ ├── SecurityError base_exceptions.py — the policy refusals never absorbed into a domain answer
+ │ ├── UriReadRefusedError / SsrfBlockedError → error_domain = INPUT, caller-facing message
+ │ ├── UnsafeSchemaError
+ │ └── Jinja2TemplateSecurityError ← the template sandbox's refusal at render time
├── CogtError cogt/exceptions.py — error_category, provider_metadata
│ │ → error_domain derived from error_category (no per-class declaration)
│ ├── LLMCompletionError ← per-instance category from the worker → per-instance domain
@@ -500,6 +504,8 @@ Exception
└── ... (one exceptions.py per package) ...
```
+`SecurityError` is the base class of the policy refusals that are never absorbed into a domain answer: `UriReadRefusedError` (a read outside the run's scope), `SsrfBlockedError` (an outbound request the SSRF guard blocks), `UnsafeSchemaError` (a schema carrying Python code-generation extensions) and `Jinja2TemplateSecurityError` (a template the sandbox refuses at render time). The handlers that turn a refusal of the caller's input into a verdict, the bundle-validation cascade and the library load, let a `SecurityError` through as it is, and a host that treats this family alike, a durable-execution plugin marking it non-retryable for instance, names that base class. Not every refusal belongs to it: the template sandbox's render-budget refusal, `Jinja2TemplateBudgetError`, is a `ToolError` in the `input` domain, and `TemplateUrlRefusedError` derives from `PipelexError` directly, also in the `input` domain, so each is handled by its domain like any other refusal of the caller's input.
+
`PipelineExecutionError`'s `RUNTIME` is deliberately a *floor*, applied only when the cause chain surfaced no domain — so a `CONTENT`-categorized inference failure now reaches the HTTP boundary as `INPUT` / 422 through every wrapping layer instead of being flattened to the wrapper's generic 500. Its identity and message are its root fault's (see [Run Failures: the Root Fault, Located](#run-failures-the-root-fault-located)).
### Factory-time vs Runtime
diff --git a/docs/under-the-hood/template-sandbox.md b/docs/under-the-hood/template-sandbox.md
index 56f631521..7f35e043e 100644
--- a/docs/under-the-hood/template-sandbox.md
+++ b/docs/under-the-hood/template-sandbox.md
@@ -44,6 +44,8 @@ Many refusals are visible in the template itself, and validation reports them be
What validation cannot see, because it depends on the values at run time (a method call, a name computed while rendering, or a bracketed key, which is legitimate on a plain dict), is refused where it happens: the render raises [`Jinja2TemplateSecurityError`](../errors/jinja2-template-security-error.md), whose message names the refused attribute or callable and the type it was reached on. A refusal never renders as an empty string, so a prompt is never sent with a hole in it.
+`Jinja2TemplateSecurityError` is a [`SecurityError`](../errors/security-error.md), like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, the other policy refusals that are never absorbed into a domain answer. A host that treats that family alike, never retrying any of it, catches that base class, and an `except ToolError` around a render does not catch this refusal. The sandbox's budget refusal is a separate error, `Jinja2TemplateBudgetError`, which is a `ToolError` in the input domain (see below). `Jinja2TemplateSecurityError` stays a type of its own, apart from `Jinja2TemplateRenderError`, which a template that fails for any other reason raises.
+
A render that would overdraw its budget raises [`Jinja2TemplateBudgetError`](../errors/jinja2-template-budget-error.md), in the input domain, whose message names the operation that was refused and what it would have spent, never the template or a value: for example, *the operator '\*' needs about 1,000,000,000, and 134,217,062 are left*. A template whose macros or includes nest deeper than Python allows raises the same error.
## How it is built
diff --git a/pipelex/tools/jinja2/exceptions.py b/pipelex/tools/jinja2/exceptions.py
index 331a1d2f6..ef63f80ad 100644
--- a/pipelex/tools/jinja2/exceptions.py
+++ b/pipelex/tools/jinja2/exceptions.py
@@ -1,4 +1,4 @@
-from pipelex.base_exceptions import ErrorDomain
+from pipelex.base_exceptions import ErrorDomain, SecurityError
from pipelex.system.exceptions import ToolError
@@ -15,11 +15,13 @@ class Jinja2TemplateRenderError(ToolError):
pass
-class Jinja2TemplateSecurityError(ToolError):
+class Jinja2TemplateSecurityError(SecurityError):
# A template reached for something the sandbox policy refuses (`jinja2_sandbox.py`): an undeclared
# private name, or a call that is not a method of a plain value. Its message names the attribute or
# the callable and the type it was reached on, and never quotes the template source, since the same
- # render serves Pipelex's own templates. A type of its own, apart from `Jinja2TemplateRenderError`,
+ # render serves Pipelex's own templates. A `SecurityError`, not a `ToolError`, in the family of
+ # `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, so that a host catching that family
+ # never absorbs it into a domain answer and never retries it. A type of its own, apart from `Jinja2TemplateRenderError`,
# so that the classification of render-time template failures can tell a refusal from the rest,
# although for now both are classified alike: runtime domain, message not caller-facing.
pass
diff --git a/pipelex/tools/jinja2/jinja2_sandbox.py b/pipelex/tools/jinja2/jinja2_sandbox.py
index 4008047e0..8485039ca 100644
--- a/pipelex/tools/jinja2/jinja2_sandbox.py
+++ b/pipelex/tools/jinja2/jinja2_sandbox.py
@@ -23,8 +23,9 @@ forge content, such as an image pointing at another organisation's storage key.
pydantic methods, `Stuff` and content methods, classes, free functions and class methods, every
method that changes a list, a dict or a set in place, and the few that produce bytes.
- **Refusing.** A refusal raises `jinja2.exceptions.SecurityError` at the point of access, which the
- render functions turn into `Jinja2TemplateSecurityError`. Jinja's stock sandbox returns an undefined
- value that prints as nothing, which would send a prompt with a hole in it.
+ render functions turn into `Jinja2TemplateSecurityError`, a Pipelex `SecurityError` like the runtime's
+ other policy refusals. Jinja's stock sandbox returns an undefined value that prints as nothing, which
+ would send a prompt with a hole in it.
- **Spending.** What a template may reach says nothing about what it may spend, so every render also
spends from one budget (`jinja2_render_budget.py`), charged by the hooks of this class, by wrappers
around every filter and test, and by a rewrite of the parsed template for what no hook reaches
diff --git a/tests/unit/pipelex/tools/test_jinja2_sandbox.py b/tests/unit/pipelex/tools/test_jinja2_sandbox.py
index 8a232be38..82377c229 100644
--- a/tests/unit/pipelex/tools/test_jinja2_sandbox.py
+++ b/tests/unit/pipelex/tools/test_jinja2_sandbox.py
@@ -10,6 +10,7 @@ from typing import Any
import pytest
+from pipelex.base_exceptions import SecurityError
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.native.concept_native import NativeConceptCode
from pipelex.core.stuffs.composite_content import CompositeContent
@@ -19,6 +20,7 @@ from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_artefact import StuffArtefact
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.text_content import TextContent
+from pipelex.system.exceptions import ToolError
from pipelex.tools.jinja2.exceptions import Jinja2TemplateRenderError, Jinja2TemplateSecurityError
from pipelex.tools.jinja2.image_registry import ImageRegistry
from pipelex.tools.jinja2.jinja2_models import Jinja2ContextKey
@@ -256,6 +258,21 @@ class TestTemplateSandbox:
templating_context=_make_context(),
)
+ def test_refusal_is_a_security_error(self) -> None:
+ """A refusal is a `SecurityError` like the runtime's other policy refusals, and never a render failure."""
+ assert issubclass(Jinja2TemplateSecurityError, SecurityError)
+ assert not issubclass(Jinja2TemplateSecurityError, ToolError)
+ assert not issubclass(Jinja2TemplateSecurityError, Jinja2TemplateRenderError)
+ assert not issubclass(Jinja2TemplateRenderError, SecurityError)
+ with pytest.raises(SecurityError) as exc_info:
+ render_jinja2_sync(
+ template_source="{{ photos[0].model_copy() }}",
+ template_category=TemplateCategory.BASIC,
+ templating_context=_make_context(),
+ )
+ assert type(exc_info.value) is Jinja2TemplateSecurityError
+ assert exc_info.value.to_error_report().error_type == "Jinja2TemplateSecurityError"
+
def test_sync_render_reads_metadata(self) -> None:
rendered = render_jinja2_sync(
template_source="{{ note._stuff_name }}: {{ note.text }}",