# What Are Subagent Profiles and How Do They Influence Agent Behavior and Tool Selection in Reasonix?

> Discover subagent profiles in Reasonix, reusable skills that influence agent behavior and tool selection by enforcing custom constraints for isolated child agents. Learn how they work.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: deep-dive
- Published: 2026-08-11

---

**Subagent profiles in Reasonix are reusable, manually-invoked Skills that run as isolated child agents, returning only the final answer to the parent while enforcing custom toolsets, models, and sandbox constraints.**

Subagent profiles provide a **delegation mechanism** for the DeepSeek-Reasonix framework, allowing developers to spin up constrained, single-purpose child agents without polluting the parent conversation with intermediate reasoning steps. This article explains how profiles work, how they control tool availability, and how to create and invoke them based on the official source code.

## How Subagent Profiles Work in Reasonix

According to the [[`docs/SUBAGENT_PROFILES.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SUBAGENT_PROFILES.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SUBAGENT_PROFILES.md) specification, a subagent profile executes with `runAs: subagent`, launching an entirely separate agent instance. The parent agent receives **only the child's final answer**—the intermediate thoughts, tool calls, and reasoning are discarded.

Key behaviors from the source analysis:

- **Conversation isolation**: The parent retains the original task context; the child's working memory does not merge back (lines 50-52).
- **Storage locations**: Profiles live in `.reasonix/skills/` (project-scoped) or `$HOME/.reasonix/skills/` (global).
- **Override precedence**: Profiles can specify their own **model** and **effort** settings, which override parent defaults following a documented hierarchy (lines 65-74).

## Tool Selection: The Allowed-Tools List

The most direct way subagent profiles influence behavior is through **restricted tool availability**. Each profile declares an `allowed-tools` list that acts as a capability whitelist.

From lines 18-20 of the specification:

| Scenario | Tool Availability |
|----------|-----------------|
| `allowed-tools` explicitly listed | Only those tools are mounted |
| List omitted or empty | Inherits runner's default toolset |

This prevents "tool explosion" in parent responses and ensures predictable, auditable behavior for sensitive operations.

### Read-Only Mode

Set `read-only: true` to force the **read-only tool registry**, automatically stripping all writer tools (lines 48-50). This is useful for review and analysis tasks where mutation risks must be eliminated.

## Model and Effort Overrides

Subagent profiles support **model and effort selection** that overrides parent defaults. The precedence hierarchy (lines 66-74) works as follows:

1. Profile-explicit values (highest priority)
2. Parent agent configuration
3. System defaults (lowest priority)

This allows a lightweight parent to delegate heavy reasoning to a `deepseek-pro` subagent with `effort: high`, optimizing cost and latency.

## Creating and Invoking Subagent Profiles

### Creating a Profile

Use the CLI to scaffold a reusable profile:

```bash
reasonix subagent create reviewer \
  --description "Review changes for correctness and regressions" \
  --prompt-file reviewer.md \
  --tools read_file,grep,bash \
  --model deepseek-pro \
  --effort high

```

This persists the profile to your skills directory with the constrained toolset and model configuration (lines 13-21).

### Interactive Invocation

In the CLI or desktop UI, invoke via slash command:

```text
/reviewer review the current diff

```

The subagent launches, executes in isolation, and returns its conclusion to the parent conversation (lines 44-48).

### Programmatic Invocation

Embed profiles in task or fleet definitions:

```python
task(profile="doc-rewriter", prompt="rewrite docs/01.md",
     write_paths=["docs/01.md"])

```

### Headless Execution

For automation or testing:

```bash

# Preview mode (read-only)

reasonix subagent try reviewer "review the current diff"

# Full execution (writes permitted)

reasonix subagent run reviewer "review and fix the current diff"

```

The `try` variant enforces read-only constraints regardless of profile settings (lines 77-86).

## Concurrency and Resource Limits

Reasonix imposes default guards on subagent execution:

- `agent.max_subagent_concurrency = 6` — total simultaneous subagents
- `agent.max_parallel_writers = 3` — concurrent subagents with write access

Both values are configurable per deployment (line 74).

## Profile Architecture in the Codebase

| File | Purpose |
|------|---------|
| [[`docs/SUBAGENT_PROFILES.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SUBAGENT_PROFILES.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SUBAGENT_PROFILES.md) | Complete reference for definition, creation, and invocation |
| [[`docs/SPEC.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SPEC.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md) | `runAs: subagent` executor model specification |
| [[`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/REASONIX.md) | "Subagent delegation" high-level design (line 18) |
| [[`docs/GUIDE.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/GUIDE.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.md) | Desktop and CLI user workflows |
| [[`docs/TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/TOOL_CONTRACT.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/TOOL_CONTRACT.md) | Output limit handling for subagent references |

## Summary

- **Subagent profiles** are reusable Skills that execute as isolated `runAs: subagent` instances.
- **Tool selection** is controlled via `allowed-tools` whitelist and `read-only` flags.
- **Model and effort overrides** follow a documented precedence hierarchy.
- **Invocation methods** include slash commands, programmatic `task()` calls, and headless CLI commands.
- **Concurrency limits** and sandbox isolation ensure predictable, safe delegation.

## Frequently Asked Questions

### How do subagent profiles differ from regular tool calls?

Subagent profiles spawn an **entire child agent** with its own reasoning loop and context, not a single function execution. The parent receives only the final answer, not intermediate steps, keeping the conversation tree clean and auditable.

### Can a subagent profile access tools not in its allowed list?

No. The `allowed-tools` list is enforced at the registry level. If omitted, the subagent inherits the runner's defaults—but it cannot escalate beyond that scope unless explicitly granted.

### What happens if a subagent exceeds its effort or token limits?

The subagent's execution is bounded by its own `effort` setting and the global `agent.max_subagent_concurrency` limit. Per [[`docs/TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/TOOL_CONTRACT.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/TOOL_CONTRACT.md), output handling follows the "Subagent reference" protocol, which truncates or errors rather than streaming unlimited context to the parent.

### Where should I store custom subagent profiles?

Use `.reasonix/skills/` for **project-specific** profiles versioned with your codebase, or `$HOME/.reasonix/skills/` for **personal/global** profiles available across all Reasonix sessions.