Settings injection
How workspace settings and context are injected into the agent session at run time, including precedence rules and per-workspace scoping.
Every time an agent run starts, Qoc reads your workspace files and injects a structured context bundle into the agent session so the agent has your risk config, tracked entities, and house rules without you having to copy-paste them.
What gets injected
At run time, Qoc assembles a context bundle from three sources and presents it to the agent before the first user turn.
Workspace config — the [agent] and [risk] sections of desk.toml become structured text the agent reads as its operating constraints.
Entity registry — every file in entities/ is summarised and included so the agent knows which instruments, accounts, and counterparties are in scope.
House rules — any free-form Markdown file placed at house-rules.md (or listed under [context.files] in desk.toml) is injected verbatim as a system-level instruction block.
Declaring injected files in desk.toml
[context]
# Files listed here are injected as read-only context before every agent run.
files = [
"house-rules.md",
"research/macro-outlook.md",
]
[context.risk]
# These values override the global defaults for this workspace only.
max_position_usd = 50_000
max_drawdown_pct = 3.0
allowed_venues = ["NYSE", "NASDAQ"]Precedence and scoping
Settings follow a layered precedence: workspace `desk.toml` overrides global `~/.qoc/config.toml` overrides built-in defaults. The agent never sees values from other workspaces.
Each workspace is an isolated session scope. Two workspaces running in parallel inject their own context bundles independently — there is no cross-contamination.
If a key appears in both the global config and the workspace config, the workspace value wins. You can explicitly unset a global key by assigning it an empty string or zero.
Precedence order (highest to lowest)
| Layer | Source | Applies to |
|---|---|---|
| 1 — workspace | desk.toml in the workspace root | This workspace only |
| 2 — user global | ~/.qoc/config.toml | All workspaces on this machine |
| 3 — built-in defaults | Compiled into the qoc binary | Fallback for any unset key |
Keep house rules short
The agent context window is finite. Inject only the rules and entities that are genuinely relevant to the workspace goal. Large blobs of reference material are better placed in research/ and referenced in an issue rather than injected globally.
Dynamic context via inbox
Injected files are re-read at the start of each run, so you can update house-rules.md or an entity file between runs without restarting the workspace. Changes take effect on the next scheduled or manual qoc run.
Inbox items (inbox/) are not injected wholesale; instead the agent is told how many unread items exist and can read them on demand via the scoped qoc command surface.
Secrets do not belong in injected files
Do not place API keys, broker credentials, or private keys in any file listed under [context.files]. Credentials are stored in the encrypted secrets store and are surfaced to the agent only as named references, never as raw values.