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

# Feature flags

> All Engine feature flags grouped by area, with rollout history and recommended defaults.

The Engine has roughly 25 feature flags. Each toggles a specific code
path on or off. This page groups them by what they affect, gives the
recommended defaults per environment, and notes rollout history.

For the bare reference table, see
[Environment variables → Feature flags](./env-vars#feature-flags).

## A reminder about values

Feature flag values are the strings `"true"` or `"false"`,
case-insensitive. Never `1` / `0`. Never bare `true` / `false` (those
parse as Python booleans, which the loader rejects). The Engine's
loader is strict on purpose — typos become loud errors instead of
silent defaults.

## Agent loop

These shape how the agent loop behaves on each turn.

| Flag                          | Default   | Recommended dev | Recommended prod |
| ----------------------------- | --------- | --------------- | ---------------- |
| `TOKEN_BUDGET_ENABLED`        | `"false"` | `"false"`       | `"false"`        |
| `STOP_HOOKS_ENABLED`          | `"true"`  | `"true"`        | `"true"`         |
| `PRE_TOOL_HOOKS_ENABLED`      | `"true"`  | `"true"`        | `"true"`         |
| `POST_TOOL_HOOKS_ENABLED`     | `"true"`  | `"true"`        | `"true"`         |
| `HOOKS_SETTINGS_LOAD_ENABLED` | `"true"`  | `"true"`        | `"true"`         |
| `REACTIVE_COMPACT_ENABLED`    | `"true"`  | `"true"`        | `"true"`         |
| `CACHE_HIT_MONITOR_ENABLED`   | `"true"`  | `"false"`       | `"true"`         |

**`TOKEN_BUDGET_ENABLED`.** Off by default. Enables a continuation loop
that lets the agent automatically continue past `MAX_TOKENS`. Useful
for long-form output, but removes the natural cost ceiling. Leave off
for predictable budget; turn on when you have budget guardrails
elsewhere.

**`*_HOOKS_ENABLED`.** All on by default. Hooks let you intercept the
agent loop at specific boundaries. Disabling them turns off
customization mechanisms; rarely a good idea.

**`REACTIVE_COMPACT_ENABLED`.** On. Recovers from context overflow by
collapsing earlier turns. Off means an overflow returns
`CONTEXT_OVERFLOW` and the user has to restart. Always leave on.

**`CACHE_HIT_MONITOR_ENABLED`.** On in production for visibility into
cache effectiveness. Off in development to reduce log noise.

## Memory and compaction

| Flag                                 | Default  | Recommended dev | Recommended prod    |
| ------------------------------------ | -------- | --------------- | ------------------- |
| `USE_INMEMORY_WM`                    | unset    | unset           | unset               |
| `FEATURE_CACHED_SNIP_PREPASS`        | unset    | unset           | optionally `"true"` |
| `FEATURE_POST_COMPACT_HARDENED`      | `"true"` | `"true"`        | `"true"`            |
| `FEATURE_STRUCTURED_FILE_EXTRACTION` | `"true"` | `"true"`        | `"true"`            |

**`USE_INMEMORY_WM`.** Tests and CI only. Routes working memory through
an in-memory backend rather than SQLite. Faster but loses durability.
Never enable in production.

**`FEATURE_CACHED_SNIP_PREPASS`.** When enabled, runs an extra pass to
optimize the cacheable prefix. Adds latency per turn; saves cost on
high-volume cached workloads. Pilot in staging before rolling to prod.

**`FEATURE_POST_COMPACT_HARDENED`.** On by default. Stricter
post-processing after compaction. Always leave on; the unhardened path
exists for debugging only.

**`FEATURE_STRUCTURED_FILE_EXTRACTION`.** On by default. Preserves file
contents through compaction so the agent doesn't lose track of files
it's already read. Always leave on.

## Sandbox

| Flag                           | Default  | Recommended dev | Recommended prod |
| ------------------------------ | -------- | --------------- | ---------------- |
| `FEATURE_WINDOWS_PATH_EVASION` | `"true"` | `"true"`        | `"true"`         |
| `FEATURE_DONT_ASK`             | unset    | unset           | conditional      |
| `FEATURE_SED_VALIDATION`       | `"1"`    | `"1"`           | `"1"`            |
| `FEATURE_DANGEROUS_REMOVAL`    | `"true"` | `"true"`        | `"true"`         |
| `FEATURE_TREE_KILL`            | `"true"` | `"true"`        | `"true"`         |
| `FEATURE_BG_WATCHDOG`          | `"true"` | `"true"`        | `"true"`         |

**`FEATURE_DONT_ASK`.** Disables permission prompts. Use only in
unattended automation where waiting on a human is worse than failing.
**Don't set in user-facing deployments** — the whole point of the
permission system is to keep the user in the loop.

**`FEATURE_SED_VALIDATION`.** Note: this one is `"1"` / `"0"`, not
`"true"` / `"false"`. Legacy. The validator catches the worst `sed`
patterns; on by default.

**`FEATURE_DANGEROUS_REMOVAL`.** Detects and gates dangerous
`rm`/`shred` patterns. Disabling this is rarely a good idea.

**`FEATURE_TREE_KILL`** and **`FEATURE_BG_WATCHDOG`.** Process
hygiene. Both on by default.

## Media handling

| Flag                               | Default   | Recommended dev | Recommended prod (user uploads) |
| ---------------------------------- | --------- | --------------- | ------------------------------- |
| `MEDIA_PRESEND_VALIDATION_ENABLED` | `"false"` | `"false"`       | `"true"`                        |
| `MEDIA_IMAGE_RESIZE_ENABLED`       | `"false"` | `"false"`       | `"true"`                        |
| `MEDIA_ERROR_RECOVERY_ENABLED`     | `"false"` | `"false"`       | `"true"`                        |
| `CONTENT_INGESTION_ENABLED`        | `"false"` | `"false"`       | conditional                     |

**For deployments that handle user-uploaded images and documents,
enable the first three.** They prevent oversized media from causing
provider errors.

**`CONTENT_INGESTION_ENABLED`.** On for deployments that handle large
documents (long PDFs, transcripts). Adds chunking + embedding cost up
front; saves context cost during retrieval. Off by default because the
infrastructure cost isn't worth it for everyone.

## Observability

| Flag                           | Default   | Recommended dev | Recommended prod |
| ------------------------------ | --------- | --------------- | ---------------- |
| `QUERY_CHAIN_TRACKING_ENABLED` | `"false"` | conditional     | `"true"`         |

**`QUERY_CHAIN_TRACKING_ENABLED`.** Tracks query chains in
`observability_events`. Useful for production observability; adds
overhead per call. Pilot in staging.

## Other

| Flag                      | Default   | Recommended dev | Recommended prod |
| ------------------------- | --------- | --------------- | ---------------- |
| `ENABLE_SIGINT_INTERRUPT` | `"false"` | depends         | `"false"`        |

**`ENABLE_SIGINT_INTERRUPT`.** Installs a SIGINT handler. Used for
TUI/CLI workflows where the user wants to interrupt with Ctrl-C. In
server mode, leave off — SIGINT is for the supervisor.

## Rolling out a new flag

When the Engine adds a new flag in a release:

1. The flag is introduced **off** by default. Existing deployments
   keep their behavior.
2. The release notes describe what the flag does and when to enable
   it.
3. After enough deployments have validated the new behavior, a future
   release flips the default to **on**.
4. Eventually, after several stable releases, the flag is removed
   entirely (the new behavior becomes the only behavior).

The flag's lifecycle is documented in the changelog.

## Auditing flags in production

Periodically audit the flag values in your production environment.
Flags that were enabled experimentally tend to stay on past their
useful life, accumulating mystery.

```bash theme={null}
# print the flags this Engine actually has set
docker compose exec engine env | grep -E '^(FEATURE_|MEDIA_|TOKEN_|REACTIVE_|CACHE_|USE_|PRE_|POST_|STOP_|HOOKS_|QUERY_|ENABLE_)'
```

For each flag set: do we know why? If the answer is no, take it back
to default and see if anything breaks.

## See also

* [Environment variables](./env-vars) — the bare reference table.
* [Architecture overview](../../internal/architecture/overview) — the
  systems each flag affects.