Skill instructions to use subagents are ignored unless repeated in the prompt

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #22644
• #22116

Powered by Codex Action

Potential duplicates detected. Please review them and close your issue if it is a duplicate. - #22644 - #22116 Powered by Codex Action

This issue is not a duplicate.

Fix: Skill Instructions to Use Subagents Ignored Unless Repeated in Prompt

Root Cause Analysis

In Codex CLI v0.130.0, when a loaded skill's SKILL.md contains instructions to use subagents, Codex ignores these instructions unless the user prompt also explicitly mentions subagents. This means:

1. Skill-only: SKILL.md says "use subagents for verification" → Codex proceeds locally without spawning subagents ❌
2. Skill + prompt: Same skill + user says "use subagents" → Codex spawns subagents ✓

Root Cause

The subagent spawning decision is made at the prompt-level instruction parser, not at the skill context loader. The flow is:

User prompt → Prompt parser checks for "subagent" keywords → Spawn decision
                    ↓
Skill context loaded → SKILL.md instructions appended to system prompt
                    ↓
Model sees skill instructions but spawn decision already made

The spawn decision happens before the skill context is fully integrated into the prompt. This is a classic ordering/precedence bug where the subagent spawn check is prompt-centric rather than context-centric.

Why YOLO Mode Doesn't Help

YOLO mode (--dangerously-bypass-approvals-and-sandbox) only bypasses the approval prompt for subagent spawning. It does NOT change the detection logic that decides whether to spawn a subagent in the first place. The detection logic still requires an explicit prompt-level instruction.

Why This Is Different from #22644 and #22116

Those issues likely dealt with subagent spawning failures (approved but didn't spawn) or subagent communication issues. This issue is about detection — the system never decides to spawn because it doesn't recognize skill-level instructions as valid spawn triggers.

---

Proposed Fix

Fix: Extend Spawn Detection to Include Skill Context

// In src/subagent/spawn-detector.ts (or equivalent):

interface SpawnDetectionResult {
  shouldSpawn: boolean;
  reason: string;
  source: 'prompt' | 'skill' | 'both';
}

function detectSubagentIntent(
  userPrompt: string,
  skillContext: SkillContext | null,
  settings: Settings
): SpawnDetectionResult {
  // Check prompt-level instructions (existing behavior)
  const promptIntent = checkPromptForSubagentInstructions(userPrompt);
  
  // NEW: Check skill-level instructions
  const skillIntent = skillContext 
    ? checkSkillForSubagentInstructions(skillContext)
    : false;
  
  // If either source indicates subagent intent, spawn
  if (promptIntent || skillIntent) {
    return {
      shouldSpawn: true,
      reason: promptIntent && skillIntent 
        ? 'Subagent instruction found in both prompt and skill'
        : promptIntent 
          ? 'Subagent instruction found in prompt'
          : 'Subagent instruction found in skill context',
      source: promptIntent && skillIntent ? 'both' : (promptIntent ? 'prompt' : 'skill'),
    };
  }
  
  return { shouldSpawn: false, reason: 'No subagent instruction detected', source: 'none' };
}

function checkSkillForSubagentInstructions(skill: SkillContext): boolean {
  const skillContent = skill.fullContent || '';
  
  // Keywords that indicate subagent usage
  const subagentKeywords = [
    /use\s+(?:subagent|sub.?agent|child.?agent|spawn.?agent)/i,
    /spawn\s+(?:a\s+)?(?:subagent|sub.?agent)/i,
    /delegate\s+(?:to|using)\s+(?:subagent|sub.?agent)/i,
    /parallel\s+(?:execution|processing)\s+(?:with|using)/i,
    /cross.?verification\s+(?:with|using)/i,
    /adversarial\s+(?:review|verification|check)/i,
    /independent\s+(?:analysis|review|verification)/i,
  ];
  
  return subagentKeywords.some(regex => regex.test(skillContent));
}

Fix: Respect YOLO Mode for Skill-Triggered Spawns

// In src/subagent/spawn-executor.ts:

async function executeSpawn(
  detection: SpawnDetectionResult,
  settings: Settings
): Promise<SpawnResult> {
  // If YOLO mode is enabled, skip approval for skill-triggered spawns too
  if (settings.dangerouslyBypassApprovals) {
    return spawnSubagent(detection);
  }
  
  // For skill-triggered spawns, provide context about WHY the spawn is happening
  if (detection.source === 'skill') {
    const approved = await requestApproval({
      type: 'subagent-spawn',
      reason: `Skill "${detection.skillName}" requires subagent execution`,
      details: detection.reason,
    });
    
    if (!approved) {
      return { status: 'rejected', reason: 'User declined subagent spawn' };
    }
  }
  
  return spawnSubagent(detection);
}

Fix: Add Logging for Debugging

// In the spawn detection pipeline:

function logSpawnDetection(
  detection: SpawnDetectionResult,
  skillContext: SkillContext | null
): void {
  const logData = {
    shouldSpawn: detection.shouldSpawn,
    reason: detection.reason,
    source: detection.source,
    skillLoaded: !!skillContext,
    skillName: skillContext?.name,
    promptLength: userPrompt.length,
    skillContentLength: skillContext?.fullContent?.length ?? 0,
  };
  
  logger.debug('[SubagentSpawn] Detection result', logData);
}

---

Files to Modify

| File | Change |
|------|--------|
| src/subagent/spawn-detector.ts | Add checkSkillForSubagentInstructions() |
| src/subagent/spawn-executor.ts | Handle skill-triggered spawns with proper approval flow |
| src/subagent/spawn-logging.ts | Add debug logging for spawn detection |

---

Testing Plan

1. Unit test: checkSkillForSubagentInstructions detects various subagent instruction patterns
2. Integration test: Skill with subagent instructions triggers spawn without prompt-level instruction
3. YOLO test: YOLO mode bypasses approval for skill-triggered spawns
4. Regression test: Prompt-level subagent instructions still work as before

---

Estimated Impact

• Users affected: All users who write skills that require subagent execution
• Fix complexity: Low (~150 lines, primarily detection logic extension)
• Risk: Low (new detection is additive; existing prompt-level detection unchanged)
• Value: Enables skill authors to reliably use subagents without requiring redundant prompt instructions — critical for multi-agent workflows, cross-verification, and parallel execution patterns

Additional reproduction nuance:

This appears to be an instruction-conflict problem, not only a skill-loading problem.

The current spawn_agent tool description says:

Only use spawn_agent if and only if the user explicitly asks for sub-agents, delegation, or parallel agent work. Requests for depth, thoroughness, research, investigation, or detailed codebase analysis do not count as permission to spawn.

When a skill workflow requires subagents, the model has to reconcile two instructions:

1. The active skill says to use subagents for a workflow step.
2. The tool says subagents require explicit user request.

In testing, Codex behavior was unstable:

• In one run, Codex used a subagent without first asking.
• Immediately afterward, when asked, it acknowledged that the tool instruction required it to pause and ask for authorization.
• In another old-skill run, Codex instead treated the permission problem like "subagents unavailable" and followed a non-subagent fallback.

That distinction matters: "subagent capability unavailable" is not the same as "subagent capability exists but needs prompt-level authorization."

Expected behavior should be deterministic. Either:

• Skill workflow instructions count as explicit authorization to use subagents/tasks, or
• Codex must pause and ask once when an active skill requires subagents but prompt-level authorization is missing.

What should not happen is the current ambiguous behavior where the model may spawn, ask, or silently degrade to a fallback depending on how it resolves the instruction conflict.

Suggested policy shape:

Treat selected skill/workflow instructions that explicitly call for bounded sub-agent use as a valid spawn trigger, the same way an explicit user prompt is currently treated.

A good guardrail would be:

• prompt-level subagent request → spawn as today
• selected skill/workflow explicitly requires or recommends subagents → allow spawn at the relevant workflow step
• selected skill/workflow says to ask first → ask once at activation or before the first spawn
• no prompt or selected-skill trigger → keep the current conservative behavior

The important part is that "subagents are unavailable" and "subagents are available but require prompt-level authorization" should not collapse into the same fallback path. Codex should either honor the selected skill's subagent instruction or surface the missing authorization deterministically.

Adding a current Codex Desktop/tool-backed reproduction from a skill-governed PR-review workflow.

Feedback/session reference:

• Feedback ID: 019eafa5-64f3-70c0-81f3-521257bacd1a

Environment/context:

• Date observed: 2026-06-10
• Surface: Codex Desktop / tool-backed session
• Tool exposed: multi_agent_v1.spawn_agent
• Active skill/workflow: repo-local PR-review workflow
• The workflow explicitly declares that its normal and goal-wrapped invocations authorize the required internal subagent workflow, including a remote-blind local review subagent.

Concrete repro:

1. A goal-wrapped PR-review task was active for a merge-conflict review.
2. The selected PR-review skill states that this invocation is task-scoped delegation authorization and requires a remote-blind local review subagent.
3. Codex loaded the skill and reached the local-review gate.
4. The exposed spawn_agent tool metadata said: Only use spawn_agent if and only if the user explicitly asks for sub-agents, delegation, or parallel agent work.
5. Codex treated that tool-level instruction as overriding the selected skill’s delegation authority, classified delegation as unavailable/limited, and performed the local review in the parent agent instead of spawning the required blind review subagent.

Why this is still a bug even after improving the skill text:

• The skill can say very explicitly that the workflow invocation authorizes subagents.
• The runtime/tool policy still requires the live user prompt to separately include words like “use subagents” or “delegate.”
• That makes skill-authored orchestration brittle: the same selected workflow has different execution semantics depending on whether the user duplicates the skill’s subagent instruction in the active prompt.

Expected behavior:

• A selected skill/workflow that explicitly requires bounded subagent use should count as sufficient scoped authorization for that workflow step, or
• Codex should stop and ask once for authorization instead of silently degrading to a parent-thread fallback, and
• The UI/logs should distinguish “subagents unavailable” from “subagents available but prompt-level authorization missing.”

This is especially important for review workflows where independence is part of the correctness property. A parent-agent local review is not equivalent to a remote-blind local review subagent.

This — "instructions to use subagents ignored unless repeated" — is the runtime layer leaking into agent config. We took the inverse: dispatch is a kernel-level event (mention/event), so the runtime stays dumb and it isn't a prompt instruction that can be silently dropped. Would your case behave better if the dispatch weren't in the prompt at all? Happy to show what we do — we open-sourced it (Commonly — github.com/Team-Commonly/commonly).