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

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-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:

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:

/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:

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

Headless Execution

For automation or testing:

# 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-v2/docs/SUBAGENT_PROFILES.md)	Complete reference for definition, creation, and invocation
[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-v2/REASONIX.md)	"Subagent delegation" high-level design (line 18)
[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-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-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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}