How Ponytail Controls Rule Injection Into Sub‑Agents: Environment Variables and Regex Filtering

Ponytail controls rule injection into sub‑agents via the PONYTAIL_SUBAGENT_MATCHER environment variable, which filters sub‑agents by matching their agent_type against a user‑defined regex pattern before prepending the AGENTS.md rule set to their prompts.

The DietrichGebert/ponytail repository provides a portable agent framework that ensures safety guidelines follow your AI workflows across different host platforms. Understanding how Ponytail controls rule injection into subagents is essential for maintaining consistent behavior when your main agent spawns specialized child agents.

The Mechanism Behind Sub‑Agent Rule Injection

Ponytail injects its compact rule set—the content of AGENTS.md—into sub‑agents through host‑specific hooks that intercept agent creation events. As detailed in the README.md and implemented in files like hooks/qoder-hooks.json, this injection occurs in the PreToolUse hook, which watches for sub‑agent creation patterns such as the task|Task matcher used in the Qoder adapter.

The injection logic resides in adapter‑specific hook definitions, including hooks/claude-codex-hooks.json for Claude Code and Codex. These hooks modify the sub‑agent's system prompt by prepending the rules before the agent executes, ensuring that safety constraints propagate through the entire agent hierarchy.

Configuring Selective Rule Injection

You control which sub‑agents receive the rule set using the PONYTAIL_SUBAGENT_MATCHER environment variable. This variable accepts a regular expression that Ponytail evaluates against each sub‑agent's agent_type string using case‑insensitive, un‑anchored matching.

Default Behavior: Inject Into All Sub‑Agents

When PONYTAIL_SUBAGENT_MATCHER is unset or empty, Ponytail defaults to injecting rules into every sub‑agent your LLM spawns via the Agent tool. This ensures maximum safety coverage without requiring explicit configuration.

# No environment variable needed

export PONYTAIL_DEFAULT_MODE=full   # optional, sets the main mode

# Run your LLM tool; Ponytail automatically adds rules to any sub‑agent

Selective Injection via Regex Matching

To restrict rule injection to specific agent types, set PONYTAIL_SUBAGENT_MATCHER to a regular expression that matches your target sub‑agents. The host checks the sub‑agent's agent_type property against this pattern, injecting rules only when the regex matches.

# Only inject into sub‑agents whose type contains "search"

export PONYTAIL_SUBAGENT_MATCHER="search"

# "search:google" receives rules, "tool:filesystem" does not

You can also use negative lookahead patterns to exclude specific agent types:

# Prevent injection into any read‑only agents

export PONYTAIL_SUBAGENT_MATCHER="^(?!.*read‑only).*$"

Fallback Handling for Invalid Patterns

If you provide an invalid regular expression, or if the sub‑agent lacks an agent_type property, Ponytail falls back to the default behavior of injecting rules into all sub‑agents. This prevents configuration errors from silently breaking your safety constraints.

# Invalid regex triggers fallback to all‑agent injection

export PONYTAIL_SUBAGENT_MATCHER="*invalid[regex"

# Ponytail detects the error and defaults to full injection

Implementation Across Host Adapters

Ponytail ships with adapter‑specific hooks for multiple platforms including Qoder, Claude Code, Codex, OpenCode, pi, Hermes, and Gemini CLI. Each adapter implements the same injection logic in its respective hooks file, such as hooks/qoder-hooks.json for Qoder or hooks/claude-codex-hooks.json for Claude Code and Codex.

The PreToolUse hook in these configurations specifically watches for sub‑agent creation events and performs the agent_type regex check against process.env.PONYTAIL_SUBAGENT_MATCHER before modifying the prompt. According to the docs/agent-portability.md documentation, this consistent implementation ensures that rule injection behavior remains identical regardless of which host platform you choose.

Verifying Sub‑Agent Rule Injection

To confirm that rules are being injected correctly, you can inspect the environment within your sub‑agent's execution context. The host hook typically makes the rule content available through environment variables or direct prompt modification.

# Inside the sub‑agent's code (e.g., a Qoder tool)

import os
print("System prompt starts with:", os.getenv("PONYTAIL_RULES")[:30])

# The host hook sets PONYTAIL_RULES to the rule text before execution

Summary

• Default injection: Without PONYTAIL_SUBAGENT_MATCHER, Ponytail prepends AGENTS.md rules to every sub‑agent's prompt.
• Regex filtering: Set PONYTAIL_SUBAGENT_MATCHER to a pattern matching your desired agent_type strings for selective injection.
• Fallback safety: Invalid regexes or missing agent_type properties trigger fallback to universal rule injection.
• Hook implementation: The logic lives in adapter files like hooks/qoder-hooks.json and hooks/claude-codex-hooks.json, using the PreToolUse hook to intercept agent creation.
• Cross‑platform consistency: The same mechanism works across Qoder, Claude Code, Codex, and other supported hosts as documented in docs/agent-portability.md.

Frequently Asked Questions

What happens if I don't set PONYTAIL_SUBAGENT_MATCHER?

If the environment variable is unset, Ponytail defaults to injecting the AGENTS.md rule set into every sub‑agent that the LLM spawns. This ensures that safety guidelines propagate throughout your entire agent hierarchy without requiring manual configuration.

How does Ponytail handle invalid regex patterns?

When PONYTAIL_SUBAGENT_MATCHER contains an invalid regular expression, or when a sub‑agent lacks an agent_type property, Ponytail falls back to the default behavior of injecting rules into all sub‑agents. This prevents configuration errors from silently removing safety constraints.

Which host adapters support sub‑agent rule injection?

Ponytail implements sub‑agent rule injection across all supported host adapters, including Qoder, Claude Code, Codex, OpenCode, pi, Hermes, and Gemini CLI. Each adapter contains hooks—defined in files like hooks/qoder-hooks.json and hooks/claude-codex-hooks.json—that intercept sub‑agent creation and apply the same regex‑based filtering logic.

Where does Ponytail store the rules that get injected?

The rules live in AGENTS.md at the repository root. This compact rule file contains the guidelines that Ponytail prepends to sub‑agent prompts when injection occurs. The content of this file is what the PreToolUse hooks in various adapters insert into the system prompts of matching child agents.

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