<!-- SPDX-License-Identifier: Apache-2.0 -->

# Conditional blocks and path access

`config/conditions.toml` enables conditional access to resources based on session context.

It narrows what an agent can see or touch in a given channel, keeping authority tied to where work is happening.

- Load additional memory blocks only in appropriate contexts.
- Grant or restrict access to files and folders based on where the session is running.

`conditions.toml` is not an `exec` sandbox boundary.
Path checks can gate file tools, but a command allowed through `exec` may have many ways to read, copy, or transform data inside its mounted environment.
Use the sandbox binary allowlist and mounts as the boundary for command execution.

## Format

```toml
[blocks.nsfw]
when = ["discord:nsfw", "discord:dm"]
mode = "or"
action = "load"

[memories."/private/"]
when = "discord:dm"
action = "allow"

[workspace."/deploy/"]
when = ["discord:guild:123456789"]
action = "allow"
```

## Conditions

| Condition | Meaning |
| --- | --- |
| `discord:nsfw` | NSFW-flagged Discord channel. |
| `discord:dm` | Any Discord DM. |
| `discord:dm:{channelId}` | A specific Discord DM channel. |
| `discord:guild:{guildId}` | A specific Discord guild. |
| `discord:channel:{channelId}` | A specific Discord channel. |
| `discord:forum:{forumId}` | Any thread of a forum channel. |
| `internal` | An internal session (heartbeat, cron). |
| `tui` | A TUI session; reserved in this runtime, which has no interactive TUI channel. |

Conditions support negation with a leading `!`.

`when` accepts one condition or an array of conditions; `mode` is `or` (default) or `and`.

## Actions

| Action | Applies to | Meaning |
| --- | --- | --- |
| `load` | `blocks` | Include the block in the system prompt. |
| `allow` | `memories`, `workspace` | Grant access to the path. |
| `deny` | `memories`, `workspace` | Block access to the path. |

## Conditional blocks

Create conditional blocks in `blocks/conditional/<name>.md`, where `<name>` matches the rule key in `conditions.toml`.

```markdown
+++
description = "Guidelines for handling mature content"
+++

You are in an NSFW context. The following guidelines apply:
...
```

The frontmatter is TOML and must include a `description`.
Matching blocks are added to the system prompt alongside the core blocks.

## Path access

Path rules control access to files in `/memories/` and `/workspace/`.

Paths ending with `/` match as prefixes; paths not ending with `/` require an exact match.

Access is evaluated as:

1. A deny rule that matches both the path and the current context blocks access.
2. Otherwise, an allow rule that matches both the path and the current context grants access.
3. A path with matching rules that match no context is blocked.
4. A path with no matching rules is allowed (baseline behavior).

## Hot reload

Changes to `conditions.toml` are applied live while the runtime is running; no restart is required.