openclaw - 💡(How to fix) Fix [Feature]: Subagent Workdir Isolation Built-in Prevention

Summary

When a skill spawns multiple subagents that write to shared output directories, OpenClaw should automatically inject workdir isolation to prevent data overwrite. Currently this must be manually handled by the agent via AGENTS.md contracts, which is error-prone and invisible to the system.

Problem to solve

Skills like html-to-one-pptx process many files (e.g., 62 slides) by spawning subagents in parallel. Each subagent writes to tmp/slide_NN/ directories. When two subagents write to the same directory path simultaneously:

• Subagent A writes tmp/slide_01/ (good content)
• Subagent B later writes tmp/slide_01/ (overwrites with bad content)
• Final merge uses the overwritten bad content

Root cause: The skill's internal structure does not declare workdir isolation, and the calling agent must manually create unique WORKDIRs for each subagent. This is invisible to the system and easy to miss.

Proposed solution

Layer 1: Skill Declaration

In SKILL.md, skills that spawn subagents should optionally declare a workdirStrategy:

spec:
  spawnsSubagents: true
  workdirStrategy: mktemp  # "mktemp" | "caller-provided" | "none"

• mktemp: OpenClaw automatically creates a unique /tmp/skill.{slug}.XXXXXX/ directory before spawn
• caller-provided: The skill expects the caller to inject WORKDIR (current behavior, needs manual handling)
• none: No workdir isolation needed

If spawnsSubagents: true but no workdirStrategy declared → warning at install time: "This skill spawns subagents but does not declare workdir isolation. Callers must manually provide unique WORKDIRs."

Layer 2: Automatic Workdir Injection

When workdirStrategy: mktemp is set:

1. Before each sessions_spawn call, OpenClaw automatically:

   • Creates WORKDIR=$(mktemp -d /tmp/skill.{slug}.XXXXXX)
   • Injects WORKDIR into the subagent's task environment
   • The subagent uses this WORKDIR as its output root

2. After all subagents complete, the parent agent receives all WORKDIR paths for merge

Layer 3: Merge Validation

Before merge, OpenClaw verifies:

• All subagent WORKDIRs are unique (no overlap)
• Each WORKDIR contains expected output files
• If overlap detected → block merge with error

Benefits

1. Zero configuration for callers: No need to manually create WORKDIRs in AGENTS.md contracts
2. System-level guarantee: Directory isolation is enforced by the runtime, not left to human memory
3. Backward compatible: Skills without workdirStrategy continue to work (caller-provided mode)
4. Transparent: The mechanism is visible in skill documentation and runtime logs

Example Usage

html-to-one-pptx skill (with this feature):

# SKILL.md
spec:
  spawnsSubagents: true
  workdirStrategy: mktemp

OpenClaw runtime behavior:

# Before spawn
workdir = mktemp("/tmp/html-to-pptx.XXXXXX")
spawn(task="... output to WORKDIR ...", env={WORKDIR: workdir})

# After all complete
verify_no_dir_overlap(all_workdirs)
merge_slides.py --dir dir1 --dir dir2 ... --out final.pptx

Alternatives considered

See AGENTS.md → "Subagent Directory Safety Rule" section. This is fragile because:

• It's a contract, not a system guarantee
• The AI must remember to apply it every time
• No runtime enforcement if missed

Impact

## Subagent Directory Safety Rule
- Trigger: any skill call with sessions_spawn
- L1: Scan SKILL.md for mktemp/WORKDIR declaration
- L2: Manually create WORKDIR before spawn
- L3: Verify no overlap before merge

### Evidence/examples

_No response_

### Additional information

_No response_