Roles & Context Briefing

When Nyzhi spawns a subagent, it needs to decide what the agent can do (its role) and what it knows (its context briefing). This page explains how both systems work internally.

Role Resolution

When spawn_agent is called with an agent_type, Nyzhi resolves the role in this order:

User-defined roles — from [agent.agents.roles] in your config
Built-in roles — shipped with Nyzhi
Fallback — a synthesized default role

The first match wins.

Built-in Roles

Role	Description	Read-only
`default`	General-purpose agent	No
`explorer`	Codebase exploration	Yes
`worker`	Implementation tasks	No
`reviewer`	Code review	Yes
`planner`	Architecture and planning	Yes
`architect`	System design	Yes
`debugger`	Root-cause debugging	No
`security-reviewer`	Security analysis	Yes
`quality-reviewer`	Code quality assessment	Yes
`test-engineer`	Test writing and QA	No
`build-fixer`	Build failure resolution	No
`deep-executor`	Complex multi-step tasks	No
`document-specialist`	Documentation	No
`code-simplifier`	Refactoring and simplification	No

Each built-in role has a dedicated system prompt personality and optional tool constraints.

User-Defined Roles

Define roles in your config:

[agent.agents.roles.api-specialist]
description = "Backend API expert"
system_prompt = "You are an API development specialist..."
model = "anthropic/claude-sonnet-4-20250514"
max_steps = 60
allowed_tools = ["read", "write", "edit", "bash", "grep", "glob", "git_status"]

File-Based Roles

Create a markdown file at .nyzhi/agents/<role-name>.md:

---
name: api-specialist
description: Backend API expert
model: anthropic/claude-sonnet-4-20250514
max_steps: 60
read_only: false
allowed_tools: [read, write, edit, bash, grep, glob]
---

You are a backend API specialist. Focus on:
- RESTful API design
- Input validation
- Error handling
- Performance optimization

The markdown body becomes the system prompt override.

Priority: .nyzhi/agents/ wins over .claude/agents/ on name conflicts.

Role Application

When a role is resolved, apply_role modifies the spawned agent’s config:

System prompt — overridden if the role specifies one
Max steps — capped if the role limits it
Model — overridden if the role specifies one (via subagent_model)
Agent name — labeled as sub-agent/<role>

Then apply_model_override layers any session-scoped override from /subagent-config.

Tool Fencing

Roles control tool access:

allowed_tools — explicit whitelist of tools the agent can use
disallowed_tools — blacklist subtracted from available tools

At execution time, ToolRegistry::execute enforces the allowed_tool_names gate. If a tool isn’t in the list, it can’t run.

Context Briefing

When a subagent is spawned, it receives a context briefing — a compact summary of the parent’s state.

What’s Included

SharedContext carries:

Field	What it contains
`recent_changes`	Files modified by the parent agent
`active_todos`	Current todo list items
`conversation_summary`	Recent message preview
`project_root`	Workspace path

How It’s Built

build_briefing() renders these into markdown sections with caps:

Limit	Value
Total briefing lines	60
Recent change entries	20
Message preview	5 messages

Injection

At spawn time:

Lock the shared context
Render the briefing markdown
Append it to the child’s system prompt
Append recent notepad wisdom (if available)

This gives subagents enough context to work effectively without re-reading the parent’s entire conversation.

Project Memory

The briefing can also include a project memory excerpt (from SharedContext::build_briefing()), so subagents benefit from stored project knowledge.

Runtime Model Overrides

The /subagent-config slash command lets you override models per role for the current session:

/subagent-config set explorer deepseek/deepseek-chat
/subagent-config set worker anthropic/claude-sonnet-4-20250514
/subagent-config reset explorer

These overrides apply on top of role-defined models and config-defined models.

Next Steps

Subagent Lifecycle — spawn, interact, close
Teams — multi-agent collaboration
Architecture — overall system design