Delegation

Tool Restriction Enforcement

Maestro enforces tool permissions at two levels:

Level 1: Native enforcement (primary)

Tool permissions are enforced natively via each agent's registered frontmatter stub. Use the tools array returned by get_agent when you mirror that restriction in the prompt. This works for both sequential and parallel delegation.

Level 2: Prompt-based enforcement (defense-in-depth)

Native tool permissions remain the primary boundary. As defense-in-depth, every delegation prompt should still include an explicit tool restriction block so the agent sees its allowed surface in plain language.

1. Agent Base Protocol (load agent-base-protocol via get_skill_content)
2. Filesystem Safety Protocol (load filesystem-safety-protocol via get_skill_content)
3. TOOL RESTRICTIONS block (immediately here, before any task content)
4. FILE WRITING RULES block (immediately after tool restrictions)
5. Context chain from prior phases
6. Task-specific instructions
7. Scope boundaries and prohibitions

The tool restriction block template:

TOOL RESTRICTIONS (MANDATORY):
You are authorized to use ONLY the following tools: [list from agent frontmatter].
Do NOT use any tools not listed above. Specifically:
- Do NOT use `write_file` or `replace` unless explicitly authorized above
- Do NOT use `run_shell_command` unless explicitly authorized above
- Do NOT create, modify, or delete files unless authorized above
Violation of these restrictions constitutes a security boundary breach.

Populate the tool list from the tools array returned by get_agent for the delegated agent.

The file writing rules block template:

FILE WRITING RULES (MANDATORY):
Use ONLY `write_file` to create files and `replace` to modify files.
Do NOT use `run_shell_command` with cat, echo, printf, heredocs, or shell redirection (>, >>) to write file content.
Shell interpretation corrupts YAML, Markdown, and special characters. This rule has NO exceptions.

This block reinforces the Agent Base Protocol's File Writing Rule directly in every delegation prompt, ensuring agents see the prohibition even if they skim the injected protocols.

Non-Overlapping File Ownership

When delegating to multiple agents in parallel, ensure no two agents are assigned the same file. Each file must have exactly one owner in a parallel batch.

Batch Completion Gates

All agents in a parallel batch must complete before:

• The next batch of phases begins
• Shared/container files are updated
• Validation checkpoints run
• The orchestrator creates a git commit for the batch

Conflict Prevention

• Assign non-overlapping file sets to each agent
• Reserve shared files (barrel exports, configuration, dependency manifests) for a single agent or a post-batch update step
• If two phases must modify the same file, they cannot run in parallel — execute them sequentially
• Parallel agents must NOT create git commits — the orchestrator commits after validating the batch

Hook Integration

Maestro hooks fire at agent boundaries during delegation, providing context injection and output validation. Understanding hook behavior is essential for constructing correct delegation prompts.

Agent Tracking

Before each agent dispatch, a hook tracks which agent is currently executing:

• Preferred signal: the required Agent: <agent_name> header in the delegation prompt
• Legacy fallbacks: MAESTRO_CURRENT_AGENT from the environment, then regex-based detection of patterns like delegate to <agent> or @<agent>

The detected agent name is persisted to ${MAESTRO_HOOKS_DIR:-<os.tmpdir()>/maestro-hooks-<uid>}/<session-id>/active-agent and cleared by the post-delegation hook on every allowed response (both successful validation and retry allow-through). On deny (malformed output), the active agent is preserved to enable re-validation on retry.

Session Context Injection

When an active orchestration session exists, the pre-delegation hook parses <MAESTRO_STATE_DIR>/state/active-session.md and injects a compact context line into the agent's turn:

Active session: current_phase=3, status=in_progress

This gives delegated agents awareness of where they sit in the orchestration workflow without requiring explicit context in every delegation prompt. The injection is automatic and requires no action from the orchestrator.

Handoff Format Enforcement

After completion, the post-delegation hook validates that every subagent response contains both required handoff sections:

• ## Task Report (or # Task Report)
• ## Downstream Context (or # Downstream Context)

If either heading is missing:

1. First failure: The hook blocks the response and requests a retry with a diagnostic message specifying which section is missing.
2. Second failure (stop_hook_active=true, mapped to stopHookActive in JS): The hook allows the malformed response through to prevent infinite retry loops, logging a warning.

This enforcement is the runtime complement to the Output Handoff Contract defined in the agent-base-protocol. Delegation prompts do not need to re-state the retry mechanism — the hook handles it transparently.

Exception: The TechLead/orchestrator agent is excluded from validation. Only delegated subagents are subject to format enforcement.

Delegation Constraints (per runtime)

Read delegation.constraints from get_runtime_context before constructing any agent dispatch. Apply constraints to the dispatch:

• fork_full_context_incompatible_with: list of field names. If the runtime is invoking a fork-style delegation with full-history inheritance, do NOT pass any of these fields. For Codex, this means omitting agent_type, model, and reasoning_effort whenever fork_context: true or fork_turns: "all" is used.
• result_surface: "synchronous": the parent receives the child's full text response in the dispatch return value. Parse the Task Report and Downstream Context directly from that text.
• result_surface: "deferred": the parent receives only identifiers. The parent MUST poll for completion (wait_agent or equivalent) with a bounded timeout. On timeout or empty return, invoke the Recovery Protocol in the execution skill.
• child_cannot_prompt_user: true: child agents cannot call the user-prompt tool. All user questions must surface through the Blocker Protocol below.

Blocker Protocol (child-agent question surfacing)

MANDATORY when delegation.constraints.child_cannot_prompt_user is true (Codex today). RECOMMENDED uniformly so the orchestrator remains the single approval point across runtimes.

Every agent's Task Report may include a ## Blockers section, placed between ## Task Report and ## Downstream Context:

## Blockers
- BLOCKER: [question the agent cannot resolve]
  Context: [why this question arose]
  Required to proceed: [what answer unlocks continuation]

When parsing an agent response:

1. If ## Blockers is present and non-empty, do NOT call transition_phase. Keep the phase in_progress.
2. Aggregate blockers across the batch (if parallel).
3. Ask the user via the runtime's user-prompt tool.
4. Re-delegate the phase with the answer added to the Context block. The agent re-tries with the new information.
5. On the next return, re-parse and proceed.

An agent that returns neither a handoff nor a blocker is considered incomplete. Invoke the Recovery Protocol in the execution skill.

Validation Criteria Templates

For Implementation Agents (coder, data-engineer, devops-engineer)

Validation: [build command] && [lint command] && [test command]

For Refactoring Agents (refactor)

Validation: [build command] && [test command]
Verify: No behavior changes — all existing tests must still pass

For Test Agents (tester)

Validation: [test command]
Verify: All new tests pass, report coverage metrics

For Assessment Agents (architect, api-designer, code-reviewer, debugger, performance-engineer, security-engineer, seo-specialist, accessibility-specialist, content-strategist, compliance-reviewer)

Validation: N/A (assessment-only — no write tools)
Verify: Findings reference specific files and line numbers

For Documentation Agents (technical-writer, copywriter)

Validation: Verify all links resolve, code examples are syntactically valid

For Design and Product Agents (ux-designer, product-manager)

Validation: N/A (design and requirements artifacts)
Verify: Deliverables reference user needs and acceptance criteria

For Implementation Specialists (analytics-engineer, i18n-specialist, design-system-engineer)

Validation: [build command] && [lint command] && [test command]
Verify: Domain-specific integration validated (tracking fires, locales render, tokens apply)