Agent Architecture

How agents are defined — identity, model configuration, tool access, workspace isolation, and context injection. This section covers the structural decisions that determine how an agent behaves before it processes a single message.

For how agents are used (dispatch patterns, pipelines, fleets), see Agentic Patterns.

Identity & Context Model

Shared vs. per-agent context

Some files define the agent's identity globally (SOUL.md, IDENTITY.md). Others need per-agent specialization (AGENTS.md varies by role). The challenge is giving each agent the right context without duplicating thousands of tokens of bootstrap across every sub-agent spawn.

Context injection rules

Which files does each agent see? The main agent needs everything. A coder sub-agent needs SOUL.md for voice but not MEMORY.md for personal context. A cron job needs operational rules but not channel routing tables. Injection should be role-aware, not blanket.

Inheritance patterns

Global config → agent-specific overrides → session-specific context. What's shared, what's specialized, and how do you prevent the per-agent files from drifting out of sync with the global ones?

Configuration

Model fallbacks

Each agent has its own model config — primary model plus fallback chain. A model specified in a cron or spawn must exist in that agent's own fallback list, not just in agents.defaults. An unregistered model causes a silent hang.

Tool lockdown

Models ignore prompt-level tool restrictions — "don't use the browser" in AGENTS.md gets bypassed under pressure. Tool access must be controlled at the config level. Deny tools in the agent config, and the model can't use what it can't see.

Workspace isolation

Each agent gets its own workspace directory with tailored definition files. The workspace should be minimal — only the files relevant to that agent's role. Blank template files waste tokens on every session.

Coordination

Session-keyed WIP state

memory/wip.json uses session keys to prevent concurrent agents from stomping each other's work-in-progress. Each agent only reads/writes its own session key's entry.

Cross-channel limitations

A Telegram-bound session can't send to Discord. Cron delivery targets and session targets need to match the intended output channel. Getting this wrong means silent message drops.

Subagent vs. exec vs. cron

When to spawn a sub-agent (needs full agent capabilities), when to use background exec (simple command, no AI needed), and when to schedule a cron (recurring, isolated, different model). Each has different isolation, cost, and coordination characteristics.

What's Here

• Dedicated Coder Agent — A reference implementation of a focused sub-agent with three-phase workflow, model switching, and routing gates

Status

Coder agent production-tested. Broader identity sharing and context injection patterns in development.